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:

• Creating a Transaction from a Custom Button
• Creating a Transaction from a Custom Action

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

• Parameters for URL Code Snippets

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 transaction'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 create a transaction from a Custom Button in the following ways:

• Creating a Transaction from a Template
• Creating a Transaction from a Salesforce ID or an Email Address
• Creating a Transaction from a Convention

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

When creating a transaction from a Salesforce ID you must specify the following parameters:

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

OneSpan Sign supports the following document types:

• Adobe's Portable Document Format (*.pdf) — PDFs on which OneSpan Sign can act generally have at least these permissions enabled: (1) Changing the Document; (2) Signing; (3) Filling of form fields.
• Microsoft Word (*.doc or *.docx)
• Open Office (*.odt)
• Text (*.txt)
• Rich Text Format (*.rtf)

In addition, the OneSpan Sign Print Driver supports any document that can be printed from a Windows-based application (e.g., Microsoft Word, Microsoft Excel, Microsoft PowerPoint).

File Size Constraints

• The maximum size of a single document is 16 MB. Smaller documents yield better performance — we recommend under 5 MB per document.
• If your organization uses Salesforce or Microsoft SharePoint connectors, the file size maximum is 5 MB per document.
• If your organization uses Salesforce connectors, the maximum number of documents that can be added to a transaction is ten (10).
• If you enable email delivery while configuring a recipient, attachments larger than 5 MB are not supported.

File Name Constraints

• Document file names should not contain any of the following comma-separated characters: *, /, \, :, <, >, |, ?, ".
• A document's name cannot contain the string esigned.

General File Constraints

• We recommend that you do not use PDF documents that make use of XML Forms Architecture. For more information, see XFA Support.
• Do not upload password-protected or corrupted documents. These will generate an error.
• OneSpan strongly recommends that you scan a PDF for syntax errors (e.g., by using Adobe's Preflight tool), and resolve any errors before you add the document to a transaction.
• PDFs with the NeedAppearances flag set to true are not currently supported.

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 the ID 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 recipient of type External Email with the email address [email protected].

/apex/esl__package?ParentId={!Account.Id}&Name={!Account.Name}%20Agreement&[email protected]&Signer1FirstName=john&Signer1LastName=doe&Documents=00P36000000wwrd

Creating a Transaction from a Convention

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

1. Create a suitable Convention. For more information, 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 transaction with the information specified in the Convention.

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

• The ConventionId is the ID of the Convention to be used.
• Signer1Label is the ID of the Recipient 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 transaction via a Custom Action, perform the steps below:

• Step 1: Create a field that will store the automation URL.
• Step 2: Create a Visualforce page to trigger the automation.
• Step 3: Create the action in the component, and associate the Visualforce page with it.
• Step 4: Add the action to the Page Layout.

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 use "merge fields".

<apex:page standardController="Account">

<ESL:PackageAutomation fieldName="Account_Automation_URL__c" />

</apex:page>

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:

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 Mobile and Lightning option in the top left pane.
6. If you don't see any actions in the Mobile 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 Mobile and Lightning Experience Actions section.
8. Click Save.

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

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 transaction'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 transaction's name, URL-encoded.	Name=My %20Transaction	Name={!Contact.Name} %20Transaction
Description	The transaction's description, URL-encoded.	Description=The %20Transaction %20Description	Description={!Contact.FirstName} %20{!Contact.LastName}-The %20Transaction %20Description
ExpiryDate	The transaction's expiration date (YYYYMMDD)	ExpiryDate=20151230	ExpiryDate={!Contact.ExpiryDate__c}
EmailMessage	The values enter into EmailMessage will be passed to the “$PACKAGE_MESSAGE;” placeholder existing default templates, such as the “email.activate” template and the “email.notify” template. For more information see OneSpan Sign Developers: Email Templates.	EmailMessage=Content %20of %20the %20email %20to %20send	EmailMessage={!Account.CustomEmail__c}
Language	The language of the transaction package. The options available are based on the language selections made on the Customization page.	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 transaction 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 Embedded Integration for Salesforce 4.10. 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 transaction or transaction template. However, there is no limit to the total collective size of documents in a transaction.	Documents=015g0000000Cm1f, 00Pg0000001eg9H	Documents={!Account.DocumentId__c}
Send	Flag that indicates if the transaction must be sent after being created. Requires a default Convention or the conventionID parameter, and a Recipient Label for at least one of the recipients.	Send=1 or Send=true	Send={!Account.AutomaticallySend__c}
ConventionId	The Convention ID that will be used to prepare and send the transaction. 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 transaction 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 transaction, 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 transaction, 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 transaction, 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 transaction, 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 transaction, 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 transaction, 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 [email protected]& 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 recipient at index X. It's available only for external email recipients.	[email protected]& Signer1FirstName=John& Signer1LastName=Doe	Signer1={!Contact.Email}& Signer1FirstName={!Contact.FirstName}& Signer1LastName={!Contact.LastName}
SignerXLastName	Specifies the last name of the recipient at index X. It's available only for external email recipients.	[email protected]& Signer1FirstName=John& Signer1LastName=Doe	Signer1={!Contact.Email}& Signer1FirstName={!Contact.FirstName}& Signer1LastName={!Contact.LastName}
SignerXPhone	Specifies the phone number of the recipient at index X. It's available only for external email recipients.	[email protected]& Signer1FirstName=John& Signer1LastName=Doe& Signer1Phone=8675309	Signer1={!Contact.Email}& Signer1FirstName={!Contact.FirstName}& Signer1LastName={!Contact.LastName}& Signer1Phone={!Contact.Mobile}
SignerXLabel	Specifies the Recipient Label associated with the recipient at index X. Must be the ID of the recipient-label object in the related Convention (the default Convention or the one specified in ConventionId).	Signer1=003g000000OLhpk& Signer1Label=a0Tg0000001uMIf	Signer1={!Contact.Id}& Signer1Label={!Contact.RecipientLabel__c}
SignerXAllowDelegation	Flag that determines if you will allow the original Recipient you identified to delegate someone else to sign the transaction on their behalf. Valid values are: 1 or 0, true or false. If the value is 1 or true, the Recipient 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 Recipient, 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 Recipient 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 recipients and Y is the number of questions (up to 2 questions are supported).	Signer1=003g000000OLhpk&Signer1AuthMethod=sms Signer1=003g000000OLhpk&Signer1AuthMethod=qaRecipient 1=003g000000OLhpk&Signer1AuthMethod=email	Signer1={!Contact.Id}&Signer1AuthMethod={!Contact.AuthenticationMethod__c}
AutoPrepare	Flag that determines if the AutoPrepare feature will be activated for a transaction 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 transaction 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 transaction 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 transaction.	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 transaction.	ChatterEnable=true	ChatterEnable={!Account. ChatterEnable __c}