How To: Create Embedded Signatures with DocuSign

This topic shows you how to create an end-to-end solution with DocuSign to automate the signing of a document. It includes how to embed the DocuSign signing experience within a K2 SmartForm which means that you don't need to open DocuSign separately to sign documents.

The solution used in this example shows you how to configure forms and a workflow to submit a contract of employment to Human Resources and then send it to the new employee and their manager to sign. The new employee signs by clicking on a DocuSign link in an email sent by the workflow, and the manager signs the document by opening a workflow task from K2 Workspace (Desktop and Mobile).

The DocuSign service type allows K2 to integrate with DocuSign. For more information on how to enable this integration see DocuSign Feature Activation.

This How To assumes that you are familiar with DocuSign.

The screenshots and instructions for third-party software are accurate at the time of writing. Third-party vendors may have changed or updated aspects of their systems (such as user interfaces, functionality, and security). As a result, this content may be outdated.

Runtime example of embedded DocuSign signing in K2 Workspace (Desktop)

Scenario

As part of an employee onboarding process, your company sends a contract of employment for electronic signing. After the contract is approved by HR, the document is sent to the newly hired employee and the employee's manager. Both parties need to sign the contract to complete the process.

To start, you submit a form containing the new employee details (Name, Email, Start Date, Department) and the contract of employment. This is sent to Codi Kaji (Human Resources) for approval. After successful approval, DocuSign sends the document to the employee's private email address. The employee is not part of the company domain so he signs the document by clicking on a link in the email from DocuSign.

Once signed by the new employee, the document is ready for the manager's signature. The manager receives a task containing the contract and uses K2 Workspace (Desktop and Mobile) to view it. The manager signs the document directly from within K2 Workspace (Desktop and Mobile) and there is no need to click an external DocuSign link. This is known as an embedded signing experience.

For this scenario we use sample users. You can create your own test users to work with. Depending on the type of scenario you build, you may need to configure specific security settings such as Designer authorization for these users. For more information about managing your environment see the Administer section.

Steps

In this scenario, you begin by creating a SmartObject, generating views and forms.

Next you create a workflow that contains Task, Set Folio, Decision, Timer, and DocuSign steps. You use the Create Envelope, Add Document, Add Recipient, Create Tab in Document and Send Envelope steps to configure the DocuSign signing process. For the embedded signing process, you configure a task step to use a specific form so the recipient can sign from within K2 workspace (Desktop and Mobile).

Finally, you deploy the workflow and test the solution.

Setup Steps

The following steps set up the scenario from start to finish. If you want to skip the setup steps and view the topic step, go to Create and Configure the DocuSign Embedded Form.

Create a SmartObject called New Employee.
1. From the K2 Designer, create the New Employee SmartObject as shown below.
  
  If you are not familiar with creating a SmartBox SmartObject, see How To: Create A SmartBox SmartObject.
Generate a List view for the New Employee SmartObject.
1. From the K2 Designer, right-click the New Employee SmartObject and select Generate Views
  .
2. On the Generate Options page, make sure that the item list view is generated in the correct category. In this example, they are generated in the Views category. Check the Item List check box and then click OK.
3. The generated list view show in the Views category.
  
  If you are not familiar with creating views, see How To: Create an Item View and a List View.
Create a new view called DocuSign Data Label and use the DocuSign View SmartObject as the data source. You also add two data label controls to the view.
1. From the K2 Designer, right-click the Views category and select New View.
2. In the Name field type DocuSign Data Label as the name for this view. Click the Data Source ellipsis button to specify a data source for this view.
3. On the Select a SmartObject page browse to the DocuSign category and select the View SmartObject. Click OK.
4. Click Create.
5. On the Layout tab select Create Layout Table Only.
6. On the Create Layout Table page, select 2 Columns, 1 Row and click OK.
7. From the Toolbox drag a Data Label control onto the canvas into each one of the columns.
8. Select Data Label. In the Details section on the Properties tab, change the Name and Text fields to EnvelopeID. In the General section, uncheck the Visible check box.
9. Select Data Label1. In the Details section on the Properties tab, change the Name and Text fields to RecipientID. In the General section, uncheck the Visible check box.
10. Click Finish to save to the view.
Use the New Employee Item view to generate the New Employee form.
1. From the K2 Designer, locate and right click the New Employee Item view. From the menu select Generate Forms.
2. On the Generate Forms page, make sure the form is created in the correct category. In this example, it's created in the Forms category. Change the form name to New Employee. Click OK.
3. From the K2 Designer, locate and right click the New Employee form and select Edit.
4. On the Layout tab, change the New Employee Item view title to New Employee Details.
5. From the Properties tab, change the form theme to Lithium. Click Finish.
Create and configure the Redirect Form that redirects to a message. This form shows after the manager signs the contract (the embedded signing experience). The Runtime URL of this form is used when you configure the embedded signing rule in point k of Step 6.
1. From the K2 Designer, locate and right click the Forms category. From the menu select New Form.
2. In the Name field type Redirect for the name. Click Create.
3. From the Toolbox, drag a Text Area control onto the canvas.
4. In the Details section on the Properties tab, type a Thank you for signing message into the Text field.
5. Click Finish. Right-click the Redirect form's Runtime URL link to copy it. You'll use this in Step 6: Step Create and Configure the DocuSign Embedded Form.
6. Here is an example of the Runtime URL of the Redirect form.

Create and configure the DocuSign Embedded Form

In this step, you create a form called DocuSign Embedded. The manager uses this form to sign the contract and you add the following items to the form:

a content control
a data label called DocuSignURL
the DocuSign Data Label view
add the DocuSign EnvID and DocuSign RecID parameters
and rules

You add the data label and the view to the form to make sure the correct DocuSign information is sent from the workflow to the form. This allows the DocuSign signing experience to happen inside the form. You also need the EnvelopeID and RecipientID to return a DocuSign URL. The view is linked to the DocuSign View SmartObject which stores the EnvelopeID and RecipientID. You use the DocuSign URL to display the embedded signature in the content control.

You add parameters to the view to enable communication between the form, view and the DocuSign variables you create later in the workflow.

You add rules for the correct URL to show in the content control. These rules get the Envelope ID and Recipient ID from the workflow variables using form parameters. This means the Envelope ID and Recipient ID from the workflow are passed to the form's DocuSign EnvID and DocuSign RecID parameters. You then use these parameters in rules to create the DocuSign URL displayed in the content control.

Create and configure the DocuSign Embedded Form
1. From the K2 Designer, locate and right click the Forms category. From the menu select New Form.
2. In the Name field, type DocuSign Embedded for the name. Click Create.
3. From the Toolbox, drag a Content control onto the canvas.
4. Drag a Data Label control onto the canvas below the Content control. In the Details section on the Properties tab, change the Name and Text fields to DocuSignURL. This data label contains the DocuSign URL which enables the manager to sign the contract in the form.
5. In the General section, uncheck the Visible check box for the DocuSignURL data label.
6. From the Views tab, drag the DocuSign Data Label view onto the canvas underneath the DocuSignURL data label. In the General section, uncheck the Visible check box for the view.
7. Select the Parameters tab and click Add Parameter. Add two parameters called DocuSign EnvID and DocuSign RecID as shown below.
8. Select the Rules tab, the When the Form is Initializing rule and then click Edit Rule.
9. On then on DocuSign Data Label View, execute the Initialize method, click the Initialize link and change it to Get Recipient Url.
10. Click the configure link. On the On DocuSign Data Label View, Execute the Get Recipient Url Method page, select Input Mappings. Expand the Parameters node in the Context Browser. Click and drag the DocuSign EnvID parameter into the Envelope ID field. Click and drag the DocuSign RecID parameter into the Recipient ID field.
11. Locate the Runtime URL for the Redirect form you created in Step 5. Paste the URL into the Return Url field. Click Next.
12. For the Output Mappings, click and drag the Url return property from the Context Browser into the DocuSignURL field. This is the URL that shows in the content control and enables the embedded DocuSign experience. Click Finish.
13. Select the Actions tab. In the search field type transfer, locate the Data Transfer section, and select Transfer Data.
14. Click the configure link. On the Transfer Data page, expand the View node in the Context Browser. Click and drag the Url property into the Url field. This transfers the data from the DocuSign View SmartObject to the form. Click OK.
15. Select the Actions tab. In the search field type control, locate the Control Interaction section, and select Set a Form control's properties. This rule ensures that the DocuSign View SmartObject Url shows in the content control.
16. Click the set control link and select Content.
17. Click the configure link. On the Set the Properties Of Content Control page, expand the View node in the Context Browser. Click and drag the Url property into the URL field. Click OK.
18. Your rule should look like the following example. Click OK.
19. Click Finish to complete the form configuration.

Create a workflow called Employee Contracts. The workflow starts by submitting the New Employee form. A task is created for Codi in the Human Resources department. Codi approves the task which starts the DocuSign signing process. The contract is sent first to the new employee for signature and then to the manager for final signature. The employee's signing experience happens externally (DocuSign link via an email). The manager's signing experience happens in a K2 user task form. The workflow completes once both people sign the contract.

From the K2 Designer, locate and right click the Contracts category. From the menu select New Workflow.
Name this workflow Employee Contracts and click Create.
Select the Start step and click the toggle to expand the Configuration Panel. You can also double click the step to expand the panel. Select the Start with a Form option.
Browse and select the New Employee form. Click OK.
The Start Workflow from a Form page shows. Click Next.
In the Start Rule section, select the Do it for me! option and click Next.
The Almost Done page shows. This page contains all changes to the form. Click Save and Finish.
On the Success page click OK.
The start rule is configured.
Click the toggle to expand the Context Browser. From the Variables section, click the Add link.

Use information from the table below to create seven variables:

Variable Name	Description	Type
DocID	Stores the unique Document ID.	Text
EnvID	Stores the Envelope ID.	Text
EmloyeeRecID	Stores the employee's Recipient ID.	Text
ManagerRecID	Stores the manager's Recipient ID.	Text
Status	Stores the status of the workflow. Example: In Progress.	Text
EmployeeTabID	Stores the employee's Tab ID.	Text
ManagerTabID	Stores the manager's Tab ID.	Text

The variables show as follows:
From the Toolbox, click the Basic category and drag the Set Folio step onto the canvas.
Select the Set Folio Detail tab. In the Folio field, type Contract for and then drag the Name property from the New Employee reference into the field. This adds the employee name to the workflow folio. You can find the reference in the Context Browser, References section and then expand the New Employee reference.
From the Toolbox, click the Basic category and drag the Task step onto the canvas. Connect the step to the Set Folio step. Select the Task tab and create two task actions (Approve and Reject).
Select the Forms tab. From the Form Type drop down menu select Basic Task Form.
Select the Recipients tab. Browse and select Codi Kaji as the recipient for this task.
Drag a line from the Task step to add the Decision step.
Drag a line from the Reject action port to create a Placeholder step.
Drag a Send Email step onto the Placeholder step and configure the email as shown below.
Select the Task step and change the name to HR Approval.

Add and configure the Create Envelope step that starts the DocuSign automation.
1. From the Toolbox click the DocuSign category, the Envelope category, and then drag the Create Envelope step onto the canvas. Connect the step to the Approved task action.
2. Select the step and expand the Configuration Panel. You can also double click the step to expand the panel. Select the Create Envelope tab to configure the DocuSign service instance, envelope type, envelope and the return property mappings. From the DocuSign Service menu, select the service instance. In this example, select the Standard Envelope.
3. Configure the Notification. In the Subject field, type Signature required. In the Body field, type the message as shown below and then drag the corresponding property from the New Employee reference into the notification. This adds the employee name, start date and department to the notification. You can find the reference in the Context Browser, References section. Expand the New Employee reference to see the fields of the reference.
  
  For more information about References, see References.
4. Configure the Return Property Mappings. Click the add button and add the ID and Status properties and map them to EnvID and Status.
Add an configure the Add Document step.
1. From the Toolbox, click the DocuSign category, the Document category, and then drag the Add Document step onto the canvas. Connect the step to the Create Envelope step.
2. Select the step and expand the Configuration Panel. You can also double click the step to expand the panel. Select the Add Document tab to configure the DocuSign service instance, envelope ID, document, document ID and the return property mappings. From the Variables section, drag the EnvID property into the Envelope ID field.
3. Configure the Document section. From the New Employee reference, drag the Contract file property into the Document field.
4. Configure the Document ID. From the New Employee reference, drag the ID property into the Document IDfield.
5. Configure the Return Property Mappings. Click the add button and add the Status property and map it to Status.
Add and configure the Add Recipient step and add the recipient to the envelope.
1. From the Toolbox, click the DocuSign category, the Recipient category and then drag the Add Recipient step onto the canvas. Connect the step to the Add Document step.
2. Select the step and expand the Configuration Panel. You can also double click the step to expand the panel. Select the Add Recipient tab to configure the DocuSign service instance, envelope ID, envelope type, recipient options and the return property mappings. From the Variables section, drag the EnvID property into the Envelope ID field.
3. Configure the Recipient Option section. In the Routing Order field type 1. From the Recipient Type menu select the Signer option. From the New Employee reference, drag the Name property into the Recipient Name field and the Email property into the Recipient Email Address field.
4. Configure the Return Property Mappings. Click the add button and add the ID and Status properties and map them to EmployeeRecID and Status.
5. Select the Properties tab and change the step name to Add Recipient - Employee.
Add and configure the Create Tab in Document step to specify the spot where the employee signs the document.
1. From the Toolbox, click the DocuSign category, the Document category and then drag the Create Tab in Document step onto the canvas. Connect the step to the Add Recipient - Employee step.
2. Select the step and expand the Configuration Panel. You can also double click the step to expand the panel. Select the Create Tab tab to configure the DocuSign service instance, envelope ID, recipient ID, tab details, tab positioning and the return property mappings. From the Variables section, drag the EnvID property into the Envelope ID field.
3. Configure the Recipient section. From the Variables section, drag the EmployeeRecID property into the Recipient ID field.
4. Configure the Document section. From the New Employee reference, drag the ID property into the Document ID field.
5. Configure the Tab Details section. In the Label field, type Sign Here and select the Sign Here option from the Type menu.
6. Configure the Tab Positioning section. In the Anchor String field type Signature. The purpose of this field is to specify where the DocuSign tab is added to the document. In this example, the tab is added close to the Employee Signature text in the contract.
7. Configure the Return Property Mappings. Click the add button and add the ID property and map it to EmployeeTabID.
8. Select the Properties tab and change the step name to Create Tab - Employee.
Add another recipient to the envelope using the Add Recipient step. In this scenario, the second recipient is the manager who must sign the contract.
1. From the Toolbox, click the DocuSign category, the Recipient category and then drag the Add Recipient step onto the canvas. Connect the step to the Create Tab - Employee step.
2. Select the step and expand the Configuration Panel. You can also double click the step to expand the panel. Select the Add Recipient tab to configure the DocuSign service instance, envelope ID, envelope type, recipient options and the return property mappings. From the Variables section, drag the EnvID property into the Envelope ID field.
3. Configure the Recipient Option section. In the Routing Order field type 2. From the Recipient Type menu select the Signer option. Type the recipient name and email address in the Recipient Name and Recipient Email Address fields. In this example use Bob and bob@denallix.com.
4. Configure the Option Settings. Click Add and add the Client User ID property. Type K2 into the field. You do this to make sure that this part of the DocuSign signing process is handled by K2. No email is sent to the manager as they sign using a K2 task.
5. Configure the Return Property Mappings. Click the add button and add the ID and Status properties and map them to ManagerRecID and Status.
6. Select the Properties tab and change the step name to Add Recipient - Manager.
Add and configure the Create Tab in Document step to specify the spot where the manager signs the document.
1. From the Toolbox, click the DocuSign category, the Document category and then drag the Create Tab in Document step onto the canvas. Connect the step to the Add Recipient - Manager step.
2. Select the step and expand the Configuration Panel. You can also double click the step to expand the panel. Select the Create Tab tab to configure the DocuSign service instance, envelope ID, recipient ID, tab details, tab positioning and the return property mappings. From the Variables section, drag the EnvID property into the Envelope ID field and drag the ManagerRecID property into the Recipient ID field.
3. Configure the Document section. From the New Employee reference, drag the ID property into the Document ID field.
4. Configure the Tab Details section. In the Label field, type Sign Here and select the Sign Here option from the Type menu.
5. Configure the Tab Positioning section. In the Anchor String field type Signature. The purpose of this field is to specify where the DocuSign tab is added to the document. In this example, the tab is added close to the Manager Signature text in the contract.
6. Configure the Return Property Mappings. Click the add button and add the ID property and map it to ManagerTabID.
7. Select the Properties tab and change the step name to Create Tab - Manager.
Add and configure the Send Envelope step to send the item to both the employee and manager for signatures.
1. From the Toolbox, click the DocuSign category, the Envelope category and then drag the Send Envelope step onto the canvas. Connect the step to the Create Tab - Manager step.
2. Select the step and expand the Configuration Panel. You can also double click the step to expand the panel. Select the Send Envelope tab to configure the DocuSign service instance, envelope ID, recipient ID, tab details, tab positioning and the return property mappings. From the Variables section, drag the EnvID property into the Envelope ID field. Configure the Return Property Mappings. Click the add button and add the Status property and map it to Status.
Add a Decision and Timer steps to check if the employee signed the contract. The Timer step keeps checking if the employee signed the contract. When the employee signs the contract, the workflow moves on to get the manager’s signature.
1. From the Toolbox, click the Logic category, and drag the Decision step onto the canvas. Connect the step to the Send Envelope step.
2. Select the step and expand the Configuration Panel. You can also double click the step to expand the panel. In the Decisions section, click Add to add the Employee Signed and Employee NOT Signed decisions.
3. Click Edit Decision Rule to configure the Decision Rule. This rule chooses which path to follow when the employee signs the contract or not.
4. To see if the employee signed the contract or not, use the Status property from the DocuSign Recipient SmartObject. From the Context Browser, click the SmartObjects tab and browse to DocuSign > DocuSign > Recipient > List and drag the Status property into the IF field of the rule.
5. In the SmartField composer, configure the SmartField and drag the EmployeeRecID property into the Status field and the EnvID property into the Envelope ID field. Click X to close the SmartField composer.
6. Type Complete as the IF outcome. For the THEN path, select Employee Signed from the menu and Employee NOT Signed as the ELSE path.
7. From the Toolbox, click the Logic category, and drag the Timer step onto the canvas. Connect the step to the Employee NOT Signed path.
8. Select the step and expand the Configuration Panel. You can also double click the step to expand the panel. In the Period of Time section, type 5 in the Minutes field.
9. Connect the Timer step back to the Decision step. This creates a loop that keeps checking every 5 minutes if the employee signed the contract.
Add a Set Folio step to populate the task step that is part of the embedded signing.
1. From the Toolbox, click the Basic category and drag the Set Folio step onto the canvas. Connect the step to the Employee Signed path.
2. Select the Set Folio Detail tab. In the Folio field, type Complete contract signing for and then drag the Name property from the New Employee reference into the field. This adds the employee name to the workflow folio. You can find the reference in the Context Browser, References section and then expand the New Employee reference.
Configure a Task step to use a specific form so the recipient can sign from within K2 workspace (Desktop and Mobile).
1. From the Toolbox, click the Basic category and drag the Task step onto the canvas. Select the Task tab and create two task actions (Approve and Reject). Connect the step to the Set Folio step.
2. Select the Properties tab and change the step name to Embedded Sign Task.
3. Select the Forms tab. From the Form Type drop down menu select the SmartForm option. Select the Browse option from the Form drop down menu. Browse to and select the DocuSign Embedded form.
4. The Open Task on a Form page shows. Deselect the option to create the View references. Click Next.
5. n the Open Task section, select the Help me configure it option and click Next.
6. From the Workflow View section, select the Use an existing State option and select (Base State). Click Next.
7. No configuration is needed for Form Rules or Actions. Click Next.
8. No configuration is needed for the After Submit Action. Click Next.
9. The Almost Done page shows. This page contains all changes to the form. Click Save and Finish.
10. On the Success page click OK.
11. Notice the added DocuSign EnvID and DocuSign RecID parameters in the Parameters section. You added these parameters to the form in Step 6 of this topic. You use these parameters to pass information from the workflow to the form.
12. Expand the Configuration Panel. From the Variables section, drag the EnvID variable into the DocuSign EnvID parameter and the ManagerRecID variable into the DocuSign RecID parameter.
13. Select the Recipients tab. Browse and select Bob Maggio as the recipient for this task.
14. Drag a line from the Embedded Sign Task step to add the Decision step.
15. Drag a line from the Approved and Rejected actions port to create a Placeholder step. Drag an End step into each of the placeholders.
16. Your workflow is ready to be deployed. Click File and select Deploy.
  
  For more information on the infinite loop, see Infinite Loop.
17. After successful deployment, click File and Close to close the workflow and exit the K2 Workflow Designer.
18. Check in all forms and views before testing the solution.
Test the solution by running the New Employee form, add the employee contract and submit the form. Codi, from HR, approves it which starts the DocuSign process. The contract is sent to the new employee by email for them to sign. From there it is sent to the hiring manager (Bob) via a K2 Workspace (Desktop and Mobile)Task. Bob completes the process by signing the contract on the task card and approves the task.
1. From the K2 Designer, locate the New Employee form and click the Runtime URL link.
2. Complete the form as shown below (using your own email address for the Email value and your own value for the Name). Click Save. To download a sample of the employee contract, click here.
3. Open K2 Workspace (Desktop) and log in as Codi. On the HR Approval task, select Approve and then click Submit.
4. The DocuSign process starts. The employee receives an email from DocuSign. From the email click the Review Document link.
5. The DocuSign page opens. Check I agree to use electronic records and signatures and click Continue. Sign the contract and click Finish.
6. The contract now needs to be signed by the hiring manager Bob. Open K2 Workspace (Desktop) and log in as Bob. Select the Embedded Sign Task assigned to Bob. The DocuSign experience shows in the task form. Click Continue.
7. You can sign the contract from within the task without needing to open another browser window. Click Finish to sign the contract.
8. The Redirect form shows. To complete the task, select Approve from the Select Action drop down menu and click Submit.

Review

You learned how to use DocuSign steps in a workflow to create an end-to-end solution with DocuSign functionality to automate the signing of a contract by two recipients. You also learned how to embed the signature process in K2 Workspace (Desktop).