Merge pull request #120 from docusign/feature/shared-access-example

raileendr · web-flow · commit 21c2f6aaa944 · 2023-05-19T08:09:13.000-07:00
Shared access code example
diff --git a/app/__init__.py b/app/__init__.py
@@ -105,6 +105,7 @@
 app.register_blueprint(esignature_views.eg040)
 app.register_blueprint(esignature_views.eg041)
 app.register_blueprint(esignature_views.eg042)
+app.register_blueprint(esignature_views.eg043)
 
 if "DYNO" in os.environ:  # On Heroku?
     import logging
diff --git a/app/docusign/__init__.py b/app/docusign/__init__.py
@@ -1,2 +1,3 @@
 from .ds_client import DSClient
-from .utils import ds_token_ok, create_api_client, authenticate, ensure_manifest, get_example_by_number, get_manifest
+from .utils import ds_token_ok, create_api_client, authenticate, ensure_manifest, get_example_by_number, get_manifest, \
+    get_user_info
diff --git a/app/docusign/utils.py b/app/docusign/utils.py
@@ -101,6 +101,21 @@ def wrapper(*args, **kwargs):
 
     return decorator
 
+def authenticate_agent(eg):
+    def decorator(func):
+        @wraps(func)
+        def wrapper(*args, **kwargs):
+            session["eg"] = url_for(eg + ".list_envelopes")
+
+            if ds_token_ok(minimum_buffer_min):
+                return func(*args, **kwargs)
+            else:
+                return redirect(url_for("ds.ds_must_authenticate"))
+
+        return wrapper
+
+    return decorator
+
 def ensure_manifest(manifest_url):
     def decorator(func):
         @wraps(func)
@@ -127,3 +142,7 @@ def is_cfr(accessToken, accountId, basePath):
     
     return account_details.status21_cfr_part11
 
+def get_user_info(access_token, base_path, oauth_host_name):
+    api_client = create_api_client(base_path, access_token)
+    api_client.set_oauth_host_name(oauth_host_name)
+    return api_client.get_user_info(access_token)
diff --git a/app/eSignature/examples/eg043_shared_access.py b/app/eSignature/examples/eg043_shared_access.py
@@ -0,0 +1,82 @@
+import json
+
+from docusign_esign import EnvelopesApi, UsersApi, AccountsApi, NewUsersDefinition, UserInformation, \
+    UserAuthorizationCreateRequest, AuthorizationUser, ApiException
+from datetime import datetime, timedelta
+
+from ...docusign import create_api_client
+
+
+class Eg043SharedAccessController:
+    @classmethod
+    def create_agent(cls, args):
+        api_client = create_api_client(base_path=args["base_path"], access_token=args["access_token"])
+        users_api = UsersApi(api_client)
+
+        # check if agent already exists
+        try:
+            users = users_api.list(args["account_id"], email=args["email"], status="Active")
+            if int(users.result_set_size) > 0:
+                return users.users[0]
+
+        except ApiException as err:
+            error_body_json = err and hasattr(err, "body") and err.body
+            error_body = json.loads(error_body_json)
+            error_code = error_body and "errorCode" in error_body and error_body["errorCode"]
+
+            user_not_found_error_codes = ["USER_NOT_FOUND", "USER_LACKS_MEMBERSHIP"]
+            if error_code not in user_not_found_error_codes:
+                raise err
+
+        # create new agent
+        new_users = users_api.create(args["account_id"], new_users_definition=cls.new_users_definition(args))
+        return new_users.new_users[0]
+
+    @classmethod
+    def create_authorization(cls, args):
+        api_client = create_api_client(base_path=args["base_path"], access_token=args["access_token"])
+        accounts_api = AccountsApi(api_client)
+
+        # check if authorization with manage permission already exists
+        authorizations = accounts_api.get_agent_user_authorizations(
+            args["account_id"],
+            args["agent_user_id"],
+            permissions="manage"
+        )
+        if int(authorizations.result_set_size) > 0:
+            return
+
+        # create authorization
+        return accounts_api.create_user_authorization(
+            args["account_id"],
+            args["user_id"],
+            user_authorization_create_request=cls.user_authorization_request(args)
+        )
+
+    @classmethod
+    def new_users_definition(cls, args):
+        agent = UserInformation(
+            user_name=args["user_name"],
+            email=args["email"],
+            activation_access_code=args["activation"]
+        )
+        return NewUsersDefinition(new_users=[agent])
+
+    @classmethod
+    def user_authorization_request(cls, args):
+        return UserAuthorizationCreateRequest(
+            agent_user=AuthorizationUser(
+                account_id=args["account_id"],
+                user_id=args["agent_user_id"]
+            ),
+            permission="manage"
+        )
+
+    @classmethod
+    def get_envelopes(cls, args):
+        api_client = create_api_client(base_path=args["base_path"], access_token=args["access_token"])
+        api_client.set_default_header("X-DocuSign-Act-On-Behalf", args["user_id"])
+        envelopes_api = EnvelopesApi(api_client)
+
+        from_date = (datetime.utcnow() - timedelta(days=10)).isoformat()
+        return envelopes_api.list_status_changes(account_id=args["account_id"], from_date=from_date)
diff --git a/app/eSignature/views/__init__.py b/app/eSignature/views/__init__.py
@@ -39,3 +39,4 @@
 from .eg040_document_visibility import eg040
 from .eg041_cfr_embedded_signing import eg041
 from .eg042_document_generation import eg042
+from .eg043_shared_access import eg043
diff --git a/app/eSignature/views/eg043_shared_access.py b/app/eSignature/views/eg043_shared_access.py
@@ -0,0 +1,159 @@
+""" Example 043: Share access to a DocuSign envelope inbox """
+
+import json
+
+from docusign_esign.client.api_exception import ApiException
+from flask import render_template, session, Blueprint, redirect, current_app, url_for, request
+
+from ..examples.eg043_shared_access import Eg043SharedAccessController
+from ...docusign import authenticate, ensure_manifest, get_example_by_number, get_user_info
+from ...docusign.utils import ds_logout_internal, authenticate_agent
+from ...ds_config import DS_CONFIG, DS_JWT
+from ...error_handlers import process_error
+from ...consts import pattern, API_TYPE
+
+example_number = 43
+api = API_TYPE["ESIGNATURE"]
+eg = f"eg0{example_number}"  # reference (and url) for this example
+eg043 = Blueprint(eg, __name__)
+
+
+@eg043.route(f"/{eg}", methods=["POST"])
+@authenticate(eg=eg, api=api)
+@ensure_manifest(manifest_url=DS_CONFIG["example_manifest_url"])
+def create_agent():
+    args = {
+        "account_id": session["ds_account_id"],
+        "base_path": session["ds_base_path"],
+        "access_token": session["ds_access_token"],
+        "email": request.form.get("email"),
+        "user_name": pattern.sub("", request.form.get("user_name")),
+        "activation": pattern.sub("", request.form.get("activation"))
+    }
+    try:
+        # 1. Create the agent user
+        results = Eg043SharedAccessController.create_agent(args)
+    except ApiException as err:
+        return process_error(err)
+
+    session["agent_user_id"] = results.user_id
+
+    example = get_example_by_number(session["manifest"], example_number, api)
+    return render_template(
+        "example_done.html",
+        title="Agent user created",
+        message=example["ResultsPageText"],
+        json=json.dumps(json.dumps(results.to_dict())),
+        redirect_url=f"/{eg}auth"
+    )
+
+
+@eg043.route(f"/{eg}auth", methods=["GET"])
+@authenticate(eg=eg, api=api)
+@ensure_manifest(manifest_url=DS_CONFIG["example_manifest_url"])
+def create_authorization():
+    user_info = get_user_info(
+        session["ds_access_token"],
+        session["ds_base_path"],
+        DS_CONFIG["authorization_server"].replace("https://", "")
+    )
+    args = {
+        "account_id": session["ds_account_id"],
+        "base_path": session["ds_base_path"],
+        "access_token": session["ds_access_token"],
+        "user_id": user_info.sub,
+        "agent_user_id": session["agent_user_id"]
+    }
+    try:
+        # 2. Create the authorization for agent user
+        Eg043SharedAccessController.create_authorization(args)
+    except ApiException as err:
+        error_body_json = err and hasattr(err, "body") and err.body
+        error_body = json.loads(error_body_json)
+        error_code = error_body and "errorCode" in error_body and error_body["errorCode"]
+        if error_code == "USER_NOT_FOUND":
+            example = get_example_by_number(session["manifest"], example_number, api)
+            additional_page_data = next((p for p in example["AdditionalPage"] if p["Name"] == "user_not_found"),
+                                        None)
+            return render_template(
+                "example_done.html",
+                title="Agent user created",
+                message=additional_page_data["ResultsPageText"],
+                redirect_url=f"/{eg}auth"
+            )
+
+        return process_error(err)
+
+    session["principal_user_id"] = user_info.sub
+
+    example = get_example_by_number(session["manifest"], example_number, api)
+    additional_page_data = next((p for p in example["AdditionalPage"] if p["Name"] == "authenticate_as_agent"), None)
+    return render_template(
+        "example_done.html",
+        title="Authenticate as the agent",
+        message=additional_page_data["ResultsPageText"],
+        redirect_url=f"/{eg}reauthenticate"
+    )
+
+
+@eg043.route(f"/{eg}reauthenticate", methods=["GET"])
+def reauthenticate():
+    # 3. Logout principal user and redirect to page with the list of envelopes, login as agent user
+    ds_logout_internal()
+    current_app.config["isLoggedIn"] = False
+    return redirect(url_for(f"{eg}.list_envelopes"))
+
+
+@eg043.route(f"/{eg}envelopes", methods=["GET"])
+@ensure_manifest(manifest_url=DS_CONFIG["example_manifest_url"])
+@authenticate_agent(eg=eg)
+def list_envelopes():
+    args = {
+        "account_id": session["ds_account_id"],
+        "base_path": session["ds_base_path"],
+        "access_token": session["ds_access_token"],
+        "user_id": session["principal_user_id"]
+    }
+    try:
+        # 4. Retrieve the list of envelopes
+        results = Eg043SharedAccessController.get_envelopes(args)
+    except ApiException as err:
+        return process_error(err)
+
+    example = get_example_by_number(session["manifest"], example_number, api)
+
+    if int(results.result_set_size) > 0:
+        additional_page = next((p for p in example["AdditionalPage"] if p["Name"] == "list_status_successful"), None)
+        return render_template(
+            "example_done.html",
+            title="Principal's envelopes visible in the agent's Shared Access UI",
+            message=additional_page["ResultsPageText"],
+            json=json.dumps(json.dumps(results.to_dict()))
+        )
+
+    additional_page = next((p for p in example["AdditionalPage"] if p["Name"] == "list_status_unsuccessful"), None)
+    return render_template(
+        "example_done.html",
+        title="No envelopes in the principal user's account",
+        message=additional_page["ResultsPageText"]
+    )
+
+
+@eg043.route(f"/{eg}", methods=["GET"])
+@ensure_manifest(manifest_url=DS_CONFIG["example_manifest_url"])
+@authenticate(eg=eg, api=api)
+def get_view():
+    """responds with the form for the example"""
+    example = get_example_by_number(session["manifest"], example_number, api)
+
+    return render_template(
+        "eSignature/eg043_shared_access.html",
+        title=example["ExampleName"],
+        example=example,
+        source_file="eg043_shared_access.py",
+        source_url=DS_CONFIG["github_example_url"] + "eg043_shared_access.py",
+        documentation=DS_CONFIG["documentation"] + eg,
+        show_doc=DS_CONFIG["documentation"],
+        signer_name=DS_CONFIG["signer_name"],
+        signer_email=DS_CONFIG["signer_email"]
+    )
diff --git a/app/templates/eSignature/eg043_shared_access.html b/app/templates/eSignature/eg043_shared_access.html
@@ -0,0 +1,35 @@
+<!-- extend base layout --> {% extends "base.html" %}  {% block content %}
+
+{% include 'example_info.html' %}
+
+{%  set form_index = 0 %}
+{%  set email_index = 0 %}
+{%  set username_index = 1 %}
+{%  set activation_index = 2 %}
+
+<form class="eg" action="" method="post" data-busy="form">
+    {% if 'FormName' in example['Forms'][form_index] %}
+        <p>{{ example['Forms'][form_index]['FormName'] | safe }}</p>
+    {% endif %}
+    <div class="form-group">
+      <label for="email">{{ example['Forms'][form_index]['Inputs'][email_index]['InputName'] }}</label>
+      <input type="email" class="form-control" id="email" name="email"
+             aria-describedby="emailHelp" placeholder="{{ example['Forms'][form_index]['Inputs'][email_index]['InputPlaceholder'] }}" required>
+    </div>
+    <div class="form-group">
+      <label for="user_name">{{ example['Forms'][form_index]['Inputs'][username_index]['InputName'] }}</label>
+      <input type="text" class="form-control" id="user_name" placeholder="{{ example['Forms'][form_index]['Inputs'][username_index]['InputPlaceholder'] }}" name="user_name"
+             required>
+    </div>
+    <div class="form-group">
+      <label for="activation">{{ example['Forms'][form_index]['Inputs'][activation_index]['InputName'] }}</label>
+      <input type="text" class="form-control" id="activation" name="activation"
+             placeholder="{{ example['Forms'][form_index]['Inputs'][activation_index]['InputPlaceholder'] }}" required>
+      <small id="activationHelp" class="form-text text-muted">{{ session['manifest']['SupportingTexts']['HelpingTexts']['SaveAgentActivationCode'] | safe}}</small>
+    </div>
+
+    <input type="hidden" name="csrf_token" value="{{ csrf_token() }}">
+    {% include 'submit_button.html' %}
+</form>
+
+{% endblock %}
diff --git a/app/templates/example_done.html b/app/templates/example_done.html
@@ -17,6 +17,10 @@ <h2>{{ title }}</h2>
     </ul>
 {% endif %}
 
-<p><a href="/">Continue</a></p>
-  
+{% if redirect_url %}
+    <p><a href="{{ redirect_url }}">Continue</a></p>
+{% else %}
+    <p><a href="/">Continue</a></p>
+{% endif %}
+
 {% endblock %}
diff --git a/requirements.txt b/requirements.txt
@@ -4,7 +4,7 @@ cffi==1.15.1
 chardet==5.1.0
 Click
 cryptography==39.0.0
-docusign-esign==3.21.0
+docusign-esign==3.22.0
 docusign-rooms==1.1.0
 docusign-monitor==1.1.0
 docusign-click==1.2.2
