Document generation code example (#116)

RomanBachaloSigmaSoftware · paigesrossi · web-flow · commit 2019c8c424f1 · 2023-04-20T18:18:57.000-07:00
* added example

* updated example

* update doc gen code example

* removing extra fields

* adding step comments

---------

Co-authored-by: Paige Rossi &lt;paige.rossi@docusign.com&gt;
diff --git a/app/__init__.py b/app/__init__.py
@@ -104,6 +104,7 @@
 app.register_blueprint(esignature_views.eg039)
 app.register_blueprint(esignature_views.eg040)
 app.register_blueprint(esignature_views.eg041)
+app.register_blueprint(esignature_views.eg042)
 
 if "DYNO" in os.environ:  # On Heroku?
     import logging
diff --git a/app/ds_config_sample.py b/app/ds_config_sample.py
@@ -26,6 +26,7 @@
     "doc_pdf": "World_Wide_Corp_lorem.pdf",
     "doc_terms_pdf": "Term_Of_Service.pdf",
     "doc_txt": "Welcome.txt",
+    "doc_offer_letter": "Offer_Letter_Demo.docx",
     # Payment gateway information is optional
     "gateway_account_id": "{DS_PAYMENT_GATEWAY_ID}",
     "gateway_name": "stripe",
diff --git a/app/eSignature/examples/eg042_document_generation.py b/app/eSignature/examples/eg042_document_generation.py
@@ -0,0 +1,231 @@
+import base64
+from flask import session, request
+from os import path
+from docusign_esign import EnvelopesApi, TemplatesApi, EnvelopeDefinition, Document, Signer, SignHere, \
+    DateSigned, Tabs, Recipients, DocGenFormField, EnvelopeTemplate, TemplateRole, DocGenFormFields, \
+    DocGenFormFieldRequest, Envelope
+
+from ...consts import demo_docs_path, pattern
+from ...ds_config import DS_CONFIG
+from ...docusign import create_api_client
+
+
+class Eg042DocumentGenerationController:
+    @staticmethod
+    def get_args():
+        """Get request and session arguments"""
+        envelope_args = {
+            "candidate_email": pattern.sub("", request.form.get("candidate_email")),
+            "candidate_name": pattern.sub("", request.form.get("candidate_name")),
+            "manager_name": pattern.sub("", request.form.get("manager_name")),
+            "job_title": pattern.sub("", request.form.get("job_title")),
+            "salary": pattern.sub("", request.form.get("salary")),
+            "start_date": pattern.sub("", request.form.get("start_date")),
+            "doc_file": path.join(demo_docs_path, DS_CONFIG["doc_offer_letter"])
+        }
+        args = {
+            "account_id": session["ds_account_id"],
+            "base_path": session["ds_base_path"],
+            "access_token": session["ds_access_token"],
+            "envelope_args": envelope_args
+        }
+        return args
+
+    @classmethod
+    def worker(cls, args):
+        """
+        1. Create the template
+        2. Update template document
+        3. Update recipient tabs
+        4. Create draft envelope
+        5. Get the document id
+        6. Merge the data fields
+        7. Send the envelope
+        """
+
+        api_client = create_api_client(base_path=args["base_path"], access_token=args["access_token"])
+        templates_api = TemplatesApi(api_client)
+        envelopes_api = EnvelopesApi(api_client)
+
+        account_id = args["account_id"]
+        envelope_args = args["envelope_args"]
+
+        # Step 2a start
+        template_data = cls.make_template()
+        template = templates_api.create_template(account_id, envelope_template=template_data)
+        template_id = template.template_id
+
+        # Step 2a end
+
+        # Update template document
+        # Step 3a start
+        document_id = '1'
+        templates_api.update_document(
+            account_id, document_id, template_id,
+            envelope_definition=cls.template_document(envelope_args)
+        )
+        # Step 3a end
+
+        # Update recipient tabs
+        # Step 4a start
+        recipient_id = '1'
+        templates_api.create_tabs(
+            account_id, recipient_id, template_id,
+            template_tabs=cls.recipient_tabs()
+        )
+        # Step 4a end
+
+        # Create draft envelope
+        # Step 5a start
+        envelope_definition = cls.make_envelope(template_id, envelope_args)
+        envelope = envelopes_api.create_envelope(account_id, envelope_definition=envelope_definition)
+        envelope_id = envelope.envelope_id
+        # Step 5a end
+
+        # Get the document id
+        # Step 6 start
+        doc_gen_form_fields_response = envelopes_api.get_envelope_doc_gen_form_fields(account_id, envelope_id)
+        document_id_guid = doc_gen_form_fields_response.doc_gen_form_fields[0].document_id
+        # Step 6 end
+
+        # Merge the data fields
+        # Step 7a start
+        form_fields = cls.form_fields(envelope_args, document_id_guid)
+        envelopes_api.update_envelope_doc_gen_form_fields(
+            account_id,
+            envelope_id,
+            doc_gen_form_field_request=form_fields
+        )
+        # Step 7a end
+
+        # Send the envelope
+        # Step 8 start
+        send_envelope_req = Envelope(status="sent")
+        envelope = envelopes_api.update(account_id, envelope_id, envelope=send_envelope_req)
+        # Step 8 end
+        return envelope
+
+    # Step 2b start
+    @classmethod
+    def make_template(cls):
+        # Create recipient
+        signer = Signer(
+            role_name="signer",
+            recipient_id="1",
+            routing_order="1",
+        )
+        recipients = Recipients(
+            signers=[signer]
+        )
+
+        # Create the envelope template model
+        template_request = EnvelopeTemplate(
+            name="Example document generation template",
+            description="Example template created via the API",
+            email_subject="Please sign this document",
+            shared="false",
+            recipients=recipients,
+            status="created"
+        )
+        return template_request
+    
+    # Step 2b end
+
+    # Step 3b start
+    @classmethod
+    def template_document(cls, args):
+        with open(args["doc_file"], "rb") as file:
+            content_bytes = file.read()
+        base64_file_content = base64.b64encode(content_bytes).decode("ascii")
+
+        # Create the document model
+        document = Document(
+            document_base64=base64_file_content,
+            name="OfferLetterDemo.docx",
+            file_extension="docx",
+            document_id=1,
+            order=1,
+            pages=1
+        )
+
+        envelope_definition = EnvelopeDefinition(
+            documents=[document]
+        )
+        return envelope_definition
+    # Step 3b end
+
+    # Step 4b start
+    @classmethod
+    def recipient_tabs(cls):
+        # Create tabs
+        sign_here = SignHere(
+            anchor_string="Employee Signature",
+            anchor_units="pixels",
+            anchor_x_offset="5",
+            anchor_y_offset="-22"
+        )
+        date_signed = DateSigned(
+            anchor_string="Date",
+            anchor_units="pixels",
+            anchor_y_offset="-22"
+        )
+        tabs = Tabs(
+            sign_here_tabs=[sign_here],
+            date_signed_tabs=[date_signed]
+        )
+        return tabs
+    # Step 4b end
+
+    # Step 5b start
+    @classmethod
+    def make_envelope(cls, template_id, args):
+        # Create the signer model
+        signer = TemplateRole(
+            email=args["candidate_email"],
+            name=args["candidate_name"],
+            role_name="signer"
+        )
+
+        # Create the envelope model
+        envelope_definition = EnvelopeDefinition(
+            template_roles=[signer],
+            status="created",
+            template_id=template_id
+        )
+        return envelope_definition
+    # Step 5b end
+
+    # Step 7b start
+    @classmethod
+    def form_fields(cls, args, document_id_guid):
+        doc_gen_form_field_request = DocGenFormFieldRequest(
+            doc_gen_form_fields=[
+                DocGenFormFields(
+                    document_id=document_id_guid,
+                    doc_gen_form_field_list=[
+                        DocGenFormField(
+                            name="Candidate_Name",
+                            value=args["candidate_name"]
+                        ),
+                        DocGenFormField(
+                            name="Manager_Name",
+                            value=args["manager_name"]
+                        ),
+                        DocGenFormField(
+                            name="Job_Title",
+                            value=args["job_title"]
+                        ),
+                        DocGenFormField(
+                            name="Salary",
+                            value=args["salary"]
+                        ),
+                        DocGenFormField(
+                            name="Start_Date",
+                            value=args["start_date"]
+                        )
+                    ]
+                )
+            ]
+        )
+        return doc_gen_form_field_request
+    # Step 7b end
diff --git a/app/eSignature/views/__init__.py b/app/eSignature/views/__init__.py
@@ -38,3 +38,4 @@
 from .eg039_in_person_signer import eg039
 from .eg040_document_visibility import eg040
 from .eg041_cfr_embedded_signing import eg041
+from .eg042_document_generation import eg042
diff --git a/app/eSignature/views/eg042_document_generation.py b/app/eSignature/views/eg042_document_generation.py
@@ -0,0 +1,64 @@
+""" Example 002: Remote signer, cc, envelope has three documents """
+
+from os import path
+
+from docusign_esign.client.api_exception import ApiException
+from flask import render_template, session, Blueprint, request
+
+from ..examples.eg042_document_generation import Eg042DocumentGenerationController
+from ...docusign import authenticate, ensure_manifest, get_example_by_number
+from ...ds_config import DS_CONFIG
+from ...error_handlers import process_error
+from ...consts import pattern, API_TYPE
+
+example_number = 42
+api = API_TYPE["ESIGNATURE"]
+eg = f"eg0{example_number}"  # reference (and url) for this example
+eg042 = Blueprint(eg, __name__)
+
+
+@eg042.route(f"/{eg}", methods=["POST"])
+@authenticate(eg=eg, api=api)
+@ensure_manifest(manifest_url=DS_CONFIG["example_manifest_url"])
+def sign_by_email():
+    """
+    1. Get required arguments
+    2. Call the worker method
+    3. Render success response with envelopeId
+    """
+
+    # 1. Get required arguments
+    args = Eg042DocumentGenerationController.get_args()
+    try:
+        # 1. Call the worker method
+        results = Eg042DocumentGenerationController.worker(args)
+    except ApiException as err:
+        return process_error(err)
+
+    # 2. Render success response with envelopeId
+    example = get_example_by_number(session["manifest"], example_number, api)
+    return render_template(
+        "example_done.html",
+        title=example["ExampleName"],
+        message=example["ResultsPageText"].format(results.envelope_id)
+    )
+
+
+@eg042.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/eg042_document_generation.html",
+        title=example["ExampleName"],
+        example=example,
+        source_file="eg042_document_generation.py",
+        source_url=DS_CONFIG["github_example_url"] + "eg042_document_generation.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/static/demo_documents/Offer_Letter_Demo.docx b/app/static/demo_documents/Offer_Letter_Demo.docx
diff --git a/app/templates/eSignature/eg042_document_generation.html b/app/templates/eSignature/eg042_document_generation.html
@@ -0,0 +1,57 @@
+<!-- extend base layout --> {% extends "base.html" %}  {% block content %}
+
+{% include 'example_info.html' %}
+
+{%  set form_index = 0 %}
+{%  set candidate_email_index = 0 %}
+{%  set candidate_name_index = 1 %}
+{%  set manager_name_index = 2 %}
+{%  set job_title_index = 3 %}
+{%  set salary_index = 4 %}
+{%  set start_date_index = 5 %}
+
+<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="candidate_email">{{ example['Forms'][form_index]['Inputs'][candidate_email_index]['InputName'] }}</label>
+      <input type="email" class="form-control" id="candidate_email" name="candidate_email"
+             aria-describedby="emailHelp" placeholder="{{ example['Forms'][form_index]['Inputs'][candidate_email_index]['InputPlaceholder'] }}" required
+             value="{{ candidate_email }}" />
+      <small id="emailHelp" class="form-text text-muted">{{ session['manifest']['SupportingTexts']['HelpingTexts']['EmailWontBeShared'] | safe}}</small>
+    </div>
+    <div class="form-group">
+      <label for="candidate_name">{{ example['Forms'][form_index]['Inputs'][candidate_name_index]['InputName'] }}</label>
+      <input type="text" class="form-control" id="candidate_name" placeholder="{{ example['Forms'][form_index]['Inputs'][candidate_name_index]['InputPlaceholder'] }}" name="candidate_name"
+             value="{{ candidate_name }}" required />
+    </div>
+    <div class="form-group">
+      <label for="manager_name">{{ example['Forms'][form_index]['Inputs'][manager_name_index]['InputName'] }}</label>
+      <input type="text" class="form-control" id="manager_name" name="manager_name"
+             aria-describedby="emailHelp" placeholder="{{ example['Forms'][form_index]['Inputs'][manager_name_index]['InputPlaceholder'] }}" required />
+    </div>
+    <div class="form-group">
+      <label for="job_title">{{ example['Forms'][form_index]['Inputs'][job_title_index]['InputName'] }}</label>
+      <select class="form-control" id="job_title" name="job_title">
+          <option value="Software Engineer">Software Engineer</option>
+          <option value="Product Manager">Product Manager</option>
+          <option value="Sales Representative">Sales Representative</option>
+      </select>
+    </div>
+    <div class="form-group">
+      <label for="salary">{{ example['Forms'][form_index]['Inputs'][salary_index]['InputName'] }}</label>
+      <input type="text" class="form-control" id="salary" placeholder="{{ example['Forms'][form_index]['Inputs'][salary_index]['InputPlaceholder'] }}" name="salary"
+             required />
+    </div>
+    <div class="form-group">
+      <label for="start_date">{{ example['Forms'][form_index]['Inputs'][start_date_index]['InputName'] }}</label>
+      <input type="date" class="form-control" id="start_date" placeholder="{{ example['Forms'][form_index]['Inputs'][start_date_index]['InputPlaceholder'] }}" name="start_date"
+             required />
+    </div>
+    <input type="hidden" name="csrf_token" value="{{ csrf_token() }}"/>
+    {% include 'submit_button.html' %}
+  </form>
+  
+{% endblock %}
diff --git a/requirements.txt b/requirements.txt
