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.
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
© 2019 - OneSpan North America Inc. 2
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.
OneSpan Sign for Pegasystems QuickStart Guide
© 2019 - OneSpan North America Inc. 3
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.
OneSpan Sign for Pegasystems QuickStart Guide
© 2019 - OneSpan North America Inc. 4
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.
OneSpan Sign for Pegasystems QuickStart Guide
© 2019 - OneSpan North America Inc. 5
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
OneSpan Sign for Pegasystems QuickStart Guide
© 2019 - OneSpan North America Inc. 6
To get a response from OneSpan Sign once a transaction has completed, you must do the following:
1. Log in to your Pegasystems system.
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.
OneSpan Sign for Pegasystems QuickStart Guide
© 2019 - OneSpan North America Inc. 7
1.0.6 Specifying OneSpan Sign API Configurations in PegasystemsTo make any desired OneSpan Sign API configurations within Pegasystems:
1. Log in to your Pegasystems system.
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.
OneSpan Sign for Pegasystems QuickStart Guide
© 2019 - OneSpan North America Inc. 8
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.
OneSpan Sign for Pegasystems QuickStart Guide
© 2019 - OneSpan North America Inc. 9
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.
.
OneSpan Sign for Pegasystems QuickStart Guide
© 2019 - OneSpan North America Inc. 10
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
No Specific Response DT
Docu-ment Vis-ibilty API
OS_SetDocu-mentVisibility
OS_SetDocVis-ibilityRequest
No Specific Response DT
Send Trans-
OS_SendTransaction No Specific request DT No Specific Response DT
OneSpan Sign for Pegasystems QuickStart Guide
© 2019 - OneSpan North America Inc. 11
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
No Specific Response DT
Down-load Attach-ments
OS_Down-loadAttachment
OS_Down-loadAt-tachmentRequestGET
No Specific Response DT
Down-load Evid-ence Summary
OS_RetrieveEvid-enceSummary
OS_RetrieveEvid-enceSummaryRequest GET
No Specific Response DT
Down-load Signed Docu-ments
OS_RetrievePDFDocu-ment
OS_RetrievePDFDocu-mentRequestGET
No Specific Response DT
Set Field Values
OS_UpdateFieldsOf Document
OS_UpdateFieldsRe questPOST
No Specific Response DT
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.
OneSpan Sign for Pegasystems QuickStart Guide
© 2019 - OneSpan North America Inc. 12
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-
OneSpan Sign for Pegasystems QuickStart Guide
© 2019 - OneSpan North America Inc. 13
Property Name Example Values Description
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
OneSpan Sign for Pegasystems QuickStart Guide
© 2019 - OneSpan North America Inc. 14
Property Name Example Values Description
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
OneSpan Sign for Pegasystems QuickStart Guide
© 2019 - OneSpan North America Inc. 15
Property Name Example Values Description
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
OneSpan Sign for Pegasystems QuickStart Guide
© 2019 - OneSpan North America Inc. 16
Property Name Example Values Description
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,
OneSpan Sign for Pegasystems QuickStart Guide
© 2019 - OneSpan North America Inc. 17
Property Name Example Values Description
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,
OneSpan Sign for Pegasystems QuickStart Guide
© 2019 - OneSpan North America Inc. 18
Property Name Example Values Description
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
OneSpan Sign for Pegasystems QuickStart Guide
© 2019 - OneSpan North America Inc. 19