Creating 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 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 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.