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 form which means that you don't need to log in to DocuSign to sign documents. By adding the embedded signing experience to your workflow, you can also sign documents directly from your K2 worklist in Workspace.

The solution used in this example shows you how to configure your forms and workflow to submit a contract of employment to Human Resources and then send it to the new employee and their manager to sign. The employee signs by clicking on a DocuSign link and the manager signs in Workspace.

Before You Begin

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

Runtime Example

Scenario

As part of the employee onboarding process, your company sends a contract of employment for electronic signing. This document is sent to the newly hired employee (Peter Crawford) and the employee's manager (Bob Maggio). 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 to view it. The manager signs the document directly from within K2 Workspace and there is no need to click an external DocuSign link. This is known as an embedded signing experience.

In this step, you create the New Employee SmartObject.

  1. From the K2 Designer, create the New Employee SmartObject as shown below.

In this step, you generate an item 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.

In this step, you create a new view called DocuSign Data Label. The data source for this view is the DocuSign View SmartObject. 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 the 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 the 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.

In this step, you generate a New Employee form using the New Employee Item List view.

  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.

In this step, you create a Redirect form. 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 11 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, add 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.

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 returned 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 in order 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.

  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.

In this step, you 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 internally (within a K2 user task). The workflow completes once both people sign the contract.

  1. From the K2 Designer, locate and right click the Contracts category. From the menu select New Workflow.
  2. Name this workflow Employee Contracts and click Create.
  3. 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.
  4. Browse and select the New Employee form. Click OK.
  5. The Start Workflow from a Form page shows. Click Next.
  6. In the Start Rule section, select the Do it for me! option and click Next.
  7. The Almost Done page shows. This page contains all changes to the form. Click Save and Finish.
  8. On the Success page click OK.
  9. The start rule is configured.
  10. Click the toggle to expand the Context Browser. From the Variables section, click the Add link.
  11. Use information from the table below to create five variables:
    Variable NameDescriptionType
    DocIDStores the unique Document ID.Text
    EnvIDStores the Envelope ID.Text
    RecIDStores the Recipient ID.Text
    StatusStores the status of the workflow. Example: In Progress.Text
    TabIDStores the Tab ID.Text
  12. The variables show as follows:
  13. From the Toolbox, click the Basic category and drag the Set Folio step onto the canvas.
  14. 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.
  15. 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).
  16. Select the Forms tab. From the Form Type drop down menu select Basic Task Form.
  17. Select the Recipients tab. Browse and select Codi Kaji as the recipient for this task.
  18. Drag a line from the Task step to add the Decision step.
  19. Drag a line from the Reject action port to create a Placeholder step.
  20. Drag a Send Email step onto the Placeholder step and configure the email as shown below.
  21. Select the Task step and change the name to HR Approval.

In this step, you add the Create Envelope step. This step 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.

    4. 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.

In this step, you 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.

In this step, you add a recipient to the envelope using the Add Recipient step. In this example, the first recipient is the new employee 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 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 RecID and Status.
  5. Select the Properties tab and change the step name to Add Recipient - Employee.

In this step, you add another recipient to the envelope using the Add Recipient step. In this example, 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 Add Recipient - Employee 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 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 the add button 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 RecID and Status.
  6. Select the Properties tab and change the step name to Add Recipient - Manager.

In this step, you add the Create Tab in Document step to specify the spot where the recipients sign the document. In this example, you add two Create Tab steps, one for each signature. You need to add Split and Merge logic for the signatures.

  1. From the Toolbox, click the Logic category and then drag the Split 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 Split tab and change the path names to Employee Sign and Manager Sign.
  3. 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 Employee Sign path.
  4. 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.
  5. Configure the Recipient section. From the Variables section, drag the RecID property into the Recipient ID field.
  6. Configure the Document section. From the New Employee reference, drag the ID property into the Document ID field.
  7. Configure the Tab Details section. In the Label field, type Sign Here and select the Sign Here option from the Type menu.
  8. 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.

  9. Configure the Return Property Mappings. Click the add button and add the ID property and map it to TabID.
  10. Select the Properties tab and change the step name to Create Tab - Employee.
  11. 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 Manager Sign path.
  12. 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 RecID property into the Recipient ID field.
  13. Configure the Document section. From the New Employee reference, drag the ID property into the Document ID field.
  14. Configure the Tab Details section. In the Label field, type Sign Here and select the Sign Here option from the Type menu.
  15. 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.

  16. Configure the Return Property Mappings. Click the add button and add the ID property and map it to TabID.
  17. Select the Properties tab and change the step name to Create Tab - Manager.
  18. From the Toolbox, click the Logic category and then drag the Merge step onto the canvas. Connect the step to the Create Tab - Employee and Create Tab - Manager steps.
  19. Click the Merge tab and select the Split step from the Link To menu. Select the Wait for all followed paths to be completed logic.

In this step, add the Send Envelope step to send the item to the recipients for signature.

  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 Merge 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.
  3. Configure the Return Property Mappings. Click the add button and add the Status property and map it to Status.

In this step, you 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 Send Envelope step.
  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.

In this step, you a Task step.

  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. In 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 RecID 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.
  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.

In this step, you run 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 (Peter Crawford) by email for him to sign. From there it is sent to the Peter's manager (Bob) via a Workspace 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. Click Save. To download a sample of the employee contract, click here.
  3. Open Workspace and log in as Codi. On the HR Approval task, select Approve and then click Submit.
  4. The DocuSign process starts. The employee (Peter Crawford) receives and 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 as Peter Crawford and click Finish.
  6. The contract now needs to be signed by Peter's manager Bob. Open Workspace and log in as Bob. Select the Embedded Sign Task assigned to Bob. The DocuSign experience shows in the task. 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.
  • If the DocuSign feature is not activated you do not see the DocuSign steps in the K2 Workflow Designer. Check with your K2 administrator to make sure the feature is activated and that you are running the correct version of K2
  • When setting up DocuSign you typically activate it using a developer account. If you or your company already have a DocuSign account, you may use that instead. Check with your DocuSign representative for more information on how to configure the K2 DocuSign feature or see the DocuSign Feature Activation topic
  • Once you have created your K2 workflow, you can deploy it to a production environment. For more information see the following Knowledge Base article for the deployment steps. KB001689 - How To: Deploy a DocuSign integrated workflow