Electronic Signatures Made Simpler with Docusign Adapter in SAP Integration Suite

[Vishal_Ingale]

Introduction

Signatures are part of almost every transaction in the world. However, nowadays most documents are sent by email, and asking someone to sign them physically feels pretty old-school, isn’t it?

This is  why electronic signatures are becoming more relevant by the day.

DocuSign is an ideal tool to help you send contracts that require electronic signatures. It provides a secure method which is legally valid for obtaining electronic signatures.

Docusign Adapter in SAP Cloud Integration

The Docusign adapter is designed to function as a receiver adapter. It connects SAP Integration Suite to Docusign and enables you to manage and configure Docusign objects to integrate features like embedded sending, e-signatures, etc into your applications.

It offers the following features:

• Allows you to perform several operations such as Create, Read, Update, and Delete (CRUD) for entities such as Envelopes, SigningGroups and Template etc.
• Allows secure authentication via OAuth 2.0 and JSON Web Token based authentication.
• Supports Basic configuration for convenient processing capability whereas Advanced enables proficient users to perform calls with greater control while connecting to any API endpoint.
• Allows flexibility while retrieving metadata using Query Parameter field.
• Supports response output formats like JSON, XML.

In this blog post, we will deep dive into Create Envelope operation. By the end of this blog, you will be able to learn enough to use it. So, let’s get started!

Use Case Description

Let us consider a scenario where the employer wants to send an employment contract in a PDF format to a new employee joining their organization. The document can contain terms of employment and if the employee agrees, they can sign it with an electronic signature. Simple enough, isn’t it?

Let us look at a high-level diagram to understand this further.

Source system can be SAP SuccessFactors, SAP S4HANA or any other system capable of sending the PDF document to SAP Cloud Integration. Note that the document type can also be .docx. However, to retain formatting of document .pdf file is considered.

For our use case, we will consider an example of Microsoft Sharepoint as a source system where an employment contract is placed. Microsoft Sharepoint sender adapter in SAPCI will pick this contract from respective directory or folder. Contract documents will be sent in an envelope format to Docusign using Docusign adapter. Docusign will send this envelope to signer via email.

I hope by now you have got an idea how the overall process is going to work, right?

For detailed explanation, refer to the section Creating an integration flow in SAP Cloud Integration later in this blog post. Let us now understand the prerequisites to get this scenario working.

Pre-requisites

Make sure that you have:

1. Access to Microsoft sharepoint to place PDF document (Sample employment contract).

Refer to the SAP blog by @siddhartha_routh who has nicely explained in detail how to setup connectivity with Microsoft Sharepoint.

https://community.sap.com/t5/technology-blog-posts-by-members/integrating-sap-btp-cpi-with-microsoft....

Note down the details like Client ID, Client Secret, Authorization URL, Token Service URL etc. which will be used to connect Microsoft Sharepoint from SAP Cloud Integration.

2. Access to SAP Cloud Integration to create artifacts and security materials.

3. Access to Docusign (Free trial developer account should also be fine). Please follow this step-by-step guide to get started with Docusign: https://developers.docusign.com/platform/build-integration/

3.1.1. Login to Developer Account > Go to Admin Dashboard > INTEGRATIONS > Apps and Keys > Add App and Integration Key https://apps-d.docusign.com/admin/apps-and-keys

Account Base URI in above screenshot is the address to connect with Docusign. This is used in Connection tab in Docusign adapter in SAP Cloud Integration. API Account ID is used in the Processing tab in Docusign adapter in SAP Cloud Integration.

3.1.2. Create an App with name SAPCI. Integration Key will be auto generated. This is going to be the Client ID in OAuth2 Authorization Code credentials in SAP CI.

3.1.3. Select an authentication method for your app. Refer to the below link for various authentication methods available to connect with Docusign https://developers.docusign.com/platform/auth/ .

We have used Authorization Code Grant. For more information, see https://developers.docusign.com/platform/auth/confidential-authcode-get-token/ for more details.

Click on Add Secret Key button. Remember to note down this secret key as soon as it is generated. This is going to be the Client Secret in OAuth2 Authorization Code credentials in SAP CI.

3.1.4. In SAP Cloud Integration > Go to Monitor > Manage Security > Security Material > Create > OAuth2 Authorization Code.

For the developer environment:

Authorization URL is https://account-d.docusign.com/oauth/auth .

Token Service URL is https://account-d.docusign.com/oauth/token

Provide Client ID (Integration Key from Step 3.1.2) and Client Secret (Secret Key from step 3.1.3)

For this use case, we have defined the scope signature which enables an app to call the eSignature REST API. Note down the Redirect URL from the credential section which will be used to be configure in the SAPCI app created in DocuSign.

3.1.5. Under Additional Settings > Add Redirect URIs. Copy and paste the Redirect URL obtained in the previous step, Allowed HTTP methods you might use and click Save.

3.1.6. Go back to OAuth2 Authorization Code credentials again and click Authorize. The status by default is Unauthorized.

3.1.7. You will be redirected to a new webpage for consent. Click Allow Access.

You should receive a success message like below which confirms that the refresh token has been added into credential.

3.1.8. Close and refresh the Manage Security Material screen, you should now see the status as Deployed. You can use this credential to establish connection with Docusign.

 

Creating an integration flow in SAP Cloud Integration

Steps

1. Microsoft Sharepoint Sender Adapter in SAP Cloud Integration polls files from Sharepoint directory as per scheduled frequency.

Connection: Provide the details of Sharepoint server like site host name, server relative path, authentication type etc.

You can choose either OAuth2 Authorization Code or OAuth2 Client Credentials as an authentication type. I have selected OAuth2 Client Credentials.

In SAP Cloud Integration > Go to Monitor > Manage Security > Security Material > Create > OAuth2 Client Credentials. Provide Token Service URL, Client ID, Client Secret obtained from Pre-requisites explained earlier in this blog. Set scope as https://graph.microsoft.com/.default.

Once all the details are provided, deploy credentials.

Processing: Provide the processing parameters for the file like Directory, File Name, Post-processing etc.

Scheduler: You can schedule an integration flow to poll files from Sharepoint.

2. Base64 Encoder will encode the PDF document in Base64 format to safely transfer binary data through systems. This also ensures the file's integrity and prevent corruption during transmission.

3. Content Modifier is used to prepare DocuSign API Payload (in our case Create Envelope data) in JSON format. The details provided in this step are used while sending an email from DocuSign in Step 5. Without JSON payload, DocuSign would receive a PDF document with no context, no recipient information, and no instructions on where to place the signature fields, making the transaction impossible to process. That’s why JSON payload is necessary.

Message Body

Type: Expression

JSON Body:

{
  "emailSubject": "Please Sign: Sample Employment Contract Letter for DocuSign Use Case",
  "status": "sent",
  "documents": [
    {
      "documentId": "1",
      "name": "Sample Employment Contract Letter for DocuSign Use Case.pdf",
      "fileExtension": "pdf",
      "documentBase64": "${body}"
    }
  ],
  "recipients": {
    "signers": [
      {
        "email": "<Enter email ID of recipient here>",
        "name": "<Enter name of recipient here>",
        "recipientId": "1",
        "routingOrder": "1",
        "tabs": {
          "signHereTabs": [
            {
              // --- This defines where the signature goes ---
              "anchorString": "/signature/",
              "anchorXOffset": "10",
              "anchorYOffset": "10",
              "anchorIgnoreIfNotPresent": "false",
              "documentId": "1",
              "pageNumber": "1" // This can be ignored if anchor string is reliable
            }
          ]
        }
      }
    ]
  }
}

More Information about Key Payload Components

• Including the PDF Content as Base64: The DocuSign API doesn't accept a raw file upload in this combined request structure. It requires the document content to be converted into a Base64 encoded string within the documentBase64 field.
• Defining the Recipient and signHere tab : The recipients object is where you define who needs to sign and what they need to sign. signHereTabs array: This is a crucial nested object. It tells DocuSign to place a standard signature box.

• Using anchorString for AutoPlace: The most elegant and robust way to place the signature field is the anchorString parameter within the signHereTabs object.

"anchorString": "/signature/": DocuSign scans the PDF document for this exact string.

"anchorIgnoreIfNotPresent": "false": This is useful for development. If set to true, the envelope will still send even if the string is missing. If set to false, the API call will fail with an error, alerting you that your PDF template is misconfigured.

• Fine-Tuning with Offsets: You need to adjust where the signature block appears relative to your anchor text.

"anchorYOffset": "10" (or "-10"): Moves the signature field vertically (up or down) from the baseline of your anchor text. A positive number moves it down.

"anchorXOffset": "0" (or "50"): Moves the signature field horizontally (left or right).

"documentId": "1": Links this specific signature tab to the document you included in the documents array that has documentId set to "1".

4. Using request-reply, send a Create Envelope request to DocuSign and get Envelope ID on a successful response.

The connection tab uses following parameters:

Parameter	Description
Address	Specify the address of Docusign to be used for the connection. Example: https://account.docusign.com
Authentication	Specify the address of Docusign to be used for the connection: ·        JSON Web Token (JWT) ·        OAuth 2.0 Authorization Code
Authentication Base URL	Specify the name of the Secure Parameter artifact that contains the User ID needed to connect to Docusign.
Client ID Alias	Specify the Secure Parameter artifact that contains the Client ID needed to connect to Docusign.
User ID Alias	Specify the Secure Parameter artifact that contains the User ID needed to connect to Docusign.
RSA Key Alias	Specify the RSA key alias for connecting to the Docusign account.
Authorization Code Credentials (Only available when OAuth 2.0 Authorization Code is selected)	Specify the Secure Parameter key alias that stores the Docusign OAuth Authorization Code.
Reuse Connection	Enable to reuse the connection. This option enables the reuse of connection objects from the internal connection pool which in turn improves the network turnaround time for multiple communications to a same end point.
Connection Timeout (in ms)	Specify the maximum waiting time (in milliseconds) for the connection to be established. Example: 6000
Response Timeout (in ms)	Specify the maximum waiting time (in milliseconds) for a response message. Example: 60000

The Processing tab contains all operation related configurations for the Docusign Receiver adapter.

Parameter	Description
Configuration Type	Select the required configuration type: ·        Basic to use the dropdowns and parameter text fields. ·        Advanced to specify the relative URL.
Entity	Specify the entity on which the operation is to be performed.
Operation	Select the operation to be performed.
File Name	Specify the file name of the resource being uploaded.
Query Parameter	Specify the expression containing the query parameter and value. Example:include_external_references,include_logos
Count	Specify the maximum number of results to return. Acceptable values range from 1 to 100.
Start Position	Specify the zero-based index of the result from which to start returning results.
Resource Parameters	Specify the Name and Value in case the resource path includes parameters. Example: Set Name to propertyKey & Value to 76548.
Request	Select the format for request payload.
Response	Select the format for response payload.
Request Headers	Enter a list of custom headers, separated by a pipe (|), to send to the target system. By default, no custom headers are sent. Use an asterisk (*) to send all custom headers to the target system. Alternatively, you can dynamically pass on the values by defining a property that includes a list of headers.
Response Headers	Enter a list of headers coming from the target system's response, separated by a pipe (|), to be received in the message. Use an asterisk (*) to receive all the headers from the target system, which is also the default value.

5. DocuSign internally takes care of sending an email to recipient/s retrieved from Step#3. Signer can review and electronically sign the document. Once done, a completion email will be sent to signer from Docusign.

Let’s run our integration

Steps

1. Take a Sample Employment Contract Letter like below. You can just copy-paste this content into WORD document. 

Employment Contract Letter
Dear [Employee Name],
We are pleased to offer you the position of [Job Title] at [Company Name]. This letter outlines the terms and conditions of your employment.
1. Position and Responsibilities
You will be employed as [Job Title], reporting to [Reporting Manager/Department]. You are expected to perform the duties and responsibilities assigned to you in a professional and efficient manner.
2. Compensation
Your compensation package will include:
•	Salary: [Salary Details – optional to state]
•	Benefits: As per company policy, including any applicable medical, insurance, or other benefits.
3. Work Location
Your designated place of work will be [Office Location / Remote Arrangement].
4. Company Policies
You agree to follow all company rules, regulations, and policies as communicated through the employee handbook or official HR communications.
5. Employment Classification
Your employment with the company is classified as [Full-Time / Part-Time / Contractual / Probationary].
6. Confidentiality & Conduct
During your employment, you are expected to maintain confidentiality of all company information and adhere to professional standards of conduct.
7. Acceptance of Offer
By signing below, you confirm that you have read, understood, and agree to the terms and conditions of your employment with [Company Name].
We look forward to welcoming you to our team.
Sincerely,
[HR Representative Name]
[HR Title/Designation]
[Company Name]
________________________________________
Employee Acceptance
I accept the terms of employment as stated above.

Employee Signature:  /signature/

 Make sure that the anchorString is present in the document where Docusign will place the Signature box.

To hide achorString from the document, you can simply change the font colour of text to white. This way, the anchor string would be still there in document but not visible to the signer.

Once your document is ready, convert it into PDF format using any online tool. See below to visualize how your PDF may look like.

 2. Place the letter on sharepoint directory to pick by an Integration flow

3. The integration flow runs successfully and returns Envelope ID from Docusign. File is moved to archive directory as per post-processing configuration.

4. Email is sent on recipient’s email ID to review and sign. Click Review Document.

5. Document will open and observe the Sign box appears exactly where the anchorString was present.

6. Review the document and click on Sign button. Select, draw or upload the signature you wish to use for signing the document. Once done, click on Adopt and Sign. Signature appears, click on Finish.

7. You can see a confirmation message like the one below. Signer also receives an email with completion of the document.

8. If you click on View Completed Document, you can see the signed document. The same is also attached in the email.

9. Additionally, you can also see the completed agreements in Docusign directly on home page https://apps-d.docusign.com/send/home under Agreement activity. See below screenshot

Key Learnings and Takeaways

In this blog, we explored how Docusign adapter in SAP cloud integration can help to implement a simple yet practical use case which makes implementation of electronic signatures effective and super easy. This isn’t all that you can do with Docusign adapter, take a look at all operations supported by adapter and try them out yourself.

References

https://help.sap.com/docs/integration-suite/sap-integration-suite/docusign-adapter

Note: The Docusign adapter is also available as a part of your SAP Integration Suite license.

I hope this blog helps you think broadly about how the Docusign adapter can fit into your integration scenarios to deliver value to your customers.

Thank you for reading all the way through. Keep sharing and Keep learning 😊!!

Regards,

Vishal Ingale