Added maestro code examples (#142)

* added examples

* updates and fixes

* remove redundant scope

* update example 1

* adding codeDepot markers

---------

Co-authored-by: Paige Rossi <paige.rossi@docusign.com>

Author: RomanBachaloSigmaSoftware

.gitignore

@@ -123,3 +123,6 @@ private.key
 # Current flask session
 
 flask_session/
+
+# Workflow ID file
+WORKFLOW_ID.txt

app/__init__.py

@@ -12,6 +12,7 @@
 from .monitor import views as monitor_views
 from .admin import views as admin_views
 from .connect import views as connect_views
+from .maestro import views as maestro_views
 from .webforms import views as webforms_views
 from .views import core
 
@@ -114,6 +115,10 @@
 
 app.register_blueprint(connect_views.cneg001)
 
+app.register_blueprint(maestro_views.mseg001)
+app.register_blueprint(maestro_views.mseg002)
+app.register_blueprint(maestro_views.mseg003)
+
 app.register_blueprint(webforms_views.weg001)
 
 if "DYNO" in os.environ:  # On Heroku?

app/consts.py

@@ -29,6 +29,8 @@
 # Base uri for callback function
 base_uri_suffix = "/restapi"
 
+# Workflow name
+workflow_name = "Example workflow - send invite to signer"
 
 # Default languages for brand
 languages = {
@@ -114,5 +116,6 @@
     "ROOMS": "Rooms",
     "ADMIN": "Admin",
     "CONNECT": "Connect",
+    "MAESTRO": "Maestro",
     "WEBFORMS": "WebForms"
 }

app/docusign/ds_client.py

@@ -33,6 +33,10 @@
     "asset_group_account_read", "asset_group_account_clone_write", "asset_group_account_clone_read"
 ]
 
+MAESTRO_SCOPES = [
+    "signature", "aow_manage"
+]
+
 WEBFORMS_SCOPES = [
     "signature", "webforms_read", "webforms_instance_read", "webforms_instance_write"
 ]
@@ -61,6 +65,8 @@ def _auth_code_grant(cls, api):
             use_scopes.extend(CLICK_SCOPES)
         elif api == "Admin":
             use_scopes.extend(ADMIN_SCOPES)
+        elif api == "Maestro":
+            use_scopes.extend(MAESTRO_SCOPES)
         elif api == "WebForms":
             use_scopes.extend(WEBFORMS_SCOPES)
         else:
@@ -99,6 +105,8 @@ def _jwt_auth(cls, api):
             use_scopes.extend(CLICK_SCOPES)
         elif api == "Admin":
             use_scopes.extend(ADMIN_SCOPES)
+        elif api == "Maestro":
+            use_scopes.extend(MAESTRO_SCOPES)
         elif api == "WebForms":
             use_scopes.extend(WEBFORMS_SCOPES)
         else:

app/docusign/utils.py

@@ -1,7 +1,7 @@
 from datetime import timedelta, datetime
 from functools import wraps
 import requests
-import urllib
+from urllib.parse import urlparse, parse_qs
 import json
 import re
 
@@ -148,6 +148,16 @@ def get_user_info(access_token, base_path, oauth_host_name):
     api_client.set_oauth_host_name(oauth_host_name)
     return api_client.get_user_info(access_token)
 
+def get_parameter_value_from_url(url, param_name):
+    parsed_url = urlparse(url)
+    query_params = parse_qs(parsed_url.query)
+
+    # Access the parameter value (returns a list)
+    param_value_list = query_params.get(param_name, [])
+
+    # If the parameter exists, return the first value; otherwise, return None
+    return param_value_list[0] if param_value_list else None
+
 def replace_template_id(file_path, template_id):
     with open(file_path, 'r') as file:
         content = file.read()

app/ds_config_sample.py

@@ -16,6 +16,7 @@
     "rooms_api_client_host": "https://demo.rooms.docusign.com/restapi",
     "monitor_api_client_host": "https://lens-d.docusign.net",
     "admin_api_client_host": "https://api-d.docusign.net/management",
+    "maestro_api_client_host": "https://demo.services.docusign.net/",
     "webforms_api_client_host": "https://apps-d.docusign.com/api/webforms/v1.1",
     "allow_silent_authentication": True,  # a user can be silently authenticated if they have an
     # active login session on another tab of the same browser

app/maestro/__init__.py

@@ -0,0 +1,3 @@
+from .views import mseg001
+from .views import mseg002
+from .views import mseg003

app/maestro/examples/eg001_trigger_workflow.py

@@ -0,0 +1,75 @@
+from docusign_maestro import WorkflowManagementApi, WorkflowTriggerApi, TriggerPayload
+from flask import session, request
+
+from app.docusign.utils import get_parameter_value_from_url
+from app.ds_config import DS_CONFIG
+from app.maestro.utils import create_maestro_api_client
+from app.consts import pattern
+
+
+class Eg001TriggerWorkflowController:
+    @staticmethod
+    def get_args():
+        """Get request and session arguments"""
+        return {
+            "account_id": session["ds_account_id"],
+            "base_path": DS_CONFIG["maestro_api_client_host"],
+            "access_token": session["ds_access_token"],
+            "workflow_id": session["workflow_id"],
+            "instance_name": pattern.sub("", request.form.get("instance_name")),
+            "signer_email": pattern.sub("", request.form.get("signer_email")),
+            "signer_name": pattern.sub("", request.form.get("signer_name")),
+            "cc_email": pattern.sub("", request.form.get("cc_email")),
+            "cc_name": pattern.sub("", request.form.get("cc_name")),
+        }
+    
+    @staticmethod
+    def get_workflow_definitions(args):
+        api_client = create_maestro_api_client(args["base_path"], args["access_token"])
+        workflow_management_api = WorkflowManagementApi(api_client)
+        workflow_definitions = workflow_management_api.get_workflow_definitions(args["account_id"], status="active")
+
+        return workflow_definitions
+    
+    @staticmethod
+    def get_workflow_definition(args):
+        #ds-snippet-start:Maestro1Step2
+        api_client = create_maestro_api_client(args["base_path"], args["access_token"])
+        #ds-snippet-end:Maestro1Step2
+
+        #ds-snippet-start:Maestro1Step3
+        workflow_management_api = WorkflowManagementApi(api_client)
+        workflow_definition = workflow_management_api.get_workflow_definition(args["account_id"], args["workflow_id"])
+        #ds-snippet-end:Maestro1Step3
+
+        return workflow_definition
+
+    @staticmethod
+    def trigger_workflow(workflow, args):
+        api_client = create_maestro_api_client(args["base_path"], args["access_token"])
+
+        #ds-snippet-start:Maestro1Step4
+        trigger_payload = TriggerPayload(
+            instance_name=args["instance_name"],
+            participant={},
+            payload={
+                "signerEmail": args["signer_email"],
+                "signerName": args["signer_name"],
+                "ccEmail": args["cc_email"],
+                "ccName": args["cc_name"]
+            },
+            metadata={}
+        )
+        mtid = get_parameter_value_from_url(workflow.trigger_url, "mtid")
+        mtsec = get_parameter_value_from_url(workflow.trigger_url, "mtsec")
+        #ds-snippet-end:Maestro1Step4
+
+        #ds-snippet-start:Maestro1Step5
+        workflow_trigger_api = WorkflowTriggerApi(api_client)
+        trigger_response = workflow_trigger_api.trigger_workflow(
+            args["account_id"],
+            trigger_payload,
+            mtid=mtid, mtsec=mtsec
+        )
+        #ds-snippet-end:Maestro1Step5
+        return trigger_response

app/maestro/examples/eg002_cancel_workflow.py

@@ -0,0 +1,45 @@
+from docusign_maestro import WorkflowInstanceManagementApi
+from flask import session
+
+from app.ds_config import DS_CONFIG
+from app.maestro.utils import create_maestro_api_client
+
+
+class Eg002CancelWorkflowController:
+    @staticmethod
+    def get_args():
+        """Get request and session arguments"""
+        return {
+            "account_id": session["ds_account_id"],
+            "base_path": DS_CONFIG["maestro_api_client_host"],
+            "access_token": session["ds_access_token"],
+            "workflow_id": session["workflow_id"],
+            "instance_id": session["instance_id"]
+        }
+    
+    @staticmethod
+    def get_instance_state(args):
+        api_client = create_maestro_api_client(args["base_path"], args["access_token"])
+        workflow_instance_management_api = WorkflowInstanceManagementApi(api_client)
+        instance = workflow_instance_management_api.get_workflow_instance(
+            args["account_id"],
+            args["workflow_id"],
+            args["instance_id"]
+        )
+
+        return instance.instance_state
+    
+    @staticmethod
+    def cancel_workflow_instance(args):
+        #ds-snippet-start:Maestro2Step2
+        api_client = create_maestro_api_client(args["base_path"], args["access_token"])
+        #ds-snippet-end:Maestro2Step2
+
+        #ds-snippet-start:Maestro2Step3
+        workflow_instance_management_api = WorkflowInstanceManagementApi(api_client)
+        cancel_result = workflow_instance_management_api.cancel_workflow_instance(
+            args["account_id"],
+            args["instance_id"]
+        )
+        #ds-snippet-end:Maestro2Step3
+        return cancel_result

app/maestro/examples/eg003_get_workflow_status.py

@@ -0,0 +1,35 @@
+from docusign_maestro import WorkflowInstanceManagementApi
+from flask import session
+
+from app.ds_config import DS_CONFIG
+from app.maestro.utils import create_maestro_api_client
+
+
+class Eg003GetWorkflowStatusController:
+    @staticmethod
+    def get_args():
+        """Get request and session arguments"""
+        return {
+            "account_id": session["ds_account_id"],
+            "base_path": DS_CONFIG["maestro_api_client_host"],
+            "access_token": session["ds_access_token"],
+            "workflow_id": session["workflow_id"],
+            "instance_id": session["instance_id"]
+        }
+    
+    @staticmethod
+    def get_workflow_instance(args):
+        #ds-snippet-start:Maestro3Step2
+        api_client = create_maestro_api_client(args["base_path"], args["access_token"])
+        #ds-snippet-end:Maestro3Step2
+
+        #ds-snippet-start:Maestro3Step3
+        workflow_instance_management_api = WorkflowInstanceManagementApi(api_client)
+        instance = workflow_instance_management_api.get_workflow_instance(
+            args["account_id"],
+            args["workflow_id"],
+            args["instance_id"]
+        )
+        #ds-snippet-end:Maestro3Step3
+
+        return instance