added example

Author: RomanBachaloSigmaSoftware

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

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)

app/eSignature/examples/eg043_shared_access.py

@@ -0,0 +1,56 @@
+from flask import session, request
+from docusign_esign import EnvelopesApi, UsersApi, AccountsApi, NewUsersDefinition, UserInformation,\
+    UserAuthorizationCreateRequest, AuthorizationUser
+from datetime import datetime, timedelta
+
+from ...consts import pattern
+from ...ds_config import DS_JWT
+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)
+
+        return users_api.create(args["account_id"], new_users_definition=cls.new_users_definition(args))
+
+    @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)
+
+        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=30)).isoformat()
+        return envelopes_api.list_status_changes(account_id=args["account_id"], from_date=from_date)

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

app/eSignature/views/eg043_shared_access.py

@@ -0,0 +1,136 @@
+""" 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
+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": pattern.sub("", 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.new_users[0].user_id
+
+    example = get_example_by_number(session["manifest"], example_number, api)
+    return render_template(
+        "eSignature/eg043_shared_access/eg043_shared_access_agent_created.html",
+        title="Agent user created",
+        message=example["ResultsPageText"],
+        json=json.dumps(json.dumps(results.to_dict()))
+    )
+
+
+@eg043.route(f"/{eg}auth", methods=["GET"])
+@authenticate(eg=eg, api=api)
+@ensure_manifest(manifest_url=DS_CONFIG["example_manifest_url"])
+def create_authorization():
+    args = {
+        "account_id": session["ds_account_id"],
+        "base_path": session["ds_base_path"],
+        "access_token": session["ds_access_token"],
+        "user_id": DS_JWT["ds_impersonated_user_id"],
+        "agent_user_id": session["agent_user_id"]
+    }
+    try:
+        # 2. Create the authorization for agent user
+        Eg043SharedAccessController.create_authorization(args)
+    except ApiException as err:
+        return process_error(err)
+
+    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(
+        "eSignature/eg043_shared_access/eg043_shared_access_reauthenticate.html",
+        title="Authenticate as the agent",
+        message=additional_page_data["ResultsPageText"]
+    )
+
+
+@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": DS_JWT["ds_impersonated_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/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"]
+    )

app/templates/eSignature/eg043_shared_access/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 %}

app/templates/eSignature/eg043_shared_access/eg043_shared_access_agent_created.html

@@ -0,0 +1,14 @@
+<!-- extend base layout --> {% extends "base.html" %}  {% block content %}
+
+<h2>{{ title }}</h2>
+<p>{{ message | safe }}</p>
+
+{% if json %}
+  <!-- Data from the server -->
+  <div id="server_json_data" data-server-json-data='{"json": {{ json | safe }} }' class="hidden"></div>
+  <p><pre class="json-display"><code id="json-display"></code></pre></p>
+{%  endif %}
+
+<p><a href="/eg043auth">Continue</a></p>
+
+{% endblock %}

app/templates/eSignature/eg043_shared_access/eg043_shared_access_reauthenticate.html

@@ -0,0 +1,8 @@
+<!-- extend base layout --> {% extends "base.html" %}  {% block content %}
+
+<h2>{{ title }}</h2>
+<p>{{ message | safe }}</p>
+
+<p><a href="/eg043reauthenticate">Continue</a></p>
+
+{% endblock %}

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