Create a Transaction Programmatically

OneSpan Sign for Salesforce enables you to create Conga Sign Powered by OneSpan Sign transactions programmatically. There are two main ways of doing so: From a Custom Button or a Custom Action.

Creating a Transaction from a Custom Button

This topic explains how to create a transaction in Salesforce by adding a custom button to an object, enabling users to send documents for signing directly from the object's records.

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 from a Template

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

First specify the following template parameters:

ParentId
Name
TemplateId

Example

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

Creating a Transaction from a Salesforce ID or Email Address

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

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

Note:

OneSpan Sign supports the following document types:

Adobe's Portable Document Format (*.pdf)
Microsoft Word (*.doc or *.docx)
Open Office (*.odt)
Text (*.txt)
Rich Text Format (*.rtf)

Warning:

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

Create a suitable Convention. For more information, see Automation via OneSpan Sign Conventions.
Create a Custom button that will run the necessary code when the button is clicked (see the example below).
Clicking the Custom button creates 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

Warning:

Due to the complicated nature of supporting programmers and programming languages, the integration of Conga with Visualforce, Apex, Javascript (or other programming languages), and custom code is not supported.

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

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.

Create the Visualforce page

Click Setup.
Click Develop > Visualforce pages.
Click New.
Type a suitable Label, Name, and Description for the new page.
Select the Available for Salesforce mobile apps and Lighting Pages check box.
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.

Click Setup.
If you want to use a standard object, in the left pane click Customize, and select the object.
If you want to use a custom object:
1. In the left pane, click Create > Objects.
2. Find the relevant custom object and select it.
In the Buttons, Links, and Actions section, click New Action.
Under Action Type, select Custom Visualforce.
Under Visualforce Page, select the Visualforce page you created earlier.
Fill out the Label and Name for the new Custom Action.
Click Save.

Step 4: Add the Custom Action to the Page Layout.

Once the action has been created, your System Administrator 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:

Click Setup.
In the left pane, click Create > Objects.
Select your custom object.
On the Page Layouts section, click Edit.
Click the Mobile and Lightning option in the top left pane.
If you don't see any actions in the Mobile and Lightning Experience Actions section, click the wrench icon.
Drag your Custom Action into the Mobile and Lightning Experience Actions section.
Click Save.

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.

Note:

A static sample has a fixed value. The value of a dynamic sample is specified by a merge 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	Content of the email message	`EmailMessage=Content %20of %20the %20email %20to %20send`	`EmailMessage={!Account.CustomEmail__c}`
Language	The language of the transaction package.	`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 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 Signer1=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 recipient at index X. It's available only for external email recipients.	`Signer1=support@ onespan.com& 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.	`Signer1=support@ onespan.com& 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.	`Signer1=support@ onespan.com& 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}`

Conga Product Documentation

Welcome to the new doc site. Some of your old bookmarks will no longer work. Please use the search bar to find your desired topic.