▲ Top

OneSpan Sign for Pegasystems

Quickstart Guide

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

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 security and e-signature solutions. It’s security and e-signature solutions protect people, devices and transactions from fraud, providing rock-solid security and a frictionless customer experience. This enables even the most regulated companies to drive bold digital transformation and deliver powerful digital interactions with their customers.

The OneSpan Sign for Pegasystems connector allows you to securely send and sign documents ‘out of the box’, and to fully integrate e-signatures within your internal and customer or partner facing web and mobile applications.. OneSpan Sign for Pegasystems:

  • Allows your users to initiate the document preparation and signing workflow from any out-of-the-box strategic application or custom built Pegasystems processes. As OneSpan Sign is fully integrated with Pegasystems the experiences is highly intuitive.
  • Is ideal for ad-hoc as well as on-demand signing. Using OneSpan Sign for Pegasystems extends the endpoint of your organization’s digitization efforts, giving your customers, partners and employees truly end-to-end automated processes with paperless document signing.

This guide contains the following sections:

Configuring OneSpan Sign for Pegasystems

To configure OneSpan Sign for Pegasystems you must do the following:

Prerequisites

To use OneSpan Sign for Pegasystems you must have the following:

  • A Pega account. To sign up for a Pega account, click here.
  • A OneSpan Sign account. To get a OneSpan Sign account, contact our Support Team.
  • Pegasystems 7.3.1, or later.

Download and Import the OneSpan Sign for Pegasystems Connector

  1. In the Pega Marketplace, search for and download the OneSpan Sign for Pegasystems application. 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 connector you downloaded earlier.
  6. Click Next and continue with the usual Pegasystem import process. For more information on this process, refer to the Pega online help.

Add the required rulesets to your application

  1. Login to your Pegasystems system.
  2. Open your application definition by clicking Application > Definition.
  3. In the Application rulesets section. click Add ruleset. Enter the following rulesets to your application rulesets list:
    • OneSpan:01-01
    • OSpanInt:01-01

Configuring the Application Flow:

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

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 have to customize this Data Transform OS_pyPrepareNew Package in your application 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.

Configure OneSpan Sign Account Details in Pegasystems

Use the following procedure to allow 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_LoadApplicationSettings.
  3. Using the drop-down list on the Save button, click Save as in your ruleset.
  4. Locate the OS_APIKey target and change the source column so that it points to your OneSpan Sign account, using the following format:

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

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

  5. Locate the OS_EndPointUR target and change the source column so that it points to your OneSpan Sign API EndPoint URL. For example, https://sandbox.esignlive.com/api/packages.


Configure OneSpan Sign Account Details in Pegasystems

To get a response from the OneSpan Sign once a transaction has completed you will need to do the following:

  1. Login 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.


Set OneSpan Sign API Configurations in Pegasystems

  1. Login to your Pegasystems system.
  2. In the Designer Studio search bar, enter OS_CreateESignPackage. The following OneSpan Sign APIs are called:
    • Create E Sign Package API: Use this API to set whether or not a transaction can be created without a document attached to it.
    • Clone Package API: Use this API to clone an existing transaction or template.
    • Upload Documents API: Use to allow the uploading of a single document at a time. If you have multiple documents you can loop this call for each document.
    • Set Field Values API: Use to set default values in a transaction’s fields from data within Pegasystems, or from the application workflow. You can also put the values in the tags in the document directly. You can either call this API separately or you can add the field values associated with the document in the upload document API itself.
    • Extraction : Defines the extraction method, either PDF form field, or text tags.
    • Reminder Schedule API: Use this API to send out reminders to signers that they have a transaction waiting for them to sign.
    • Set Document Visibility: Use this API to hide documents from individual signers.
    • Send Transaction: Use this API to send a transaction.

Checking a Transaction's Status

To check the status of a transaction use the Check for Status Update API. The OS_CheckForStatusUpdate calls the following other APIs:

  • Get Package Information: Retrieves transaction details, such as the full transaction metadata (JSON payloads).
  • Download the attachment: Downloads any attachments that signers may have added.
  • Download Evidence Summary: Download the log for a particular transaction.
  • Download Signed Document: Downloads any signed documents that are associated with the transaction.
  • Retrieve Field Values: Retrieves field values from the transaction's documents.

Configuring the Settings for Status Check Polling

In 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 do this, use the OS_WaitTimeInterval API.

The Dynamic System Setting for setting the interval for checking the status is: OS_WaitTimeInterval. Please define the interval to check in minutes. The recommended time interval is 12 hours (720 minutes).

Status Update Process Flow

Status updates are provided under the following two possible scenarios:

  • Scenario 1: The status update comes from OneSpan Sign.
    • Status updates can be Completed, Declined, or Pending.
    • When the incoming status for the particular transaction is completed, all documents and attachments associated with that transaction are downloaded.
  • Scenario 2: The Status Update from OneSpan Sign doesn’t reach Pegasystems. For example, if there is a network issue.
    • The system will wait for the amount of time specified in the DSS OS_WaitTimeInterval.
    • Once this time interval has completed, the system checks for a status update for the transaction. Status updates can be Completed, Declined, or Pending.
    • 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.
    • If the system returns a transaction status of Declined, the process flow completes, but without downloading any documents or attachments.
    • If the system returns a transaction status of Completed, the system downloads all signed documents, evidence summary, and attachments for that transaction, and attaches them to the specific case.

.

API Details

The following table provides information on all OneSpan Sign for Pegasystems APIs.

API

Activity

Request DT

Response DT

Create ESign Package API

OS_CreateESignPackageAPI

OS_NewPkgRequestPOST

No Specific Response DT

Cloning a Package/ Template

OS_ClonePackage

OS_ClonePackageRequestPOST

No Specific Response DT

Uploading the Document

OS_UploadSingleDocumentAPI

OS_UploadDocuments

OS_SingleDocResponsePOST

Reminder Schedule API

OS_SetReminderSchedule

OS_PackageReminderRequestPOST

No Specific Response DT

Document Visibilty API

OS_SetDocumentVisibility

OS_SetDocVisibilityRequest

No Specific Response DT

Send Transaction

OS_SendTransaction

No Specific request DT

No Specific Response DT

Get Package Info API

OS_RetrievePackageInformation

OS_RetrievePackageInformationRequest GET

OS_RetrievePackageInformationR esponseGET

Get Package Status

OS_PackageSigningStatus(connector)

OS_PackageSigningStatusRequestGET

No Specific Response DT

Download Attachments

OS_DownloadAttachment

OS_DownloadAttachmentRequestGET

No Specific Response DT

Download Evidence Summary

OS_RetrieveEvidenceSummary

OS_RetrieveEvidenceSummaryRequest GET

No Specific Response DT

Download Signed Documents

OS_RetrievePDFDocument

OS_RetrievePDFDocumentRequestGET

No Specific Response DT

Set Field Values

OS_UpdateFieldsOf Document

OS_UpdateFieldsRe questPOST

No Specific Response DT

Retrieve Field Values

OS_GetDocumentFieldValues

OS_RetrieveFieldValuesRequestGET

OS_RetrieveFieldValuesResponse GET

Setting and Retrieving Field Values

To set field values, you need to customize the OS_UpdateFieldsRequestPOST Data Transform API. This API is called after a document is uploaded to the package.

To retrieve all field values, you need to customize the Data Transform OS_RetrieveFieldValuesResponseGET. This API is called when the package is completed.

OS_NewPkgRequestPOST

Property Name

Example Values

Description

Package Related Properties

OS_Package

OS_autocomplete

true/false

Set Boolean value when we want the document to be reviewed before completion

 

OS_description

Package description from the back end

Package description

 

OS_emailMessage

Package email message from the back end

Set the message to the send along with the mail

 

OS_email

Example.Test@gmail.com

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 Package

 

 

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 Package

OS_roles

Set the list of roles having access to this package

 

OS_id

Role1

Enter the string without special characters

 

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

Test.mail@gmail.com

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_challenges

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 document needs to be delivered by mail after signing

OS_settings

Package level settings

 

OS_ceremony.OS_ inPerson

true/false

Set the boolean value

OS_Package

Package Releated Properties

 

OS_packageId

XXXXXXXX

Set the Template ID

 

OS_autocomplete

true/false

Set Boolean value when we want the document to be reviewed before completion

 

OS_description

Package description from the back end

Package description

 

OS_emailMessage

Package email message from the back end

Set the message to the send along with the mail

 

OS_email

Example.Test@gmail.com

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 Package

 

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 characters

 

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

Test.mail@gmail.com

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_challenges

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 document needs to be delivered by mail after signing

OS_settings

Package level settings

 

OS_ceremony.OS_inP erson

true/false

Set the boolean value

OS_Package.OS_ documents

Package Related Properties

 

OS_id

NDAAgreeement

Set the Document ID

 

OS_name

NDAAgreeement

Set the Document Name

 

OS_description

NDA Agreement For Employees

Set 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 Package Creation

OS_fields

Field Related Details

 

OS_id

myLabelField

Set the Field Id

 

OS_height

50

Set the Height Alignment

 

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 Alignment

 

OS_id

myLabelField

Set the Field Id

 

OS_height

50

Set the Height Alignment

 

OS_left

100

Set the Left Alignment

OS_Package

Interval Related Properties

 

OS_ packageId

XXXXXXXX

Unique identifier of a eSignLive package

 

OS_intervalInDays

0

The time of Interval for reminder schedule

 

OS_repetitionsCount

5

The number of repetitions

 

OS_startInDaysDelay

1

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 Alignment

 

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 Alignment