Blog
Home/

Common API Tasks🐈: List all your Maestro workflows using the Maestro API

Author Inbar Gazit
Inbar GazitSr. Manager, Developer Content
Summary3 min read

Discover the Maestro API and see how to use it to retrieve a list of all your Maestro workflows with examples in all our supported SDK languages.

    • Docusign Maestro
    • Maestro API
    • C#
    • Java
    • Node.js
    • PHP
    • Python
    • Ruby
    • Additional resources

    Table of contents

    Welcome to an marvelous new edition of the CAT🐈 (Common API Tasks) blog series. The CAT blogs provide all you need to complete small, specific, SDK-supported tasks using one of our APIs. You can find all articles in this series on the DocuSign Developer Blog.

    Last month we made an exciting new announcement about Docusign IAM for Developers being in open beta. The cat🐈is now out of the bag (sorry, couldn’t help myself). Included in Docusign IAM for developers is a brand-new API called the Maestro API. This is the first time that I'm writing to show you how to use the Maestro API. 

    Docusign Maestro

    Docusign Maestro is a brand-new offering from Docusign that is part of the new Intelligent Agreement Management set of capabilities that are now available for all Docusign customers to use. The promise of Docusign Maestro is that it can improve all processes around agreements and shorten the time it takes to get things done. It’s all about automation and data flow. Maestro has a designer that might be familiar to users of products such as Microsoft Power Automate or Zapier (and many others). You can use that designer to build custom workflows that can be executed repeatedly to improve the efficiency of processes for both your company and your customers. Maestro can also be extended: that is to say, the set of capabilities available as part of Docusign Maestro is not limited to what Docusign is building. Developers such as yourself can build extension apps that can provide additional functionality for Maestro. The possibilities are limitless.

    Maestro API

    The Maestro API is one of the newest APIs built by Docusign and supports most things that the Maestro application supports. However, as of the writing of this blog post (June 2024) the API is still in beta, which means that potential issues may exist. Note: There’s an extra layer of consent to keep in mind. As the Maestro app itself was built using the eSignature REST API and Authentication Code Grant, there’s a consent required for both the Maestro app as well as any app you build using the Maestro API. Both consents are only required once, but both still must be done manually by a user of the application. Also: We do provide SDKs for the Maestro API in six languages, and they’re compatible with our other SDKs for other APIs

    Now let’s discuss this specific scenario. The code snippet I’m going to show you is simple. What it does is fetch all your workflows using the getWorkflowDefinitions() endpoint. This will provide a list of workflows. However, it’s important to mention that a workflow must be published before it can be used. You can filter this list by requesting only published or unpublished workflows based on your needs. 

    One last note: You must specify a different scope, aow_manage, when you obtain your access token when using the Maestro API. Please make sure to add that scope or you will get a 404 error from the API call. 

    C#

    var docuSignClient = new DocuSignClient(basePath);
    // You will need to obtain an access token using your chosen authentication method
    docuSignClient.Configuration.DefaultHeader.Add("Authorization", "Bearer " + accessToken);
    var workflowManagementApi = new WorkflowManagementApi(docuSignClient);
    WorkflowDefinitionList workflows = workflowManagementApi.GetWorkflowDefinitions(accountId);
    foreach (WorkflowDefinitionMetadata workflowDefinition in workflows.Value)
    {
      Console.WriteLine(workflowDefinition.Name);
    }
    
    

    Java

    Configuration config = new Configuration(new ApiClient(basePath));
    // You will need to obtain an access token using your chosen authentication method
    config.addDefaultHeader("Authorization", "Bearer " + accessToken);
    var workflowManagementApi = new WorkflowManagementApi(apiClient);
    WorkflowDefinitionList workflows = workflowManagementApi.getWorkflowDefinitions(accountId);
    for (WorkflowDefinitionMetadata workflowDefinition in workflows.getValue())
    {
      System.out.printLn(workflowDefinition.getName());
    }
    
    

    Node.js

    let dsApiClient = new docusign.ApiClient();
    dsApiClient.setBasePath(basePath);
    // You will need to obtain an access token using your chosen authentication method
    dsApiClient.addDefaultHeader('Authorization', 'Bearer ' + accessToken);  
    let workflowManagementApi = new docusign.WorkflowManagementApi(dsApiClient);
    let workflows = workflowManagementApi.getWorkflowDefinitions(accountId);
    workflows.value.forEach((workflowDefinition) => console.log(workflowDefinition.name));
    
    

    PHP

    $api_client = new \DocuSign\eSign\client\ApiClient($base_path);
    $config = new \DocuSign\eSign\Model\Configuration($api_client);
    # You will need to obtain an access token using your chosen authentication method
    $config->addDefaultHeader('Authorization', 'Bearer ' + $access_token);
    $workflow_management_api = new \DocuSign\eSign\Api\EnvelopesApi($api_client);
    $workflows = $workflow_management_api->getWorkflowDefinitions($account_id);
    foreach ($workflows['value'] as $workflow_definition)
    {
      echo $workflow_definition['value'];
    }
    
    

    Python

    api_client = ApiClient()
    # You will need to obtain an access token using your chosen authentication method
    api_client.set_default_header('Authorization', 'Bearer ' + access_token)
    workflow_management_api = WorkflowManagementApi(api_client)
    workflows = workflow_management_api.get_workflow_definition(account_id)
    for workflow_definitnion in workflows.value:
      print(workflow_definition.name)
    
    

    Ruby

    config = DocuSign_eSign::Configuration.new
    config.host = base_path
    api_client = DocuSign_eSign::ApiClient.new config
    # You will need to obtain an access token using your chosen authentication method
    api_client.DefaultHeader['Authorization'] = 'Bearer ' + access_token
    workflow_management_api = WorkflowManagementApi(api_client)
    workflows = workflow_management_api.get_workflow_definition(account_id)
    for workflow_definitnion in workflows.value
      print(workflow_definition.name)
    end
    
    

    That’s all, folks! I hope you found it useful. If you have any questions, comments, or suggestions for topics for future Common API Tasks posts, feel free to email me. Until next time…

    Additional resources

    Author Inbar Gazit
    Inbar GazitSr. Manager, Developer Content

    Inbar Gazit has been with Docusign since 2013 in various engineering roles. Since 2019 he has focused on developer content. Inbar works on code examples including the launchers, available on GitHub in eight languages, and helps build sample apps showcasing the various Docusign APIs. He is also active on StackOverflow, answering your questions. Inbar can be reached at inbar.gazit@docusign.com.

    More posts from this author

    Related posts

    • Common API Tasks🐈: Download a document that is part of an eSignature template
      Common API Tasks

      Common API Tasks🐈: Download a document that is part of an eSignature template

      Author Inbar Gazit
      Inbar Gazit
    • Common API Tasks🐈: Find a web form by name

      Common API Tasks🐈: Find a web form by name

      Author Inbar Gazit
      Inbar Gazit
    • Common API Tasks🐈: Check if your access token has expired

      Common API Tasks🐈: Check if your access token has expired

      Author Inbar Gazit
      Inbar Gazit
    Common API Tasks🐈: Find a web form by name

    Common API Tasks🐈: Find a web form by name

    Author Inbar Gazit
    Inbar Gazit
    Common API Tasks🐈: Check if your access token has expired

    Common API Tasks🐈: Check if your access token has expired

    Author Inbar Gazit
    Inbar Gazit

    Discover what's new with Docusign IAM or start with eSignature for free

    Explore Docusign IAMTry eSignature for Free
    Person smiling while presenting