K2 blackpearl - CoSign Service Integration

K2 BLACKPEARL - COSIGN SERVICE INTEGRATION

TECHNICAL GUIDE | MIKE MORSE

8/12/2013


© 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



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.



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



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.



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.



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.



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.



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.



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:





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.



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.



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.



Date post:	03-Feb-2017
Category:	Documents
Upload:	dangnhan
View:	215 times
Download:	1 times

K2 blackpearl - CoSign Service Integration

Documents