OneSpan Sign for PegasystemsPegasystems is the leader in software for customer engagement and operational excellence. OneSpan is a global leader in digital-identity security, transaction

OneSpan Sign for Pegasystems

Quickstart Guide

Version 1.0 - January 28, 2020

Pegasystems provides an industry-leading Customer Engagement and Digital Process Automation platform. Powered by advanced artificial intelligence and robotic automation, that platform achieves breakthrough business outcomes with low- code/no-code. Pegasystem’s adaptive, cloud-architected software empowers people to rapidly deploy and easily change applications to meet their strategic business needs. Pegasystems is the leader in software for customer engagement and operational excellence.

OneSpan is a global leader in digital-identity security, transaction security, customer on-boarding, and business productivity. OneSpan is the essential foundation for delivering industry-leading secur-ity and e-signature solutions. Those solutions protect people, devices and transactions from fraud, providing rock-solid security and a frictionless customer experience. This enables even the most reg-ulated companies to drive bold digital transformation and to deliver powerful digital interactions with their customers.

The OneSpan Sign for Pegasystems connector enables you to securely send and sign documents ‘out of the box’, and to fully integrate e-signatures within your internal, customer-facing and partner-

© 2019 - OneSpan North America Inc. 1

NOTE: This PDF is no longer being maintained. For the latest updates, please refer to our Community Portal.

http://www.onespan.com/

https://community.onespan.com/documentation/onespan-sign

facing web and mobile applications. More specifically, OneSpan Sign for Pegasystems enables your users to initiate a workflow for preparing and signing documents from any custom-built Pegasys-tems processs or out-of-the-box strategic application. Because OneSpan Sign is fully integrated with Pegasystems, the experience is highly intuitive.

OneSpan Sign for Pegasystems is ideal for ad-hoc as well as on-demand signing. It extends the end-point of your organization’s digitization efforts, giving your customers, partners and employees true end-to-end automated processes with paperless document signing.

This guide discusses:

l Configuring OneSpan Sign for Pegasystems on page 2

l Checking a Transaction's Status on page 9

l API Details on page 11

l Specifying & Retrieving Field Values on page 12

Configuring OneSpan Sign for Pegasystems

To configure OneSpan Sign for Pegasystems, follow the instructions in these sections:

1. Satisfying the Prerequisites on page 2

2. Downloading & Importing the Connector on page 3

3. Adding Required Rulesets to your Application on page 4

4. Configuring the Application Flow on page 4

5. Configuring OneSpan Sign Account Details in Pegasystems on page 6

6. Specifying OneSpan Sign API Configurations in Pegasystems on page 8

1.0.1 Satisfying the PrerequisitesBefore you install OneSpan Sign for Pegasystems, you must have the following:

l A Pega account. To sign up for a Pega account, click here.

l A OneSpan Sign account. To get a OneSpan Sign account, contact our Support Team.

l Pegasystems 7.3.1 or higher

OneSpan Sign for Pegasystems QuickStart Guide


https://accounts.pega.com/register

https://www.esignlive.com/customer-support


1.0.2 Downloading & Importing the ConnectorDownload and import OneSpan Sign for Pegasystems by doing the following:

1. In the Pega Marketplace, locate and download the OneSpan Sign for Pegasystems applic-ation. Note the location to which you download this file.

2. Login to your Pegasystems system.

3. Click Designer Studio > Application > Distribution > Import.

4. Select the Local file method.

5. Select Choose File, then browse to and select the OneSpan Sign for Pegasystems con-nector you downloaded earlier.

6. Click Next, and continue with the usual Pegasystem import process. For more information on this process, refer to Pega online help.



https://community.pega.com/sites/default/files/help_v82/procomhelpmain.htm#tools/moverules/moverules4.htm


1.0.3 Adding Required Rulesets to your ApplicationAdd the required rulesets to your application by doing the following:

1. Log in to your Pegasystems system.

2. Open your application definition by clicking Application > Definition.

3. In the Application rulesets section, click Add ruleset.

4. Add the following rulesets to the list of your application's rulesets:

l OneSpan:01-01

l OSpanInt:01-01

1.0.4 Configuring the Application FlowOnce you have added the required rulesets to your Pegasystems system, you should be able to see OS_SigningProcess flow in the Work-Class.

TIP: Use the Search bar at the top of screen to search for and open OS_SigningProcess.

To use this pre-defined flow, you must call it using the Subprocess Smart Shape.




You must customize this Data Transform OS_pyPrepareNew Package in your application's Work Class as per your requirements.

Use the OS_Package Property of class Work-. This page will be passed as an input reference to 'Create Esign Package' smart shape.




1.0.5 Configuring OneSpan Sign Account Details in PegasystemsTo enable your OneSpan Sign account to work with your Pegasystems account:

1. Login to your Pegasystems system.

2. Using the Search bar at the top of screen, search for and open OS_LoadAp-plicationSettings.

3. Using the drop-down list on the Save button, click Save as in your ruleset.

4. Locate the OS_APIKey target. Then, using the following format, change the source column so it points to your OneSpan Sign account:

"BASIC" + <"OneSpan Sign Account API Key">

NOTE: For information on how to find your OneSpan Sign API Key, see Integration.

5. Locate the OS_EndPointUR target. Then change the source column so it points to your OneSpan Sign API EndPoint URL — e.g: https://sandbox.esignlive.com/api/packages



https://sandbox.esignlive.com/api/packages


To get a response from OneSpan Sign once a transaction has completed, you must do the following:


2. In the Designer Studio search bar, enter Ospan Events.

3. Open the Service REST rule, and copy the service End Point URL.

4. Navigate to the following URL: https://sandbox.esignlive.com/a/admin/integration

5. Paste the Service Rest rule End Point URL that you copied above into the Call Back URL Text Box.

6. Enter the following Callback Key: T25lU3BhblNlcnZpY2VVc2VyOnJ1bGVz

7. In the Select events section, enable the Transaction completed event.

8. Click Save.



https://sandbox.esignlive.com/a/admin/integration


1.0.6 Specifying OneSpan Sign API Configurations in PegasystemsTo make any desired OneSpan Sign API configurations within Pegasystems:


2. In the Designer Studio search bar, enter OS_CreateESignPackage. It employs the following OneSpan Sign API calls:

l Create E Sign Package API: Determines if a transaction can be created without a document attached to it.

l Clone Package API: Clones an existing transaction or template.

l Upload Documents API: Enables the uploading of one document at a time. If you have multiple documents, you can loop this call for each document.

l Set Field Values API: Sets default values in a transaction’s fields from data within Pegasystems, or from the application workflow. You can also put tag val-ues directly in a document. You can use this API call separately, or you can add a document's field values in the Upload Documents API.

l Extraction : Defines the extraction method to be used (e.g., Text Tag Extrac-tion).

l Reminder Schedule API: Sends reminders to signers that a transaction awaits their signature.




l Set Document Visibility: Hides documents from individual signers.

l Send Transaction: Sends a transaction.

Checking a Transaction's Status

To check the status of a transaction:

l Use the API call Check for Status Update API.

The OS_CheckForStatusUpdate API call employs the following API calls:

l Get Package Information: Retrieves transaction details, such as the full transaction metadata (JSON payloads).

l Download the attachment: Downloads any attachments that signers may have added.

l Download Evidence Summary: Downloads the log for a particular transaction.

l Download Signed Document: Downloads any signed documents that are associated with the transaction.

l Retrieve Field Values: Retrieves field values from the transaction's documents.

The rest of this section discusses:

l Configuring Status Checks on page 9

l The Process Flow for Status Updates on page 10

1.0.7 Configuring Status ChecksIn certain situations, such as during a network failure, OneSpan Sign may not be able to reach Pegasystems. However, you can configure the system to check for status updates on a particular transaction at a pre-defined interval rate. Once the network is connected again, the transaction status will be sent.

To configure such status checks:

l Use the API call OS_WaitTimeInterval API.




NOTE: The Dynamic System Setting that specifies the interval (in minutes) is: OS_WaitTimeInterval. The recommended interval is 12 hours (= 720 minutes).

1.0.8 The Process Flow for Status UpdatesStatus updates from OneSpan Sign are sent to Pegasystems in the following scenarios:

l Scenario 1: The status update successfully reaches Pegasystems. In this case:

l The updated status can be Completed, Declined, or Pending.

l When the incoming status for a transaction is Completed, the system downloads the transaction's signed documents, Evidence Summary, and attachments.

l Scenario 2: The status update doesn’t reach Pegasystems (e.g., because of a network issue). In this case:

l The system will wait for the amount of time specified in the DSS OS_WaitTimeInterval.

l Once that time interval has elapsed, the system checks for a status update for the transaction. Again, the updated status can be Completed, Declined, or Pending.

l If the system returns a transaction status of Pending, the system will once again wait for the amount of time specified in DSS OS_WaitTimeInterval.

l If the system returns a transaction status of Declined, the process flow com-pletes, but without downloading any documents or attachments.

l If the system returns a transaction status of Completed, the system downloads the transaction's signed documents, Evidence Summary, and attachments.

.




API Details

The following table provides information about all OneSpan Sign for Pegasystems API calls.

API Activity Request DT Response DT

Create ESign Package API

OS_CreateESignPack-ageAPI

OS_NewPkgRequestPOST No Specific Response DT

Cloning a Package/ Template

OS_ClonePackage OS_ClonePack-ageRequestPOST

No Specific Response DT

Upload-ing the Docu-ment

OS_UploadSingleDocu-mentAPI

OS_UploadDocuments OS_SingleDocRe-sponsePOST

Reminde-r Sched-ule API

OS_SetRe-minderSchedule

OS_Pack-ageReminderRequestPOST


Docu-ment Vis-ibilty API

OS_SetDocu-mentVisibility

OS_SetDocVis-ibilityRequest


Send Trans-

OS_SendTransaction No Specific request DT No Specific Response DT




API Activity Request DT Response DT

actionGet Pack-age Info API

OS_RetrievePack-ageInformation

OS_RetrievePack-ageInformationRequest GET

OS_RetrievePack-ageInformationR esponseGET

Get Pack-age Status

OS_Pack-ageSigningStatus(connector)

OS_Pack-ageSign-ingStatusRequestGET


Down-load Attach-ments

OS_Down-loadAttachment

OS_Down-loadAt-tachmentRequestGET


Down-load Evid-ence Summary

OS_RetrieveEvid-enceSummary

OS_RetrieveEvid-enceSummaryRequest GET


Down-load Signed Docu-ments

OS_RetrievePDFDocu-ment

OS_RetrievePDFDocu-mentRequestGET


Set Field Values

OS_UpdateFieldsOf Document

OS_UpdateFieldsRe questPOST


Retrieve Field Val-ues

OS_GetDocu-mentFieldValues

OS_RetrieveFieldVal-uesRequestGET

OS_RetrieveFieldVal-uesResponse GET

Specifying & Retrieving Field Values

To specify field values for a transaction:

l Customize the API call OS_UpdateFieldsRequestPOST Data Transform. This is called after a document is uploaded to a transaction.

To retrieve all field values for a transaction:

l Customize the API call Data Transform OS_RetrieveFieldValuesResponseGET. This is called when a transaction is completed.




1.0.9 OS_NewPkgRequestPOST

Property Name Example Values Description

Package Related Properties OS_Package OS_auto-

completetrue/false Set Boolean value

when we want the doc-ument to be reviewed before completion

OS_description Package description from the back end

Package description

OS_emailMes-sage

Package email message from the back end

Set the message to the send along with the mail

OS_email [email protected] Sender Email Address OS_firstName Example Sender First Name OS_lastName Test Sender Last Name OS_language en Package language

should be any one of the following en, fr, da, de, es, el, it, nl, pt,ru, zh-cn, zh-tw, ja, ko

OS_name Package name set in back end

Package Name

OS_due 20181019 Expiry Date for Pack-age

OS_status

SENT/DRAFT

Status should be any one of the following DRAFT, SENT, COMPLETED, ARCHIVED, DECLINED, OPTED_OUT, EXPIRED

OS_type PACKAGE Type should be one of the following values PACKAGE, TEMPLATE, LAYOUT

OS_visibility ACCOUNT/SENDER Visibility of the Pack-age

OS_roles Set the list of roles having access to this package OS_id Role1 Enter the string

without special char-



mailto:[email protected]



acters OS_name Role1 Enter the role name OS_index 1 Set integer value if you

want to set signing order

OS_signers Set the list of signers available for particular role in this package OS_email [email protected] Signer Email Id OS_firstName Test First Name of the

Signer OS_id TM Enter the value

without special chars OS_title Mr Title of the signer OS_company OneSpan Company of the Signer OS_lastName mail Last Name of the

Signer

OS_auth Enter the authentication method before signing the document for futher details

OS_ scheme NONE Scheme should be any one of the following NONE, PROVIDER, CHALLENGE, SMS, SSO, KBA

OS_chal-lenges

This needs to be set when auth scheme is SMS and Q & A

OS_ question What is your Pet Name? Enter the question and it will be asked before signing the document

OS_answer XXX Enter answer for the question

OS_maskInput true/false Boolean allows the answer entering by the signer is visible or not

OS_delivery Delivery of the Signed Document OS_email true/false Set the boolean value

whether the doc-ument needs to be delivered by mail after signing






OS_settings Package level settings OS_cere-

mony.OS_ inPer-son

true/false Set the boolean value

OS_Package Package Releated Properties OS_packageId XXXXXXXX Set the Template ID OS_auto-

completetrue/false Set Boolean value

when we want the doc-ument to be reviewed before completion

OS_description Package description from the back end

Package description

OS_emailMes-sage

Package email message from the back end

Set the message to the send along with the mail

OS_email [email protected] Sender Email Address OS_firstName Example Sender First Name OS_lastName Test Sender Last Name OS_language en Package language

should be any one of the following en, fr, da, de, es, el, it, nl, pt,ru, zh-cn, zh-tw, ja, ko

OS_name Package name set in back end

Package Name

OS_due 20181019 Expiry Date for Pack-age

OS_status SENT/DRAFT Status should be any one of the following DRAFT, SENT, COMPLE- TED, ARCHIVED, DECLINED, OPTED_OUT, EXPIRED

OS_type PACKAGE Type should be one of the following values PACKAGE, TEMPLATE, LAYOUT

OS_roles Set the list of roles having access to this package






OS_id Role1 Enter the string without special char-acters

OS_name Role1 Enter the role name OS_index 1 Set integer value if you

want to set signing order

OS_signers Set the list of signers available for particular role in this package OS_email [email protected] Signer Email Id OS_firstName Test First Name of the

Signer OS_id TM OS_title Mr Enter the value

without special chars OS_company OneSpan Company of the Signer OS_lastName mail Title of the signer

OS_auth Enter the authentication method before signing the document for futher details

OS_scheme NONE Scheme should be any one of the following NONE, PROVIDER, CHALLENGE, SMS, SSO, KBA

OS_chal-lenges

This needs to be set when auth scheme is SMS and Q & A

OS_question What is your Pet Name? Enter the question and it will be asked before signing the document

OS_answer XXX Enter answer for the question

OS_maskInput true/false Boolean allows the answer entering by the signer is visible or not

OS_delivery Delivery of the Signed Document OS_email true/false Set the boolean value

whether the doc-ument needs to be delivered by mail after






signing

OS_settings Package level settings OS_cere-

mony.OS_inP erson

true/false Set the boolean value

OS_Pack-age.OS_ doc-uments

Package Related Properties

OS_id NDAAgreeement Set the Document ID OS_name NDAAgreeement Set the Document

Name OS_description NDA Agreement For

EmployeesSet the Document Description

OS_extract true/false Boolean Value

OS_approvals

Approval/Role Details

OS_id Role1 Set the Role ID from Package Creation

OS_name Role1 Set the Role Name from Package Creation

OS_role Role1 Set the Role from Pack-age Creation

OS_fields Field Related Details OS_id myLabelField Set the Field Id OS_height 50 Set the Height Align-

ment OS_left 100 Set the Left Alignment OS_name SIGNATURE Set the Field Name OS_page 0 Set the Page OS_ subtype FULLNAME Set the Field Subtype

(Subtype can be any one of FULLNAME, INITIALS, CAPTURE, LABEL, TEXTFIELD, TEXTAREA, CHECKBOX, DATE, RADIO, LIST, QRCODE, CUSTOMFIELD, SEAL,





MOBILE_CAPTURE, RAW_CAPTURE, DATEPICKER)

OS_top 900 Set the Top Alignment OS_type SIGNATURE Set the Field Type OS_width 200 Set the Width Align-

ment OS_id myLabelField Set the Field Id OS_height 50 Set the Height Align-

ment OS_left 100 Set the Left Alignment

OS_Package Interval Related Properties OS_ packageId XXXXXXXX Unique identifier of a

eSignLive package OS_inter-

valInDays0 The time of Interval for

reminder schedule OS_repe-

titionsCount5 The number of repe-

titions OS_

startInDaysDelay1 The time the next

reminder is scheduled to send the package

OS_Package. Document Details OS_packageId XXXX Unique identifier of a

eSignLive package OS_documentId XXXX Set the Document ID OS_approvalId XXXX Set the Approval ID OS_FieldID XXXX Set the Field ID

OS_fields Field Related Details OS_id myLabelField Set the Field Id OS_height 50 Set the Height Align-

ment OS_left 100 Set the Left Alignment OS_name SIGNATURE Set the Field Name OS_page 0 Set the Page OS_ subtype FULLNAME Set the Field Subtype

(Subtype can be any one of FULLNAME, INITIALS, CAPTURE,





LABEL, TEXTFIELD, TEXTAREA, CHECKBOX, DATE, RADIO, LIST, QRCODE, CUSTOMFIELD, SEAL, MOBILE_CAPTURE, RAW_CAPTURE, DATEPICKER)

OS_top 900 Set the Top Alignment OS_type SIGNATURE Set the Field Type OS_width 200 Set the Width Align-

ment


