k2 blackpearl - docusign service...

K2 BLACKPEARL - DOCUSIGN SERVICE INTEGRATION

TECHNICAL GUIDE | MIKE MORSE

5/1/2014


© 2013 SOURCECODE TECHNOLOGY HOLDINGS, INC. 1

Contents

Introduction ................................................................................................................................................. 1

Summary of Service Broker Functionality ............................................................................................... 2

Service Object Definitions .......................................................................................................................... 3

Envelope Service Object ........................................................................................................................... 3

Properties ............................................................................................................................................... 3

Methods ................................................................................................................................................. 4

Document Service Object .......................................................................................................................... 4

Properties ............................................................................................................................................... 4

Methods ................................................................................................................................................. 5

Recipient Service Object ........................................................................................................................... 5

Properties ............................................................................................................................................... 5

Methods ................................................................................................................................................. 7

Additional Method Details ...................................................................................................................... 7

Tab Service Object .................................................................................................................................... 7

Properties ............................................................................................................................................... 7

Methods ................................................................................................................................................. 9

Envelope Audit Events Service Object ...................................................................................................... 9

Properties ............................................................................................................................................... 9

Methods ............................................................................................................................................... 10

Envelope Status Service Object .............................................................................................................. 10

Properties ............................................................................................................................................. 10

Methods ............................................................................................................................................... 11

Registering The DocuSign Service Broker ............................................................................................. 12

Assemblies Needed ................................................................................................................................. 12

Add The New Service Type ..................................................................................................................... 12

Register a Service Instance..................................................................................................................... 12

INTRODUCTION

The demand for electronic signing of documents has been growing at a rapid pace. Electronic signatures

are usually just one part of a larger process. By integrating DocuSign with K2, customers can create end



to end business process applications that require signing without ever leaving the process. By using K2

and DocuSign together, customers can drastically reduce the time it takes to get a signature and maintain

visibility into the process at all times including a full audit trail on the signing steps.

The goal with the K2 and DocuSign integration is to manage the end to end signing setup, signing

management and signing runtime components using DocuSign without needing custom code. The

integrity of the process is maintained, and with real-time visibility into every step of the workflow, all

processes can be tracked to completion

SUMMARY OF SERVICE BROKER FUNCTIONALITY

The broker consists of a number of service objects that you can use to automate and integrate with your

DocuSign instance in easy and no code way. The following is a high level summary of some of the types

of operations you can perform.

1. Envelopes

a. Create, delete, send, void, move, etc.

2. Documents

a. Retrieving, adding, deleting

3. Recipients

a. Add, remove, and get details.

4. Tab

a. Create a number of different tab types

5. Auditing and Status Tracking

a. Various methods to determine the status of an envelope and status of a

recipients signing request.



SERVICE OBJECT DEFINITIONS

ENVELOPE SERVICE OBJECT

The Envelope service object provides the methods for the creation, sending and manipulating of inflight or

completed envelopes. The following tables list and describe all properties and methods.

Properties

Name Description

Envelope Id The unique identifier for each envelope instance.

Allow Reassign If true, the recipient can redirect an envelope to a more appropriate recipient.

Allow Markup If true, Document Markup is enabled for envelope. Account must have Document Markup enabled to use this.

Allow Recipient Recursion

When set to true, this enables the Recursive Recipients feature and allows a recipient to appear more than once in the routing order.

Authoritative Copy Specifies the Authoritative copy feature. If set to true the Authoritative copy feature is enabled.

Brand Id This sets the brand profile format used for the envelope. The value in the string is the Brand Id associated with the profile. Account branding must be enabled for the account to use this option.

Email Blurb Optional element. This is the same as the email body. If specified, it is included in email body for all envelope recipients. This can be a maximum of 10,000 characters.

Email Subject The subject of the email that will be sent to all recipients. This can be a maximum of 100 characters.

Enable Wet Sign If true, the signer is allowed to print the document and sign it on paper.

Envelope Id Stamping If true, Envelope ID Stamping is enabled.

Message Locked If true, prevents senders from changing the Email Blurb and Email Subject for the envelope.

Additionally, this prevents users from making changes to the Email Blurb and Email Subject when correcting envelopes

However, if the Message Lock node is set to True and the Email Subject is empty, senders and correctors are able to add a subject to the envelope.

Status Sets envelope Status. There are two possible values: sent and created.



If Status = sent, the envelope is sent to the recipients. If Status = created, the envelope is saved as a draft and can be modified and sent later.

Methods

Name Description

Create Creates a new envelope and places it into a draft state. Envelope Id will be

returned for future envelope modification.

Send Sends the envelope to the designated recipient list.

Delete Deletes the envelope, envelope must not be in the middle of a signing process.

Move To Folder Moves an existing envelope to a new location.

Void Voids / cancels an envelope that is currently out for signing.

DOCUMENT SERVICE OBJECT

The Document service object allows you attach your documents to your envelopes, retrieve status

information about the documents and finally retrieve the documents as needed.

Properties

Name Description

File The file contents

Name Name of the file.

Order* The order the document should reside within the envelope in the case of multiple documents. *The order doesn’t have to be sequential, for example, your first document could start at order 5 and your second document added at 15. This gives you the opportunity to now place documents in position 1-4 and 6-15.

Pages The total number of pages in the document.

Uri Indicated whether the user is disabled or enabled.



Document Id The unique Id for the document in this specific envelope. This is a user specified value not DocuSign.

Envelope Id The envelope id associated with the document.

Watermark If the account has the watermark feature enabled and the envelope is not complete, the watermark for the account is added to the PDF documents. This option can remove the watermark.

Show Changes When set to true, any changed fields for the returned PDF are highlighted in yellow and optional signatures or initials outlined in red.

Certificate This option can remove the envelope signing certificate from the download.

Methods

Name Description

Get Envelope Document Retrieves a document from the specified envelope.

Delete Envelope Document

Delete a document from an envelope.

List Envelope Documents This returns a list of documents associated with the specified envelope.

Get Envelope Documents Combined

This retrieves a PDF containing the combined content of all documents and the certificate. If the account has the Highlight Data Changes feature enabled, there is an option to request that any changes in the envelope be highlighted.

Add Document To Draft Envelope

This can be used to add one or more documents to an existing draft envelope.

RECIPIENT SERVICE OBJECT

The Recipient service object allows you to add, remove and get recipient details for a particular envelope

Properties

Name Description

Envelope Id The unique envelope identifier.

Name Full legal name of the recipient. This can be a maximum of 100 characters.



Access Code This Optional element specifies the access code a recipient has to enter to validate the identity. This can be a maximum of 50 characters.

Add Access Code to Email

This Optional attribute indicates that the access code will be added to the email sent to the recipient; this nullifies the Security measure of Access Code on the recipient.

Client User Id* This specifies if the recipient is embedded or remote.

If the Client User Id is not null then the recipient is embedded.

*This is required if the signer is an offline signer.

Recipient Id Unique for the recipient. It is used by the tab element to indicate which recipient is to sign the Document. This is a user provided Id.

Note A note that will be unique to this recipient. This note will be sent to the recipient via the signing email. This note will display in the signing UI near the upper left corner of the document on the signing screen. This can be a maximum of 1,000 characters.

Require Id Lookup If set true then the recipient is required to use the specified ID check method (including Phone and SMS authentication) to validate their identity.

Role Name Optional element. This is the role name associated with the recipient.

Routing Order This element specifies the routing order of the recipient in the envelope.

Auto Navigation Specifies if auto navigation is set for the recipient.

Default Recipient If true, this is the default recipient for the envelope. This option is used with the CreateEnvelopeFromTemplatesAndForms method.

Sign In Each Location If set to true and the feature is enabled in the sender’s account, then the signing recipient is required to draw signatures and initials at each signature/initial tab (instead of adopting a signature/initial style or only drawing a signature/initial once).

Status

Recipient Type Type of Recipient, such as signer, editor etc.

Email Email of the recipient. Notification will be sent to this email id. This can be a maximum of 100 characters.

Signed Date Time Date and time the user signed the document.

Delivered Date Time Date and time in which the user opened/viewed the document it was successfully delivered.



Methods

Name Description

Get Envelope Recipients Returns a list of envelope recipients and delivery and signature date

information.

Add Envelope Signer Adds a new signer recipient to an envelope.

Remove Envelope Recipient

Removes a recipient from an envelope that is un-sent and in draft status.

Additional Method Details

Reset Password

This method contains a required input parameter called New Password which should be set to the

desired new password for the specified user.

TAB SERVICE OBJECT

The Tab service object allows you to automate the creation only of multiple types of DocuSign signature

place holder locations.

Properties

Name Description


Tab Id The unique identifier for the tab.

Anchor String Specifies string searched for to place the tab in the document.

Anchor XOffset This specifies tab location as XOffset position, using the Anchor Units, from the Anchor String.

Anchor YOffset This specifies tab location as YOffset position, using the Anchor Units, from the Anchor String.

Anchor Units Specifies units of the X and Y offset. Units could be pixels, mms, cms or inches.

Conceal Value On Document

Optional element. If true, the field appears normally while the recipient is adding or modifying the information in the field, but the data is not visible (the characters are hidden by asterisks) to any other signer or the sender.



When an envelope is completed the information is available to the sender through the Form Data link in the DocuSign Console.

This setting applies only to text boxes and does not affect list boxes, radio buttons, or check boxes.

Conditional Parent Label

Optional element. For conditional fields this is the TabLabel of the parent tab that controls this tab’s visibility.

Conditional Parent Value

Optional element. For conditional fields this is the Value of the parent tab that controls this tab’s visibility.

If the parent tab is a Checkbox, Radio button, Optional Signature, or Optional Initial use “on” as the value to show that the parent tab is active.

Document Id This is the Document Id number that the tab is placed on. This must refer to an existing Document’s ID attribute.

Locked Signer cannot change the data of the custom tab if true.

Page Number* This specifies the page number where the tab will be affixed. *Not used with Anchoring

Recipient Id This specifies the recipient whose signature is needed on the document. Must refer to an existing recipient’s ID attribute.

Required If true, the signer is required to fill out this tab.

Template Locked Optional element. Used only when working with template tabs. If true, the attributes of the tab cannot be changed by the sender.

Template Required Optional element. Used only when working with template tabs. If true, the tab cannot be removed by the sender.

X Position* This indicates the horizontal offset of the tab on the page, in a coordinate space that has left top corner of the document as origin. *Note used with Anchoring

X Position* This indicates the vertical offset of the tab on the page, in a coordinate space that has left top corner of the document as origin. *Note used with Anchoring

Name The names associated with the tab type. Set to Text for a Text tab.

Optional



Scale Value Sets the size for the Sign Here tab. It can be value from 0.5 to 1.0, where 1.0 represents full size and 0.5 is 50% size.

Tab Label The label used with the tab. This can be a maximum of 500 characters.

Notes:

Making a tab’s TabLabel the same will cause the all like fields to update when the user enters data.

Value This element specifies the value of the tab.

Width Width of the tab.

Methods

Name Description

Create Sign Here Tab Places a tag where the recipient must sign the document.

Create Signer Title Tab Places a tag on the document where you want the recipient’s title to appear.

Create Date Signed Tab Places a tag on the document where you want the date the recipient signed the document to automatically appear.

Create Full Name Tab Places a tag on the document where you want the recipient’s name to appear.

Create Initial Here Tab Places a tag where the recipient must initial the document.

Create Company Name Tab

Places a tag on the document where you want the recipient’s company name to appear.

ENVELOPE AUDIT EVENTS SERVICE OBJECT

The Envelope Audit Events service object provides the ability to retrieve a list of envelope related events

that is tracked by DocuSign. This could be when a user viewed the envelope for the first time or when

they signed or rejected the document.

Properties

Name Description




Log Time The date-time the audit event occurred.

Source The source of the envelope. Values can be web or API.

User Name The name of the user that sent the envelope.

Action The current action status.

Message The message associated with the Action.

Envelope Status Status of the envelope. Values can be Voided, Created, Deleted, Sent, Delivered, Signed, Completed, Declined and TimedOut.

Client IP Address The client IP address associated with the action.

Information Base information associated with the action.

Geo Location The geographic location associated with the action.

Language The language used in the envelope.

Methods

Name Description

List Returns a list of all audit events associated with specified envelope.

ENVELOPE STATUS SERVICE OBJECT

The Envelope Status service object provides slightly different functionality than Audit Event. Its main

purpose is to report the single current envelope status (i.e. Created, Sent) or a complete list of all

envelope status changes (i.e. Created, Sent, Delivered, Signed, Completed, Declined, etc.) and the

associated information about the change.

See Envelope Service Object definition for redundant properties that were all covered by this service

object.

Properties

Name Description




Status The current status of the envelope.

Status Changed Date Time

The time in which the event occurred that caused the envelope status to change.

Delivered Date Time The time in which delivery of the envelope was confirmed.

Sent Date Time The time in which the envelope was sent.

Completed Date Time Time in which the envelope completed all necessary signing and DocuSign actions.

Methods

Name Description

Load Returns the current status of the given envelope id

List Status Changes Returns a list of all status changes for the given envelope id

Important Note! DocuSign has guidelines around requesting an envelope status in accordance to

their rules. Applications should not be requesting status in denial of service fashion and thus at the

time of authoring this document DocuSign states no more frequent than one status check every 15

minutes per envelope. However, you should consult the DocuSign documentation for any changes.

.



REGISTERING THE DOCUSIGN SERVICE BROKER

ASSEMBLIES NEEDED

The following assemblies must be placed on each of your K2 blackpearl servers in the following location:

Drive:\Program Files (x86)\K2 blackpearl\ServiceBroker

SourceCode.DocuSign.Client.dll

SourceCode.SmartObjects.Services.DocuSignService.dll

ADD THE NEW SERVICE TYPE

Follow these steps to quickly register the new DocuSign service broker with your K2 blackpearl server.

1. Launch the SmartObject Service Tester.exe

2. Within the toolbar click Register ServiceType

3. Using the Service pull down menu select:

SourceCode.SmartObjects.Services.DocuSignServiceDocuSignServiceBroker

a. Provide a system name, display name and description.

b. Click Add.

REGISTER A SERVICE INSTANCE

1. Within the SmartObject Service Tester click Register ServiceInstance.

2. Using the Service Types pull down select the newly added DocuSign service type.



3. You must now provide your Account Id, Integrator Key and User/Pass associated with your

DocuSign instance. To get your Account Id and Integrator Key you must login to DocuSign, then

go to Preferences. Under Account admnistrator there’s a heading labeled ‘API’.

4. Click Next.

a. Provide a system name, display name and description.

b. Click Add.



5. You can now expand the ServiceObject Explorer node and see the newly created service type,

instance and associated DocuSign service objects.