Common API Tasks🐈: List all your Maestro workflows using the Maestro API
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…
