K2 BLACKPEARL - COSIGN SERVICE INTEGRATION
TECHNICAL GUIDE | MIKE MORSE
8/12/2013
K2 BLACKPEARL - COSIGN SERVICE INTEGRATION
© 2013 SOURCECODE TECHNOLOGY HOLDINGS, INC. 1
Contents
Introduction ......................................................................................................................................2
Summary of Service Broker Functionality ........................................................................................2
Service Object Definitions ................................................................................................................3
Signature Field Service Object .........................................................................................................3
Properties ....................................................................................................................................3
Methods ......................................................................................................................................4
Additional Method Details .............................................................................................................4
User Service Object .........................................................................................................................5
Properties ....................................................................................................................................6
Methods ......................................................................................................................................6
Additional Method Details .............................................................................................................7
Registering The CoSign Service Broker ...........................................................................................7
Assemblies Needed.........................................................................................................................7
Add The New Service Type ..............................................................................................................7
Register a Service Instance..............................................................................................................8
CoSign Client Configuration .............................................................................................................9
Examples of Usage ......................................................................................................................... 11
User Management ......................................................................................................................... 11
Execution from Workflow ............................................................................................................... 12
Basic Signing and Workflow Task Page .......................................................................................... 13
K2 BLACKPEARL - COSIGN SERVICE INTEGRATION
© 2013 SOURCECODE TECHNOLOGY HOLDINGS, INC. 2
INTRODUCTION
Digital signatures are key to many document processes, but traditionally, this has been a cumbersome
and expensive solution to deliver. Now K2, with its award-winning platform for business applications, has
partnered with CoSign by ARX, a leader in the world of digital signature technology, making it easier than
ever to integrate digital signatures into a broad range of processes while maintaining rich auditability,
tracking and integrity of the documents.
Regardless of process type and which repository the documents live in, users can apply digital signature
placeholders to one or more documents, no matter how many people are involved in the signing process.
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 consist of two primary service objects and their associated properties and methods (diagram
below of methods). At the core of the broker is three cores functional areas.
1. The ability to perform user management functions of CoSign user accounts.
2. The ability to create digital signature field(s) on-the-fly as part of a K2 forms application
of from within running K2 process instances.
3. The ability to digitally sign documents using the CoSign user accounts.
K2 BLACKPEARL - COSIGN SERVICE INTEGRATION
© 2013 SOURCECODE TECHNOLOGY HOLDINGS, INC. 3
SERVICE OBJECT DEFINITIONS
SIGNATURE FIELD SERVICE OBJECT
The Signature Field service object is responsible for performing all actions as it pertains to the creation
and placement of signature fields as well as digitally signing signature fields. The following tables list and
describe all properties and methods.
Properties
Name Description
Anchor Text* The textual marker within a document for which to search. Used for
creating signature fields when specific page number and x,y coordinates
may not be known.
*Used only for specific methods
Display Graphical Image Specified that a graphical signature should be used in place of a system
generated signature.
Display Logo Specified to display logo if applicable.
Display Signed By Display the name of the signer as part of the signature.
Display Signing Reason Display the reason for signing if one had been supplied.
Display Signing Time Display the date and time of signing.
File The input or output fi le depending on the executed method.
File Path* The fi le system location of the document.
* Used only for specific methods.
Height The height of the signature field.
Is Signed Specified if the signature field has been signed.
Name The name of the signature field.
Page The page number of the signature field.
Signed By The user that signed the signature field
Signed On The data in which the signature field was signed.
Signing Reason The reason for signing
K2 BLACKPEARL - COSIGN SERVICE INTEGRATION
© 2013 SOURCECODE TECHNOLOGY HOLDINGS, INC. 4
Width The width of the signature field.
Methods
Name Description
Create Creates a new signature field with the specified options. Requires a fi le as
input and returns a fi le as output. Page number and x, y coordinates are
required as input.
Clear Clear a signature field of its current signature so that it can be resigned by another user.
Create from Anchor Create a new signature field with the specified options based on textual content that is to be located within the input fi le. Page number and x, y
coordinates are not required with Anchor methods.
Create Local Creates a new signature field with the specified options however this method takes a fi le path location for the input document. This method can
be useful when multiple calls to the same fi le will be made in order to reduce the overhead passing documents between each smart object call.
Create Local from Anchor A combination of Create From Anchor and Create Local.
Delete Removes a signature field from the document.
Load Return the properties of a given signature field.
List Returns a l ist of all signature fields and associated properties within the input document.
Sign Signs the specified signature field with the given input credentials.
Additional Method Details
Create & Create Local
These two methods require that you know up front the exact desired location for the new signature field(s)
that you want to create. For example, you will need to know the page number in addition to its positioning
(x and y coordinates) within that page. For documents that are static and are not dynamically generated
or documents that always contain a signing page in a static location (the first or last page of the document
for example) this may be a good option. The difference between Create and Create Local is that Create
Local expects that the document will reside on the file system so you will be required to specify and
additional input parameter File Path when executing this call. Create allows you to pass a file directly into
the method execution and in turn pass the resulting file directly back.
K2 BLACKPEARL - COSIGN SERVICE INTEGRATION
© 2013 SOURCECODE TECHNOLOGY HOLDINGS, INC. 5
Create from Anchor & Create from Anchor Local
In contrast to ‘Create’ and ‘Create Local’ these two methods do not require you to know the exact
positioning of the signature field at design time. Instead when executing these methods you will be
required to pass an input property of ‘Anchor Text’. The Anchor Text specified will then be located within
the document to determine the page number and x,y coordinates for you.
Note: Your Anchor Text input value must be wrapped in an opening and closing pattern. For example
within your document you can place the text <<CFO Signature>> or [[CFO_Signature]] as both are
valid Anchors, however just “CFO Approval” is not. Additionally it is recommended that you’re
Anchor’s font color match that of your document’s background color so that it can remain hidden.
List & Load
The two methods allow you to return the details of one or more signature fields within the document.
Delete
Allows you to remove a signature field from within the document.
Sign
Allows you to sign a given signature field within the specified input document. Aside from the input
properties this method has a few method parameters that are worth mentioning.
User Name: This is the Name of the CoSign user to authenticate with against the CoSign
appliance.
Password: The password associated with the user.
Graphical Image Name: This is an optional parameter. You can specify this parameter when you
have uploaded a rasterized image of signature to the CoSign appliance and you would like to
apply that image during signing.
USER SERVICE OBJECT
The User service object allows you to perform all functions as it pertains to the management of the
CoSign appliance users.
Note: With the exception of the Verify Login method all other methods will require credentials of a
user that has permissions to perform the particular user management function. This means that all
other methods require the Login Username and Login Password to be specified for execution.
K2 BLACKPEARL - COSIGN SERVICE INTEGRATION
© 2013 SOURCECODE TECHNOLOGY HOLDINGS, INC. 6
Properties
Name Description
Display Name Display name of the CoSign user account. Not be confused with the Name
property.
Can Login Value indicating whether a login attempt was successful.
Certificate Status
Email Address Email address of the user account as it exist within CoSign.
Login Status Indicated whether the user is disabled or enabled.
Login Username The Name of the account to be used when performing the specified service object method.
Login Password The password associated with the specified Login Username.
Name* Name of the user account. Unlike Display Name the Name property is used during authentication with the CoSign appliance when executing the Sign method.
Methods
Name Description
Create Creates a new account within the CoSign appliance that can then be used
for signing documents.
Delete Delete a user account.
Disable Disable the user account.
Enable Enable the user account.
List Returns a l ist of user accounts and associated properties.
Load Loads a single user account.
Reset Password Change the password for the specified user account.
Verify Login Performs a logon attempt to the CoSign appliance to ensure the specified user’s Name and Password are valid.
K2 BLACKPEARL - COSIGN SERVICE INTEGRATION
© 2013 SOURCECODE TECHNOLOGY HOLDINGS, INC. 7
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.
REGISTERING THE COSIGN 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.SmartObjects.Services.CoSign.dll
Interop.SAPILib.dll
Interop.SAPIUMCOMLib.dll
ADD THE NEW SERVICE TYPE
Follow these steps to quickly register the new CoSign service broker with your K2 blackpearl server.
1. Drive:\Program Files (x86)\K2 blackpearl\Bin\SmartObject Service Tester.exe
2. Within the toolbar click Register ServiceType
3. Using the Service pull down menu select:
SourceCode.SmartObjects.Services.CoSign.CoSignService
a. Provide a system name, display name and description.
b. Click Add.
K2 BLACKPEARL - COSIGN SERVICE INTEGRATION
© 2013 SOURCECODE TECHNOLOGY HOLDINGS, INC. 8
REGISTER A SERVICE INSTANCE
1. Within the SmartObject Service Tester click Register ServiceInstance .
2. Using the Service Types pull down select the newly added CoSign service type.
3. In the Service Keys section specify wether you plan to integrate in Directory Independent mode
or Active Directory mode.
Note: When Directory Independent mode is set to true users will authenticate against the
CoSign appliances internal auth store. When set to false, you must additionally provide the
Domain service key value which you’re CoSign appliance is installed to authenticate against.
4. Click Next.
a. Provide a system name, display name and description.
b. Click Add.
K2 BLACKPEARL - COSIGN SERVICE INTEGRATION
© 2013 SOURCECODE TECHNOLOGY HOLDINGS, INC. 9
5. Specify the
6. You can now expand the ServiceObject Explorer node and see the newly created service type,
instance and associated service objects.
COSIGN CLIENT CONFIGURATION
In order for the K2 server to communicate with the CoSign appliance to perform all of the operat ions
outlined within this document it is required to install the CoSign client software on the K2 server itself. The
client configuration is slightly different when it is going to run as a service rather than when the client is
installed on a user’s desktop. The following screens show possible configurations for the CoSign client
only as it pertains to the K2 server running as a service. The most important option to note is the ‘Deny
Login dialog pop-up except for designated applications’. Since the K2 server will be passing credentials
with each service call it’s important to ensure the CoSign client does not attempt to additionally prompt it
for credentials. Additionally you could ‘Disable login dialog’ altogether but you may want to use some of
the CoSign applications or Microsoft Word integration on the K2 server. Enable those application to
permit login pop-ups as needed.
If you have registered K2 / CoSign Broker in “Directory Independent” mode you can use the following
recommended settings:
K2 BLACKPEARL - COSIGN SERVICE INTEGRATION
© 2013 SOURCECODE TECHNOLOGY HOLDINGS, INC. 10
K2 BLACKPEARL - COSIGN SERVICE INTEGRATION
© 2013 SOURCECODE TECHNOLOGY HOLDINGS, INC. 11
If you have registered K2 / CoSign Broker in “Active Directory” mode (Directory Independent = false) you
can use the following recommended settings:
EXAMPLES OF USAGE
USER MANAGEMENT
The following screens illustrate a very simple K2 smartforms application that can be used to empower
users to manage CoSign users from a web based application.
K2 BLACKPEARL - COSIGN SERVICE INTEGRATION
© 2013 SOURCECODE TECHNOLOGY HOLDINGS, INC. 12
EXECUTION FROM WORKFLOW
The following snippet of a K2 workflow process generates and password for a newly request CoSign user
accounts, provisions the account and sets the user’s password, creates two signature fields within a
contract and send the contract for approval and signing to the newly created user account.
K2 BLACKPEARL - COSIGN SERVICE INTEGRATION
© 2013 SOURCECODE TECHNOLOGY HOLDINGS, INC. 13
BASIC SIGNING AND WORKFLOW TASK PAGE
The following depicts a K2 smartforms form that enables the user to review document he is being asked
to sign. The user can provide their credentials and choose to sign the document or choose to not sign the
document and select a workflow action that returns the document for corrections as an example.
K2 BLACKPEARL - COSIGN SERVICE INTEGRATION
© 2013 SOURCECODE TECHNOLOGY HOLDINGS, INC. 14
Top Related