Package: docassemble.docusign
docassemble.docusignA docassemble extension to allow you to access the DocuSign API from inside Docassemble interviews.InstallationInstall this package from within your Docassemble package management screen using the GitHub address.ConfigurationDocassemble-DocuSign uses the JWT authorization technique.  See the DocuSign API Documentation for details.To configure Docassemble to access your DocuSign account:In the DocuSign Admin system, create a docassemble-docusign app.Create an RSA Keypair for that app, and save the private key to a secure location.For that app, add https://{your.server.here}/interview as a redirect URI, or whatever your "interview" root is on your
docassemble server.Get the integration key or "client ID" for your app.In the user section of your DocuSign admin system, look at the details of the user account your app will use, and get
the "API Username" for that user.Now you are ready to configure docassemble-docusign. Go into the configuration screen of docassemble, and add the following
configuration lines. Remember that whitespace matters.docusign:
  client-id: {the integration key or client ID from step 4}
  impersonated-user-guid: {the API Username from step 5}
  test-mode: True
  private-key: |
    -----BEGIN RSA PRIVATE KEY-----
    {the private key you saved from step 2}
    -----END RSA PRIVATE KEY-----Test ModeIf you settest-mode: True, the extension will use sandbox mode on the DocuSign API.
If you settest-mode: False, the extension will use live mode on the DocuSign API.AuthenticatingNow the extension is configured, but you need to give it permission to impersonate the DocuSign user account.To do that run thedocusign_auth.ymlinterview included with the package. It will send you to the right location to authorize.UsageInclude the ModuleFirst, include the module in your interview.---
modules:
  - docassemble.docusign.da_docusign
---Generate DocuSign TabsSecond, use thegenerate_anchorfunction to insert "Anchors" into your document where you want DocuSign tabs to appear.generate_anchoraccepts two parameters, the first is a DocuSign anchor type, which must be one of:'approve''checkbox''company''dateSigned''date''decline''email''envelopeId''firstName''formulaTab''fullName''initialHere''lastName''list''notarize''note''number''radioGroup''signHere''signerAttachment''ssn''text''title''view''zip'The second parameter is the email address of the person who needs to fill out that tab.For example, you can create a template in your docassemble interview as follows:attachments:
  - name: Your Document
    filename: docusign_test_doc
    variable name: docusign_test_doc
    content: |
      % for r in recipient:

      ${ generate_anchor('signHere', r.email) }  

      ***  

      ${ r.name }
      ${ generate_anchor('date', r.email) }
      % endforThat code will generate an anchor for the signature, followed by a horizontal line, followed by the person's name, followed by an
anchor for the date on which they signed the document.Create the DocuSign Envelope ParametersNext, your code needs to create a Python object for the recipients portion of the DocuSign envelope, and a python object for the
documents portion of the DocuSign Envelope.Note that when you are generating your recipients object, you must include all the same tabs that you generated anchors for in the
document, to ensure that DocuSign will deal properly with them. When generating tabs, use thegenerate_anchorfunction.An example of a correctly formated recipients object is:recipients=[
        {
            'name': 'Doug Rattman',
            'email': 'doug.rattman@aperturescience.com',
            'group': 'signers',
            'routingOrder': 1,
            'tabs': [
                {
                    'type': 'signHere',
                    'anchorString': generate_anchor('signHere', 'doug.rattman@aperturescience.com')
                },
                {
                    'type': 'date',
                    'anchorString': generate_anchor('date', 'doug.rattman@aperturescience.com')
                }
            ]
        },
        {
            'name': 'Cave Johnson',
            'email': 'ceo@aperturescience.com',
            'group': 'certifiedDeliveries',
            'routingOrder': 2
        }
    ]See the DocuSign API documentation for information on the features that are available in DocuSign envelopes.Thegenerate_anchorfunction has an optional argumentuidthat will add an additional section to the anchor. Use this is if you want to distinguish between tags of the same type.When generating documents, use themake_document_base64function to convert the document to Base64 before adding it to the object.make_document_base64accepts a path to a document. If you want to use a dynamically-generated document in a Docassemble interview,
give that document avariable name:attribute, and then usedocument_variable_name.pdf.path(), replacingpdfwith whatever
document format you prefer.An example of a correctly formatted documents object is:documents=[
        {
            'name': "Bring Your Daughter To Work Day",
            'fileExtension': 'docx',
            'documentBase64': make_document_base64('bydtwd.docx')
        },
        {
            'name': "Lemon Grenade Acquisition",
            'fileExtension': 'docx',
            'documentBase64': docasign.make_document_base64('lemongrenadeacquisition.docx')
        }
    ]There is an example interview provided in the package,docusign_test_interview.yml, that has an example of generating the
recipient and document objects in code.Send the Envelope to DocuSignIn your interview code, create a DocuSign() object:code: |
  ds = DocuSign()Then, call theget_signatures()function to send your documents to your recipients.get_signaturesaccepts the following parameters:recipients: Mandatory. The recipients object described above.documents: Mandatory. The documents object described above.send_immediately: Optional, if set toTrue, your request will be sent. IfFalse,email_subject: optional, defaults to "Please Sign".assign_doc_ids: optional, deafults toTrue. Set toFalseif you are manually setting document IDs in your document object.assign_recipient_ids: optional, deafaults toTrue. Set toFalseif you are manually setting recipient IDs in your recipients object.Any other paramaters will be added as additional parts of the request sent, for example,emailBlurb="Please sign this document"sets the email's body.get_signaturesreturns the JSON formatted version of your DocuSign envelope whensend_immediatelyisFalse.
Ifsend_immediatelyis set toTrue, then it returns three values:the JSON formatted version of the DocuSign envelopethe response data of the DocuSign Serverthe status code of the request to the DocuSign ServerA successful envelope submission will return a status code of 201.