Creating OneSpan Sign Transactions Programmatically

OneSpan Sign for Salesforce enables you to create OneSpan Sign transactions programmatically. There are two main ways of doing so:

The following section provides information relevant to both of the above procedures:

The URL that appears in the code examples below must start with the character string /apex/esl__package?. This is the URL required to access a OneSpan Sign package's Visualforce page.

Creating a Transaction from a Custom Button

If you create a Custom Button, and add it to a Salesforce object, the added button enables Salesforce users to send documents to be signed from that object’s records.

You can programmatically create a package from a Custom Button in three ways:

Creating a Transaction from a Template

To create a package programmatically from a template:

  • Write and then run code that will create a package from a template.

You must specify the following template parameters:

  • ParentId
  • Name
  • TemplateId

At the end of this procedure, you should see all the template's information reflected in the created package.

Example

When the following code snippet is run, it creates a OneSpan Sign package from a template for a particular account:

/apex/esl__package?ParentId={!Account.Id}& 
Name={!Account.Name}%20Agreement &TemplateID=a0G360000018BdREAU

Creating a Transaction from a Salesforce ID or an Email Address

To create a package programmatically from a Salesforce ID or an email address:

  • Write and then run code that will create a OneSpan Sign package from a Salesforce ID or an email address.

You must specify the following parameters:

  • Name
  • Documents
  • SignerN — This can be either a Salesforce ID (see Example 1) or an email address for the Nth signer (see Example 2). If SignerN is an email address, the following parameters are also required:
    • SignerNFirstName
    • SignerNLastName

At the end of this procedure, you should see the provided information reflected in the created package.

Example 1

When the following code snippet is run, it creates a OneSpan Sign package from a DynamicsId of a contact:

/apex/esl__package?ParentId={!Account.Id}&Name={!Account.Name}%20Agreement&Signer1=00336000003gBYX&Documents=00P36000000wwrd

Example 2

When the following code snippet is run, it creates a OneSpan Sign package from an email address. In particular, this snippet creates a signer of type External Email with the email address john.doe@test.com.

/apex/esl__package?ParentId={!Account.Id}&Name={!Account.Name}%20Agreement&Signer1=john.doe@test.com&Signer1FirstName=john&Signer1LastName=doe&Documents=00P36000000wwrd

Creating a Transaction from a Convention

To create a package from a Convention with the help of customized code:

  1. Create a suitable Convention (for more, see Automation via OneSpan Sign Conventions).
  2. Create a Custom button that will run the necessary code when the button is clicked (see the example below).
  3. Click the Custom button. Doing so should create a package with the information specified in the Convention.

Example

When the following code snippet is run, it creates a OneSpan Sign package from a Convention, where:

  • The ConventionId is the DynamicsID of the Convention to be used.
  • Signer1Label is the DynamicsID of the Signer Label to be applied to Signer1.
/apex/esl__package?ParentId={!Account.Id}&Name={!Account.Name}%20Agreement&Documents=00P36000000wwrd&ConventionId=a0836000000nfRo&Signer1=00336000003gBYX&Signer1Label=a0K36000001j8VW

Creating a Transaction from a Custom Action

If you create a Custom Action, and add it to a Salesforce object, the added action enables Lightning Experience users to easily send documents to be signed via OneSpan Sign.

The URL used in the procedure for a Custom Action is the same as that for a Custom Button, except that the URL for a Custom Action must be stored in a custom field created on the object.

To create a package programmatically via a Custom Action, perform the steps below:

Step 1: Create a field that will store the automation URL.

In this step, you must create a field in the object (Account, Contact, Opportunity, etc) that will store the Automation URL. That URL follows the same rules as for the Custom Button, and it receives the same parameters.

We recommend using formula fields, so you can merge fields.

Step 2: Create a Visualforce page to trigger the automation.

In the Visualforce page, the Admin user must use a component supplied by the connector to: (1) read the Automation URL stored in the field created above; (2) trigger the automation.

To create the Visualforce page:

<apex:page standardController="Account">

<ESL:PackageAutomation fieldName="Account_Automation_URL__c" />

</apex:page>

  1. Click Setup.
  2. In the left pane, click Develop > Visualforce pages. A list of Visualforce pages appears.
  3. Click New.
  4. Type a suitable Label, Name, and Description for the new page.
  5. Select the Available for Salesforce mobile apps and Lighting Pages check box.
  6. On the Visualforce Markup tab, type the following code:

After the Admin user has created the Visualforce page, they must specify: (1) the name of the object that will use that page (e.g., Account, Contact, Opportunity, a custom object, etc.); (2) the name of the field where the URL is stored.

Step 3: Create the action in the component, and associate the Visualforce page with it.

  1. Click Setup.
  2. If you want to use a standard object, in the left pane click Customize, and select the object.
  3. If you want to use a custom object:
    1. In the left pane, click Create > Objects. A new page displays a list of custom objects.
    2. Find the relevant custom object, and click its name.
  4. In the Buttons, Links, and Actions section, click New Action. A New Action page opens.
  5. Under Action Type, select Custom Visualforce.
  6. Under Visualforce Page, select the Visualforce page you created earlier.
  7. Type a suitable Label and Name for the new Custom Action.
  8. Click Save.

Step 4: Add the action to the Page Layout.

Once the action has been created, the Admin user must add it to the Page Layout to make it accessible to other users. It must also be added to the Salesforce1 actions to make it available on mobile devices.

To add the new Custom Action to the Page Layout for your custom object:

  1. Click Setup.
  2. In the left pane, click Create > Objects. A new page displays a list of custom objects.
  3. Find your custom object, and click its name.
  4. On the Page Layouts section, click Edit. The Page Layout page appears.
  5. Click the Salesforce1 Actions option in the top left pane.
  6. If you don't see any actions in the Salesforce1 and Lightning Experience Actions section, click the wrench icon that appears when you move your mouse over that section.
  7. Drag the new Custom Action into the Salesforce1 and Lightning Experience Actions section.
  8. Click Save.

At the end of this procedure, you should see all input information reflected in the created package.

Parameters for URL Code Snippets

The following table describes parameters that can be used in URL code snippets for all of the above procedures.

A static sample has a fixed value. The value of a dynamic sample is specified by a merged field.

Parameter Name

Description

Static Sample

Dynamic Sample

TemplateId

The package's template ID. If it's not provided, create it ad hoc. Any field specified in the URL will override the value of the template. The template must be active.

TemplateId=a0Ag0000007r4nS

TemplateId={!Account.Transaction_Template__c}

Name

The package's name, URL-encoded.

Name=My %20Transaction

Name={!Contact.Name} %20Transaction

Description

The package's description, URL-encoded.

Description=The %20Transaction %20Description

Description={!Contact.FirstName} %20{!Contact.LastName}-The %20Transaction %20Description

ExpiryDate

The package's expiration date (YYYYMMDD)

ExpiryDate=20151230

ExpiryDate={!Contact.ExpiryDate__c}

EmailMessage

Content of the email message

EmailMessage=Content %20of %20the %20email %20to %20send

EmailMessage={!Account.CustomEmail__c}

Language

Language of the package (only English is currently available)

Language=en

Language={!Contant.CommunicationLanguage__c}

InPersonSigning

Flag that specifies if in-person signing is true or false

InPersonSigning=true

InPersonSigning={!Contact.InPersonSigning__c}

Documents

List of comma-separated IDs. Those IDs can be for Salesforce attachments, Salesforce documents, or Salesforce files. Create a package attachment, document, or file with its binary, and with a related name that corresponds to the item's order in the list. Note: Salesforce files became supported only in OneSpan Sign for Salesforce 4.10. Warning: The system supports a maximum of 5 MB per document (smaller documents yield better performance — we recommend under 5 MB per document). The system supports a maximum of 10 documents per package or package template. However, there is no limit to the total collective size of documents in a package.

Documents=015g0000000Cm1f, 00Pg0000001eg9H

Documents={!Account.DocumentId__c}

Send

Flag that indicates if the package must be sent after being created. Requires a default Convention or the conventionID parameter, and a Signer Label for at least one of the signers.

Send=1 or Send=true

Send={!Account.AutomaticallySend__c}

ConventionId

The Convention ID that will be used to prepare and send the package. ConventionId is mandatory if no default Convention has been set in the Custom Settings.

ConventionId=a0Rg00000033spu

ConventionId={!Account.Convention__c}

retUrl

The URL to which users will be directed once the package has been sent. It must have Send=1 or Send=true, and it must be URL-encoded.

retUrl= %2Fhome %2Fhome.jsp

retUrl= %2F{!Account.Id}

DescriptionObjectName

Specifies the description of a package, using the name of a custom object. It must be an object name like Account or Transaction__c. This parameter requires DescriptionObjectField and DescriptionObjectId.

DescriptionObjectName=Account& DescriptionObjectField=Name& DescriptionObjectId=001g000000T9wTR

DescriptionObjectName=Account& DescriptionObjectField=Name& DescriptionObjectId={!Account.Id}

DescriptionObjectField

Specifies the description of a package, using a field from a custom object. Must be a field in the object defined in DescriptionObjectName, like Name or Description__c. This parameter requires DescriptionObjectName and DescriptionObjectId.

DescriptionObjectName=Account& DescriptionObjectField=Name& DescriptionObjectId=001g000000T9wTR

DescriptionObjectName=Account& DescriptionObjectField=Name& DescriptionObjectId={!Account.Id}

DescriptionObjectId

Specifies the description of a package, using a custom object's ID. Must be the ID of an object of the type defined in DescriptionObjectName. This parameter requires DescriptionObjectName and DescriptionObjectField.

DescriptionObjectName=Account& DescriptionObjectField=Name& DescriptionObjectId=001g000000T9wTR

DescriptionObjectName=Account& DescriptionObjectField=Name& DescriptionObjectId={!Account.Id}

EmailMessageObjectName

Specifies the email message of a package, using the name of a custom object. Must be an object name like Account or Transaction__c. This parameter requires EmailMessageObjectField and EmailMessageObjectId.

EmailMessageObjectName=Account& EmailMessageObjectField=Name& EmailMessageObjectId=001g000000T9wTR

EmailMessageObjectName=Account& EmailMessageObjectField=Name& EmailMessageObjectId={!Account.Id}

EmailMessageObjectField

Specifies the email message of a package, using a field from a custom object. Must be a field in the object defined in EmailMessageObjectName, like Name or Description__c. This parameter requires EmailMessageObjectName and EmailMessageObjectId.

EmailMessageObjectName=Account& EmailMessageObjectField=Name& EmailMessageObjectId=001g000000T9wTR

EmailMessageObjectName=Account& EmailMessageObjectField=Name& EmailMessageObjectId={!Account.Id}

EmailMessageObjectId

Specifies the email message of a package, using the ID of a custom object. Must be the ID of an object of the type defined in EmailMessageObjectName. This parameter requires EmailMessageObjectName and EmailMessageObjectField.

EmailMessageObjectName=Account& EmailMessageObjectField=Name& EmailMessageObjectId=001g000000T9wTR

EmailMessageObjectName=Account& EmailMessageObjectField=Name& EmailMessageObjectId={!Account.Id}

SignerX

X is a number from 1 to infinity. The value can be a lead ID, contact ID, user ID, or an email address. If an email address is provided, the parameters SignerXFirstName and SignerXLastName are required.

Signer1=003g000000OLhpk or Signer1=sign.support@onespan.com& Signer1FirstName=John& Signer1LastName=Doe

Signer1={!Account.Main_Contact__c} or Signer1={!Contact.Email}& Signer1FirstName={!Contact.FirstName}& Signer1LastName={!Contact.LastName}

SignerXFirstName

Specifies the first name of the signer at index X. It's available only for external email signers.

Signer1=sign.support@onespan.com& Signer1FirstName=John& Signer1LastName=Doe

Signer1={!Contact.Email}& Signer1FirstName={!Contact.FirstName}& Signer1LastName={!Contact.LastName}

SignerXLastName

Specifies the last name of the signer at index X. It's available only for external email signers.

Signer1=sign.support@onespan.com& Signer1FirstName=John& Signer1LastName=Doe

Signer1={!Contact.Email}& Signer1FirstName={!Contact.FirstName}& Signer1LastName={!Contact.LastName}

SignerXPhone

Specifies the phone number of the signer at index X. It's available only for external email signers.

Signer1=sign.support@onespan.com& Signer1FirstName=John& Signer1LastName=Doe& Signer1Phone=8675309

Signer1={!Contact.Email}& Signer1FirstName={!Contact.FirstName}& Signer1LastName={!Contact.LastName}& Signer1Phone={!Contact.Mobile}

SignerXLabel

Specifies the Signer Label associated with the signer at index X. Must be the ID of the signer-label object in the related Convention (the default Convention or the one specified in ConventionId).

Signer1=003g000000OLhpk& Signer1Label=a0Tg0000001uMIf

Signer1={!Contact.Id}& Signer1Label={!Contact.SignerLabel__c}

SignerXAllowDelegation

Flag that determines if you will allow the original Signer you identified to delegate someone else to sign the e-SignTransaction™ on their behalf. Valid values are: 1 or 0, true or false.

If the value is 1 or true, the Signer will be asked to enter the email address and full name of the delegate, plus an optional email message to be sent to the delegate. You will be notified of this change of Signer, and will be CC’d on the email message (if sent).

Signer1=003g000000OLhpk&Signer1AllowDelegation=true Signer1={!Contact.Id}&Signer1AllowDelegation=1
SignerXAuthMethod

Flag that allows you to create a transaction automatically, using one of the following authentication methods:

  • Question and answer
  • SMS
  • Email

If question and answer is selected as the authentication method, then the following additional parameters must be configured:

  • signerXQandAYQuestion – the authentication question

  • signerXQandAYTextAnswer – the correct answer to the authentication question.

  • signerXQandAYSFFieldAnswer –an alternative method of defining the answer. In this case, the answer comes from a specified field within the chosen type. For example, if using Contact as your Type, you could select any field within the Contact type, such as phone number. The Signer would then enter their phone number , which is cross-referenced with the phone number field in their Contact type.
    Note that you cannot use this parameter if SignerX is of External Email type. Note also that you need to provide either signerXQandAYSFFieldAnswer or signerXQandAYTextAnswer, but you cannot provide both.

  • signerXQandAYMaskAnswer – determines whether or not the answer typed by the user should be masked while typing. Possible values are true and false. This parameter is optional and defaults to false.

  • Note that X is the number of signers and Y is the number of questions (up to 2 questions are supported).

Signer1=003g000000OLhpk&Signer1AuthMethod=sms

Signer1=003g000000OLhpk&Signer1AuthMethod=qaSigner

1=003g000000OLhpk&Signer1AuthMethod=email

Signer1={!Contact.Id}&Signer1AuthMethod={!Contact.AuthenticationMethod__c}
AutoPrepare Flag that determines if the AutoPrepare feature will be activated for a package if a Convention is specified. Valid values are: 1 or 0, true or false. AutoPrepare=true AutoPrepare={!Account.AutoPrepareTransaction__c} Insert={!Account.InsertValueInTransaction__c}
Insert

Flag that determines if data from Salesforce will be auto-populated into a OneSpan Sign document when the document's package is being prepared. Valid values are: 1 or 0, true or false.

Insert=true Insert={!Account.InsertValueInTransaction__c}
WriteBack Flag that determines if a Salesforce field will be updated with data from a OneSpan Sign document when that document's package is completed. Valid values are: 1 or 0, true or false. WriteBack=true WriteBack={!Account.WriteValueInTransaction__c}
EnforceSigningOrder

Flag that determines if the enforce signing order condition is true or false.

EnforceSigningOrder=true

EnforceSigningOrder={!Account.EnforceSigningOrder__c}

ParentId

ID of the parent object. To be stored in the ParentId text field. It automatically populates the parent type and the related lookup field if possible.

ParentId=001g000000T9wTR

ParentId={!Account.Id}

enableReminders

Flag (true / false) that determines if the automatic-reminder feature is set for the package

enableReminders=true

enableReminders={!Account.RemindersEnabled__c}

sendReminderDays

Number of days before the first reminder is sent

sendReminderDays=2

sendReminderDays={!Account.SendReminderDays__c}

repeatReminderDays

Interval in days between successive reminders

repeatReminderDays=1

repeatReminderDays={!Account.RepeatReminders__c}

totalReminders

Maximum number of reminders to be sent

totalReminders=10

totalReminders={!Account.TotalReminders__c}

ChatterEnable

Flag (true / false) that determines if Chatter will be active on the package

ChatterEnable=true

ChatterEnable={!Account. ChatterEnable __c}