Click the Table icon to add a table. This is a common tool for dealing with column data in your forms. If you drag the size of the table or its columns, the sizes will be fixed as you specify it in the editor. But you can also set their sizes to percentage widths and the layout will expand and contract with the browser size.

Click the Insert Horizontal Line button to add a line across the page.

Click the Insert Page Break button to force a page break when the user prints the document from their browser.

Click the Insert Special Character button to add one of the listed characters.

Click the Image button to insert an image defined in the document, the document's library or from the ESF/Library/Template.

Click the Link button to make a hyperlink.

Click the Source button, for advanced users, who want to see the HTML generated. You may enter HTML directly in this mode and then click it again to return to the WYSIWYG mode. In Source mode, you can also add javascript or style sections as necessary.

Click the Show Blocks button to display the page in terms of blocks, indicating the type of tags used to create them.

Table of contents

Fields in document

On the right side is the Fields in document list:

This shows all fields defined in the document using the ${ } notation. It shows the number of references as well as the field's type.

Click on a field to change its configuration:

By default, new fields are given the General type, meaning they are standard text input fields:

• EsfName specifies the field's name, which must be unique in the document.
• Use the Set from library drop down to select any pre-defined fields from the library. Note that using this will update all fields on the form.
• Use the Type drop down to choose the correct type for this field:
• General is a text input field for entering a single value, like a name.
• Checkbox is a traditional checkbox field, either checked or not.
• Credit card # is a text input field that expects a legal credit card number. This type currently supports Visa, MasterCard, American Express, Discover numbers.
• Date is a text input field that includes a calendar selector or lets the user enter the date directly.
• Decimal is a text input field that expects a valid decimal number, like 123.4. It differs from the Money type only in that it doesn't show a currency symbol.
• Drop down list lets you choose a drop down list defined in your library so that parties can select a valid value from the list.
• Email address is a text input field that expects a valid email address.
• File upload is a special field that allows files to be attached (or removed) when in edit mode, or listed and viewed when in display mode.
• HTML editor puts a CKEditor field in your document, allowing the party to enter rich text, or paste from Word, etc. We recommend you only provide this feature to parties who are part of your company.
• Integer is a text field that expects an integer/counting number value, such as -5 or 20. Decimal points are not allowed. This type also supposed an Extra options value to specify whether to show normal integers like 1, 2, 3, or to show the value as an ordinal number, like 1st, 2nd, 3rd.
• Money is a text input field that expects a valid amount of money to be entered, like 15.25 or $20. It differs from the Decimal type in that it displays a currency symbol rather than just the number.
• Phone (US/Canada) is a text input field that expects a valid 10-digit phone number.
• Radio button is a traditional radio button that is typically defined with other values and are put in a group so that only one of the radio buttons in the group can be selected at a time.
• Radio button group is a non-visual field type that actually holds the value of the selected radio button defined as part of the group.
• Signature is a text field stylized for the purpose of having the party type their name to indicate they are signing. It will also trigger the additional of the electronic signature process record for the party who signs.
• SignatureDate is a non-entry field associated with a Signature field by having the same name as the Signature field, but with "Date" added. So if you define a signature field as "CustomerSignature" you can have a date field added and automatically assigned with the actual signing date by defining a SignatureDate field named "CustomerSignatureDate" ("CustomerSignature" with "Date" added at the end).
• SSN is a text field suitable for the entry of US-based social security numbers.
• Text area is a multi-line text field that allows for greater input by a user. It is generally used to enter plain text comments, additional contract terms, descriptions, free form mailing addresses, etc.
• Zip code is a text field suitable for the entry of US-based zip codes, either 5 or 9 digits.
• Use the Align drop down to change the alignment of the field. "Inherit" is commoly used.
• Check the Required checkbox if the field is required.
• Click the Security options list to add special options such as whether the field should support "Auto complete" or not (meaning that if the user has entered similar data elsewhere, the browser will offer up alternative choices, and if not checked, the browser will not offer suggestions); "Mask in data snapshot" is for sensitive data that you may store in your forms, but if the data is exported it must be masked; and "Copy value on tran clone" specifying whether this field's value can be copied if a new transaction is created from an existing transaction (for example, signature fields generally should not be copied since the new transaction should not assume they have typed to sign).
• Enter the Minimum length this field may have in number of characters.
• Enter the Maximum length this may have in number of characters.
• Enter the Width and Units to specify how big the field should be. If your fields are defined in a table column, you may want to choose 100% to have it fill the available space. Or choose "Auto" in the Units (Width value is ignored) to have the field sized according to its natural size, which is useful for fields like checkboxes, drop downs, radio buttons, etc.
• Check the Resize display field if you want the field to display in its natural size when in view/display mode (not in input/edit mode).
• Check Top, Bottom, Left and/or Right to include borders around the field.
• The Initial value specifies a fixed value or a field specification, like ${transaction:firstName}, which is used to set the field's initial value when the transaction is started. You generally cannot reference other fields in the document (since the order they are initialized is not defined), but you can set it to values posted when the transaction was started by an external process. If the initial value field specification cannot be found and the Display if empty value option is enabled, then the field will be left blank rather than set to the missing field name.
• The Display if empty value specifies a fixed value or a field specification, which is displayed for this field when the value is blank (null, spaces, empty string, etc.) To activate this, you need to check the box to its left.
• The User tooltip allows you to enter a tooltip that will display when the party hovers the mouse over the field on the document.
• The Input format specifies the expected format for input into the field.
• The Display format specifies the format to use when displaying the field (not in input/edit mode).

Each field can also be displayed with its label, automatically. By defining the label that goes with the field, when there is a data validation error, the field and label can be highlighted to help the party know what is wrong. We recommend laying out your forms with the label in the "Above left" position to create a professional, consistent look that is clear to your users (although for checkbox and radio buttons, we recommend "Right").

• Select the Label position to use when allowing the label to be automatically shown with the field. Select "None" to prevent the label from automatically appearing with the field. We recommend you do put the label somewhere nearby, though, using the syntax ${label:fieldName}.
• Check Show input only if the label should only be shown when the field is open for input (edit mode). This is mostly useful for a field inside a paragraph of text where the label is useful as a field prompt, but once populated the label no longer is necessary.
• For Label to show enter the value to show as the field's label.
• Choose the Separator drop down to define the separation of the label and the field as "None" (no separator), "Colon :" (put a colon and space between), or "Space" (put a space between).
• Choose the Size of the label as "Small" (use a smaller font, which is typical when using a label position of "Above Left") or "Normal" (use the same font size for the label).

Click the Ok button to save your changes to the field template.

Click the Cancel button to discard the changes made to the field template.

Click the Create new like button to create a new field like this one. Note that you will want to update your document to reference the new field using ${ } notation.

Click the Delete button to delete the field. Note that you must also remove the associated ${ } specification in the document because when you save the document page, all undefined fields will be re-created as a General type field.

Table of contents

Parties to document

On the right side is the Parties to document list:

This shows all parties defined in the document. You only need to define parties who are expected to fill out portions of the document. You do not need to specify any parties who will only view the document. You can drag to reorder the parties listed so that they appear in the expected order that the document will be completed.

Click on a party to change its configuration:

• EsfName is the unique name of a party to this document who is expected to enter data or sign.
• Choose from the Set name from library drop down to select a pre-defined party in your library. This only changes the EsfName and Display name fields, but keeps them consistent across your documents. Consistent names will make it easier to configure packages when you add multiple documents in.
• The Display name is the name of this party when displayed on a document or otherwise describing the party's step or role.
• Select fields from Fields party can view and click the >> button to convert them into Fields party can update. The fields listed on the right side are the fields the party will be allowed to type into. Use the << button to remove the selected fields from the update column if the party should not be allowed to update them.
• Select fields from Required fields party can update and click the >> button to make those fields defined with the Required checkbox optional for this party. Often a required field may not be known by an early party (like the person who starts the transaction and then sends it along for processing by another party), so while the field truly is required, it may be considered optional for another party. Use the << button to remove the optional nature of that field for the party so it's required as defined in the field template.

Click the Ok button to save your changes to the party.

Click the Cancel button to discard the changes made to the party.

Click the Create new like button to create a new party like this one.

Click the Delete button to delete the party.

Table of contents

Files linked in document

On the right side is the Files linked in document list:

This shows all files defined in the document. For files like HR policies that will likely appear in more than one document, we recommend you define those in the library. But many files are tied specifically to a single document, and this is the place to add those files.

Click on a file to change its configuration:

• EsfName is the unique name of an file in this document.
• Display name is the auto-generated text shown in the link to this file.
• Description is a short description of the file.
• Comments is any other information you want to maintain about the file.

If the file has already been specified, click the Replace file... button to select a different file to use. When you first create a new file, use the Set file button to select the file to upload.

Click on the File link (view/download) link to download the file.

Click the Ok button to save your changes to the file.

Click the Cancel button to discard the changes made to the file.

Click the Delete button to delete the file.

Table of contents

Images in document

On the right side is the Images in document list:

This shows all images defined in the document. For images like logos that will likely appear in more than one document, we recommend you define those in the library. But some images are tied specifically to a single document, and this is the place to add those images.

Click on an image to change its configuration:

• EsfName is the unique name of an image in this document.
• Description is a short description of the image.
• Comments is any other information you want to maintain about the image.

If the image has already been specified, click the Replace image file button to select a different image to use. When you first create a new image, use the Set image file button to select the image to upload.

Click on the View full image link to display the image "as is".

Note that the thumbnail image may appear to have a black background when the original images uses a transparent background.

Click the Ok button to save your changes to the image.

Click the Cancel button to discard the changes made to the image.

Click the Delete button to delete the image.

Table of contents

Add new field or party or file or image to the document

On the right side, click the Add new button and then choose the type of new object to create:

Click on whichever type of object to create.

Table of contents

Document page editor cheatsheet

We recommend that when you want to build a new document, start from the top, lay out the first line, test, then lay out the second line, test, etc. This will make it easier to spot layout errors before too much is built.

Next, add in your fields using the generic ${fieldName} syntax inside the document. For each such ${ } specified, a general purpose field will automatically be created for you. Just lay out all of the fields and do not worry about which party will manipulate which field.

Once your testing shows the document layout working as expected, with general fields, you can then use the 'Fields in document' tab to update their types as necessary. At this stage, you can also define the parties who will fill out the document and assign the fields to the respective parties.

Coding conventions

${fieldName} specifies a document field called 'fieldName'. Examples include ${firstName}, ${streetAddres}, ${SSN} etc. We recommend that each document have a field for each variable element so it will work more easily when packaged with other documents. However, a document may reference a field (display-only value) from another document using the notation: ${documentName.fieldName}. ${fieldName} is equivalent to ${fieldlabel:fieldName}, with the former preferred as it's easier to type.

The names are used as programming variables and thus have are limited to 50 characters in length, must begin with a letter, and then can contain numbers, uppercase or lowercase letters and the underscore (_). So firstName and First_Name are valid, while First name and 1stName and first-name are not.

If a given field appears in multiple locations in a document, only one should be used for input with the standard field notation. The other references to the field, where it's only displayed, should use:

• ${out:fieldName} will show the field 'fieldName' for display-only.

While fields are often shown together with a label, you can specify these be shown individually using the notation:

• ${label:fieldName} will show the label configured for the field 'fieldName'.
• ${field:fieldName} will show just the field 'fieldName' without any configured label.

If you select a file using the Editor's link feature, the file link will appear in the document while editing. However, you may also use this notation to specify a configured file:

• ${file:FileName} will insert a link to the file named 'FileName' in that location.

If you select an image using the Editor's image feature, the image will appear in the document while editing. However, you may also use this notation to specify a configured image:

• ${image:ImageName} will insert the image named 'ImageName' in that location.

To insert the value of a configured property, you may use this notation:

• ${property:PropertySetName.PropertyName} will insert the value of 'PropertyName' as configured in the property set named 'PropertySetName'.
• ${htmlproperty:PropertySetName.PropertyName} will insert the value of 'PropertyName' as configured in the property set named 'PropertySetName' as if the value were valid HTML (no escaping special characters to HTML entities).

Built-in fields used in documents

• ${document:esfname} is replaced by the document's configured name.
• ${document:displayname} is replaced by the document's display name.
• ${document:id} is replaced by the document's unique id.
• ${document:version} is replaced by the document's version number.
• ${document:version.id} is replaced by the document version's unique id.
• ${document:page.esfname} is replaced by the document version page's name.
• ${document:page.id} is replaced by the document version page's unique id.
• ${document:page.number} is replaced by the document versions page's number.
• ${document:party.esfname} is replaced by the party's name.
• ${document:party.displayname} is replaced by the party's display name.
• ${document:package.pathname} is replaced by the package's path name.
• ${document:package.version} is replaced by the package's version number.
• ${document:package.id} is replaced by the package's unique id.
• ${document:package.version.id} is replaced by the package version's unique id.

Built-in fields to reference from the transaction and startup data

• ${transaction:id} is replaced by the transaction's unique id.
• ${transaction:ESF_Start_Timestamp} is replaced by the date-time it was created.
• ${transaction:ESF_Started_API_Mode} is true if the transaction was started using the API mode (from an automated start rather than a user). It is false otherwise.
• ${transaction:ESF_Started_By_User_Id} is replaced by the user id of the person who started this transaction if it was started by a logged in user.
• ${transaction:ESF_Started_By_User_Email} is replaced by the email address of the person who started this transaction if it was started by a logged in user.
• ${transaction:ESF_Started_By_User_Email_Address} is replaced by the full email display name and email address of the person who started this transaction if it was started by a logged in user.
• ${transaction:ESF_Started_By_User_Personal_Name} is replaced by the first/personal name of the person who started this transaction if it was started by a logged in user.
• ${transaction:ESF_Started_By_User_Family_Name} is replaced by the last/family name of the person who started this transaction if it was started by a logged in user.
• ${transaction:paramName} is replaced by the value of the named parameter passed at startup (X prefix is needed if original param started with a number; '-', '/' or '.' replaced by '_').
• ${transaction:ESF_Request_Header_headerName} is replaced by the value of the named header passed at startup ('-', '/' or '.' replaced by '_').
• ${transaction:ESF_Request_Method} is replaced by 'GET' or 'POST' based on type of original startup HTTP request.
• ${transaction:ESF_Request_ContentType} is replaced by HTTP request's mime-type/content-type when specified.
• ${transaction:ESF_Request_RequestURL} is replaced by HTTP request's original URL.
• ${transaction:ESF_Request_QueryString} is replaced by HTTP request's query string portion of the URL.
• ${transaction:ESF_Request_RemoteAddr} is replaced by HTTP request's remote address (typically an IP address).

Built-in fields used in Package documents

• ${transaction:documents.todo} specifies where the generated list of documents the specified party has access to are listed.

Built-in fields used in Email notifications configuration

• ${LINK} specifies where the generated HTTP Link or URL will be placed in the email notification.
• ${EMAIL} specifies where the party's address will be placed in the email notification, TO/CC/BCC, and/or subject.

Built-in fields used in password-related e-mail configuration for users

• ${LINK} specifies where the generated HTTP Link or URL will be placed in the email notification.
• ${NAME} specifies where the user's display name will be placed in the email notification and/or subject.
• ${EMAIL} specifies where the user's address will be placed in the email notification, TO/CC/BCC, and/or subject.

Links to advanced configuration options

There are a few data types that allow for customization using Java's built in capabilities, but they are a bit technical. For advanced folks who need them, here are some useful links to documentation that describe these more.

For Date, use SimpleDateFormat specifications

For Decimal and Money and even Integer, use DecimalFormat specifications

For General, use regular expression Pattern specifications

Table of contents

Package+disclosure documents

There is a special type of document that plays the role of a welcome message, the E-Sign Disclosure (required by law for consumers) and often contains the list of documents contained in the package for a given party.

Since the list of documents for a given party are variable, you can include ${transaction:documents.todo} in the package+disclosure document and it will automatically show the correct list of documents and their status for the party.

The ESF/Library/Template contains a document just for this purpose called StandardPackageDisclosures.

It's contents is some like the following:

${image:Logo}

Welcome to our electronic signature service.

Please note that your continued use of this service constitutes your agreement to use electronic signatures in lieu of a paper document with a traditional hand-written signature. Electronic signatures are legally recognized throughout the United States. Your electronic signature will take place when you type your name and/or initials into the marked areas on the subsequent document(s) and then you click both the Review and Submit buttons on each document to indicate your agreement and/or authorization.

You also certify that these documents are intended for you and that you are authorized to sign the documents. If you have received these by mistake, please do not continue and email us or call ${property:MyCompany.CustomerSupportPhone} to report our error.

If you do not wish to sign these documents electronically, please contact us and do not continue with this process. However, we expect that you will prefer this free, easy-to-use, fast and environmentally sound option.

Document(s) for your review:
${transaction:documents.todo}

You are free to create your own documents with alternative welcome messages, E-Sign Disclosures and/or layout for this purpose. Just specify your package+disclosure document in the Package configuration.

Table of contents

Document styles

Document styles provides basic control of the look of your documents. They specify CSS (Cascading Style Sheets) rules. By using a common set of styles, documents will have a consistent look. Open eSignForms comes with a built-in default style in the ESF/Library/Template library called ESF_DefaultDocumentStyle. It is a clean, modern look.

The values associated with the styles can be seen in the ESF/Library/Template's drop downs.

To use the style, you must set it as the document version's style. You can also set your document style as your library's default value to use when creating new documents.

Click on Document styles to show all document styles in the selected library.

• Choose Enabled to allow the document style to be used. If a document style is no longer needed, click Disable.
• EsfName is the unique name for this document style.
• Description is a short description of the document style.
• Comments is any other information you want to maintain about the styles.

The style is composed of various aspects that are used to override the hard-coded default CSS that ensure basic document functionality. It can be viewed from the document page editor's View default CSS link. Values that are specified as "(Default)" will use the values defined in default CSS. Values that are specified as "Inherit" use the setting of its parent element.

• General document contents sets the font styles for the regular text you put on the page.
• Signatures sets the font styles to use for signatures and signature dates, to give a styled look that makes the typed name electronic signature stand out from the general document contents.
• Field data on review sets font styles to be applied to all fields when in review mode (display mode, compared to edit mode when the field can be entered). This can be useful if you would like all "variable data" in your documents to stand out from the boilerplate text.
• Required data in input fields specifies the styles for input fields that are required.
• Optional data in input fields specifies the styles for input fields that are not required.
• Invalid data in input fields specifies the style for input fields when they contain invalid data and an error has been reported. It helps identify fields that need to be corrected.
• Normal label specifies the style of normal-sized field label.
• Normal error label specifies the style of the normal-sized field label when that field has been flagged as invalid.
• Small label specifies the style of small-sized field label.
• Small error label specifies the style of the small-sized field label when that field has been flagged as invalid.

Note: You can always specify the fonts for your text directly in the document page editor. But to control labels, error looks, signatures, etc. you need to use the document style.

Default CSS print style note: The default CSS file includes a brief print style: div.newPage will insert an actual page break; fonts are set to 90% of their screen size; and link tags (A HREF) with the "showURL" class will display the value of the link's URL since a printed link would otherwise lose that information.

Table of contents

Drop downs

Click on Drop downs to show all drop downs (selection boxes) in the selected library.

• Choose Enabled to allow the drop down to be used. If a drop down is no longer needed, click Disable.
• EsfName is the unique name for this drop down.
• Description is a short description of the drop down.
• Comments is any other information you want to maintain about the drop down.

• Check Allow Multi-Selections if the drop down should allow the user to select more than one value from the list.
• The Label is the text the user will select from when viewing the drop down list. The Value is the data value that will be stored in the drop down field. The label and value can be set to same.
• If "no selected value" is allowed, consider creating the first Label as "--SELECT--" with an empty Value.

Click the Add option once for each label+value you want to appear in your drop down. It will create a new entry that you can then update.

Select an option by clicking a row so it is highlighted (such as clicking in the Order field or the narrow space between the label and value) and then click the Remove selected option to remove that option.

Drag a row to another location to rearrange the order that the drop down displays its options.

Table of contents

Email templates

Email templates are used to define any email that needs to be sent from the system. Like a document, they can have variable data substituted to customize them for individual parties.

Click on Emails to show all email templates in the selected library.

• Choose Enabled to allow the email template to be used. If an email template is no longer needed, click Disable.
• EsfName is the unique name for this email template.
• Description is a short description.
• Comments is any other information you want to maintain.

• Send email FROM: specifies the FROM email address that will be used. Often, this is a NO-REPLY@example.com address to indicate that the email is an automated email and not a personal email. However, you can use any email address. The default is a property set value ${property:ESF.SendEmailFrom}. You can use any field from the documents that are used when the email is sent, or you can use the user who started the transaction with a value like ${transaction:ESF_Started_By_User_Email_Address}.
• Send email TO: specifies who the email will be sent to. For most party-based emails, we recommend using the value ${EMAIL} since that variable can be set (overridden) in various configuration options. For example, in a Package Party configuration, you can set the option labeled Notify email address spec (${EMAIL}) to replace ${EMAIL} everywhere it's used in this email template (including the email body text). The same is true for the package's custom logic action for sending an email option Email address spec (${EMAIL}). Multiple emails can be specified (use a semicolon to separate them).
• CC: specifies any CC recipients.
• BCC: specifies any BCC recipients (blind-copy so will not appear to other recipients).
• Subject is the subject of the email.
• Text version is the email text to show for clients who cannot or will not allow HTML-based emails. A text version is required as it's guaranteed to be used by all email clients. You may specify the field ${LINK} anywhere the party's pickup link should appear. Each party has a unique ${LINK} value to ensure the system knows who is retrieving the package of documents. In the package's custom logic action for sending an email option For party (${LINK}) allows you to control which value to use. Emails sent to a given party will use that party's unique link value.
• HTML version is the HTML version of the email for clients that support HTML. Generally, it should be similar to the text version, but you can use various stylings to make the email more attractive. You may put ${LINK} anywhere you need the party's unique pickup link to appear. If the actual URL of the link is not shown in your HTML version, we recommend showing the full link at the bottom, in a smaller font, with something like this:

If the above link is not active (e.g. nothing happens when you click on it), please copy the link below exactly as shown into your web browser's address or location field:

${LINK}

Table of contents

Files

Files are used to upload and save files (generally not images, though) linked to by your various documents. When a file is only needed for a particular document, you should consider defining the Files linked in a document version. But by defining the files in the library, they are available for other documents, and of course you can easily override them using a Branding Library should the file change depending on who is using the document.

Click on Files to show all files in the selected library.

• Choose Enabled to allow the file to be used. If a file is no longer needed, click Disable.
• EsfName is the unique name for this file.
• Display name is the name shown in the link to this file.
• Description is a short description.
• Comments is any other information you want to maintain.

If it's a new file, click the Set the file... button. You can then choose a file (GIF, JPEG or PNG should generally be uploaded as an image, not a file). A link to download the file will be created.

Click the Save button to save the file.

If you are replacing an existing file:

Click the Replace file... button to select a new file to replace the one shown.

Click the Save button to save the new file.

Tip: In a document, while you can reference a file using the ${file:FileName} syntax, you will probably find it easier to use the editor's link button to insert a link to the file so it's visible in the editor.

Table of contents

Images and Logos

Images/Logos are used to upload and save images and logos used across your various documents. When an image or logo is only needed for a particular document, you should consider defining the image inside the document version. But by defining the images in the library, they are available for other documents, and of course you can easily override them using a Branding Library should the image change depending on who is using the document.

Click on Images/Logos to show all images in the selected library.

• Choose Enabled to allow the image to be used. If an image is no longer needed, click Disable.
• EsfName is the unique name for this image.
• Description is a short description.
• Comments is any other information you want to maintain.

If it's a new image, click the Set the image file button. You can then choose an image file (GIF, JPEG or PNG should be used for online documents). A thumbnail image will be generated, along with a link to view the full-sized image. Note that images that have transparent backgrounds will show a black background in the thumbnail, but the original image will remain transparent.

Click the Save button to save the image.

If you are replacing an existing image:

Click the Replace image file button to select a new image file to replace the one shown.

Click the Save button to save the new image.

Tip: In a document, while you can reference an image using the ${image:imageName} syntax, you will probably find it easier to use the editor's image button to insert the image so it's visible in the editor.

Table of contents

Property sets

Property sets are a bundle of related name-value pairs. This allows you to create more flexible and re-usable documents because certain key information, like company name, address, phone, contact email, etc. can be externalized with the values stored in property sets. Changes can then be made simply by updating the property set, and all documents that reference that property set will automatically begin using the new values without having to update each document.

Properties are referenced first by which property set is being used, and then which property in that set is being referenced: PropertySetName.PropertyName.

Also, if you support multiple brands, you can create the property set (with the same name) in a branding library so that multiple companies can use the same document, yet each gets their company name, address, phone, etc. in their documents.

Click on Property sets to show all property sets in the selected library.

• Choose Enabled to allow the property set to be used. If a property set is no longer needed, click Disable.
• EsfName is the unique name for this property set.
• Description is a short description.
• Comments is any other information you want to maintain.

In the table of name-value pairs on the right side, the fields are:

• The EsfName is the name of the property (must be unique within this property set).
• The Value is the value to show when this property is referenced. It can be more than one line.
• The Comment is any information you'd like to maintain about the property.

Click the Add property button one or more times to add one more new properties. Just replace the name and value as needed.

To remove properties, click on one or more rows so they are highlighted, then click the Remove selected properties button. It can be tricky to select a row, but if you click in the row, but not inside a input field, it should highlight to show the row been selected.

Property sets can be referenced in your documents, email templates and the like using ${property:propertySetName.propertyName} notation. The propertySetName is the name of the property set, and propertyName is the name of the individual property defined in that property set.

Tips: Normally, property values are encoded to be HTML-safe when displayed in your documents, but if you have taken care to create a property value containing valid HTML, you can include that in your document using ${htmlproperty:propertySetName.propertyName} notation. You can use this as a simple, flexible way to insert variable or common HTML in your documents, including custom styles you frequently use in your documents.

Table of contents

Fields

Click on Fields to show all field templates in the selected library.

Most fields, of course, are defined in the document, which you can reference for details on configuring them. The process is the same.

The main purpose for a field template defined in a library is to create "standardized" field names and configuration. When creating documents, you can create fields based on those defined in the library so that their values take on the standard definition. Of course, any value can be overridden in the specific document's definition.

Table of contents

Parties

Click on Parties to show all party templates in the selected library.

Most parties, of course, are defined in the document.

The main purposes for a party template defined in a library are 1) to create a "standardized" name for your parties so that as you create multiple documents, you tend use the same name for the same roles across those documents; and 2) if you configure a party in a package as a 'To Do' party, then you can define the group that represents members of the party so that any member in the group can process transactions when the party is active.

If the package party is defined for To Do purposes, specify the To Do Group that represents the users who will be able to place this role. Also, if you support multiple companies, each branding library is able to set their own group to play the given role. So if you have an "Approver" role, you can set it to be one group for one company, but another group for the other company.

Table of contents

Packages

Packages allow you to bundle one or more documents so that they are processed as a group. Each party will be able to process one or more of the documents in the package. It is possible to have some parties only see a subset of documents.

You also configure the package parties who will process the documents. The initial list of parties come from the names defined in the documents you add. But you may find that you need to rename or group the parties; for example, one document may say call the party who fills in the document as "FirstParty" while another document may have called that party "Customer". In the package, if these are really the same person, you can bundle them together.

Click on Programming->Packages to show all packages of documents that are available to you.

Click on a package to view or configure it. To create a new package, select a template or similar existing package you have permission to access and click the Create new like button.

• Choose Enabled to allow the package to be used. If a package is no longer needed, click Disable.
• PathName is the unique path name for this package.
• Description is a short description.
• Comments is any other information you want to maintain.
• Permissions to access this package contain the standard List, View Details, Create Like, Update and Delete permission lists. Just choose which groups are allowed to do each of these operations on a package. Normally, the "programming" group has permission to this as it's not a general user task.

For the list of documents and parties on the right side, the fields are:

• The Choose documents shows each Library that is available to you. If you open the arrow, it will show the documents defined in each. Just click and drag a document from this list into the Documents in this package table. If other documents are already in the list, note the insertion bar when you drag the document over to choose to place it at the top (first), between documents, or at the bottom (last). Of course, you can re-order at any time.
• The Documents in this package table lists each document in the package and the order they will be presented. If you drag a document from the table back to the Choose documents tree and drop it anywhere there, the document will be removed from the package and will automatically be returned to the correct library where it came from.
• The Parties involved with this package of documents table lists all parties defined in the package, as well as the order in which they should process the package of documents. The first party is the "initiator" who starts the transaction and can be a normal user or an automated API party.
• The Package+disclosure view drop down list lets you choose the special document that plays the role of welcoming the parties, showing E-Sign disclosures, as well as the list of documents the party is expected to process. By default, this is the ESF/Library/Template/StandardPackageDisclosures document.

Click the Make Test version Production button to move a Test version package to Production.

If the package is already a Production version, use the Create next Test version button to create the next package that you can test until you are ready to make it production. You can also use the Revert to Test button to temporarily take the package out of production for a quick fix before you make it production again (do this with caution since a production transaction will get an error, or use the prior production version if one exists, while you are making this update).

Click the Customize logic button to add special processing rules to this package of documents.

Click the Map report fields to define the fields in the documents you have selected that you would like to include in reports or To Do lists for your internal parties.

Note that after any change to the package, including any changes made in other screens related to the package, you will have to click the Save button keep those changes.

Table of contents

Package document configuration

Note that you can drag to re-order the documents, or drag it back to the Choose documents list of libraries to remove it.

Click on a document from the Documents in this package table to configure the parties who will process that document.

Since package parties are defined initially from the parties defined in the various documents, it is possible that the names used in various documents are not consistent. This allows you to specify which package party will play the role for a given document party. Select the package party or parties who will be allowed to play the specified document party.

Click Ok to remember the changes. Click Cancel to discard any changes.

Tip: To save your changes, remember to click the Save button for the package.

Table of contents

Package party configuration

Note that you can drag a party to re-order the processing flow. If after you are done you have parties defined that do not reference any documents, you can remove them using the Remove X unused package parties button that appears below the list of parties.

Click on a party in the Parties involved with this package of documents to configure the package party.

• Package Party EsfName is the name of the party as used in the package. Remember, package parties initially default to the names they were given in the documents, but the names may not (most likely will not) be consistent across all of the documents, so this allows you to specify the name as it makes sense for this package.
• Display name is the name this party will use whenever it is shown to a user.
• Landing page defines the page the party will see when they first access the package of documents. The default is "Package (disclosures)" which shows the welcome message, E-Sign Disclosures and list of documents to be processed as specifed on the package's "Package+disclosure view". You may also select "First document" to land on the first document in the package that the party is allowed access to. Select "First To Do or First document" to land on the first document the party must work on, or the first document if all documents have been processed; this is used when a party may come back over time to complete the package so they resume on the first document that needs their action. Select "First To Do or Package" to land on the first document the party must work on, or the package document if all documents have been processed.
• Check Must be logged in if this party is supposed to be an internal user. This ensures that step is taken only by authenticated users.
• Check Allow delete tran if no signatures to allow the party to delete the transaction, if no signatures have been applied, from the package document. This is generally used only on the first party since they may start the transaction, and then decide not to continue. If the user does not complete it, or delete it, it will be in that user's To Do queue so they can resume later. If they are external users, the transaction will not progress unless the user comes back with the unique pickup link for it (like if they bookmarked the page or your process sent them an email with the link).
• For Select document parties for this package party select all document+party combinations that apply. You can use the special "View only" party to allow this party to view the document, but otherwise not be able to change it (or sign it).
• Select a To Do Party EsfName if this party actually belongs to a group of users. In a Library, you can define a Party template that is associated with a To Do Group so that anybody who belongs to the group can process the transaction via the To Do work queue. Select that Party name defined in a Library and be sure it has a group associated with. Note that by creating transaction templates with separate branding libraries, it is easy to set up a package where such a party belongs to different groups, such as when running the service for multiple companies or departments.
• In Renotify select the various intervals that you'd like an email re-notification to be sent to the party until the party step is completed (and the transaction is in progress). It is good to be able to remind a user to complete a document, but you don't want to pester them either.
• Check Email All To Do Parties if you've also set a To Do Party EsfName if you would like all users who belong to the group associated with the party to receive an email notification.
• In Notify email address spec (${EMAIL}) enter an email address or a document and field specification that contains the email address of the person to notify when this party is activated. The value will replace the ${EMAIL} specification used in the Email template.
• In Notify Email EsfName specify the Email template to use to notify this party.

Click Ok to keep any changes, otherwise click Cancel.

Tip: To save your changes, remember to click the Save button for the package.

Table of contents

Customize logic

It is often necessary to add additional processing logic to fine tune the process flow. You can set up special custom rules based on when in the process flow you want it, whether it's limited to a given set of documents or parties, and then add various actions you'd like to take place then.

Click on the Customize logic button on the package version to configure additional logic.

Click on the Create new custom logic button to add new processing logic rule. Or you can click on a previously created rule to update it.

• In When event(s) occur select at least one type of event that describes when you'd like the associated actions to run. You can choose from:
• Party created occurs when a package party is created.
• Party activated occurs when a package party is first activated to process the package.
• Party retrieved document occurs when a package party retrieves a document.
• Party review document occurs when a package party has filled out the form or is signing and clicks the review button.
• Party completed document occurs when a package party completes a given document.
• Party completed occurs when a package party complete all documents in the package that are assigned to him or her.
• Party transferred occurs if a user transfers a given package party to another person through the transaction details page in reports and general transaction search. This occurs when a transaction is started and it turns out there was an error, such as invalid email address, or you find another person actually needs to process it.
• Transaction started occurs when the transaction is first started.
• Transaction completed occurs when the transaction is completed.
• Transaction canceled occurs when the transaction is canceled.
• In Limit only to documents (optional) check any documents if the actions should only fire when the selected event(s) occur, but also only when the specified document is being processed. If you do not select any, then it will not matter which document is involved.
• In Limit only to parties (optional) check any parties if the actions should only fire when the selected event(s) occur, but also only when the specified party is processing the transaction. If you do no select any, then it will not matter which party is involved.
• In Actions you can drag to re-order existing actions or click the Delete button to remove it.
• Click the Add action button to add the actions you'd like to occur when the specified event arises, possibly limited based on the documents and parties selected. Choose Set field action to change any field values in your documents. Choose Calculate field value to calculate a value (add, subtract, multiply, divide). Choose Send email to send an email. Choose Change tran/party status... to cancel the transaction to skip a party step.

Click Ok to keep any changes, otherwise click Cancel.

Click Close to close the custom logic window.

Click Delete to delete the selected custom logic rule.

Tip: To save your changes, remember to click the Save button for the package.

Table of contents

Conditional actions

After you configure an action, you can specify a condition that will be checked before running your action. Conditions can be arbitrarily complex, but in practice few are.

By default, the initial condition associated with an action is called AND and by itself does nothing more than ensure all sub-conditions added to it must all be true to pass the test. You can convert it to an OR condition so that only one of the sub-conditions added to it must be true to pass the test.

Or you can negate any condition which basically evaluates to the opposite (also known as NOT), so if your condition is true, negating it means it will not pass, but if your condition is false, then negating it means it will pass.

Click on the IF condition button to show any conditions that apply to that action.

Initially, when there are no conditions yet set, it prompts you to Right-Click to add a new condition to the default AND condition. The top level condition must be an AND or OR condition. You cannot delete this top level condition, but you can convert the default AND to an OR condition, and you can of course negate whichever you choose.

Right-click on (Right-click to add conditions to AND) to add new conditions to the top level AND condition:

• Click Negate condition to convert the selected condition to do the opposite of what it normally would be, also known as NOT the condition.
• Click Convert to OR condition to change a selected AND condition (all conditions added to it must be true) to an OR condition (one condition added to it must be true). When the condition is an OR condition already, this option will let you convert it to an AND condition.
• Click Add OR condition if you need to add a condition that itself is true only if one of the sub-conditions you add to it is true.
• Click Add AND condition if you need to add a condition that itself is true only if all of the sub-conditions you add to it are true.
• Click Add ALL FIELDS BLANK check to add a condition in which all fields you specify must be blank (have no value). If you negate this check, it means "ANY FIELD is NON-BLANK," that is, it's true if any of the list fields has a value. You can just specify a single field to check.
• Click Add ANY FIELD BLANK check to add a condition in which any (at least one) of the fields you specify must be blank. If you negate this check, it means "ALL FIELDS are NON-BLANK," that is, it's true if all of the list of fields have a value. You can just specify a single field to check.
• Click Add SOME BUT NOT ALL FIELDS BLANK check to add a condition in which at least one field is blank and at least one field has a value. To work as expected, you must specify at least two fields.

Table of contents

All blank condition

After you have added or changed a condition, just click on the condition to configure it further.

AND and OR conditions have no specific condition editors, so for these special types of conditions, you just right-click on them to negate them, convert them from one type to the other, delete it (and all of its sub-conditions), or to add further sub-conditions to them.

Click on the All blank: condition to change which fields are checked to be blank. You can specify one or more fields to check. A popup editor will appear.

Click the Add field to check if blank button to specify a new field to check that it's blank (has no value).

• Choose from In document the name of the document where the field to check resides.
• Choose from Field the name of the field in the selected document to check.

You can specify one or more fields to check. In this case, all specified fields must be blank to pass the test.

If you negate this condition (NOT ALL BLANK), it passes if any of the fields specified has a value (ANY NON-BLANK).

Like always, click Ok to save your changes. Click Cancel to abandon the change. Click Close to close the popup window. Click Delete to delete a selected field check.

Tip: To save your changes, you will want to click the Ok button on the custom logic rule as well as click the Save button for the package. Once you do, when you click on the IF condition button, your conditions will be updated.

Table of contents

Any blank condition

Like the All blank condition, Any blank works the same way except that it is true if any of the fields you specify is blank. At least one blank field must be present to be true.

If you negate this condition (NOT ANY BLANK), it passes if all of the fields specified have a value (ALL NON-BLANK).

Some but not all fields blank condition

Like the All blank condition, Some but not all blank works the same way except that it is true if at least one field is blank and at least one field is non-blank (has a value). This condition only makes sense if at least two fields have been specified.

You rarely will negate this condition, but if you do it will be true if all of the fields are blank, or if all of the fields have a value.

Set field value action

When you need to change (or clear) a value, use the Set field value action. Click the Add field to set button to add a new field to set. Or you can click on a previously created rule to update it.

• For In document select the document where the field exists that will be set.
• For Set field select the field in the selected document that will be set.
• For New value or field spec to use enter a literal value (or leave blank to blank out the field) or ${ } notation to specify the new value for the field.

Click the Ok button to keep your changes, or click Cancel.

Click the Close button to close the set field value actions window.

Click the Delete button to delete the selected action.

Note that you can set multiple fields at the same time using this view.

Tip: To save your changes, you will want to click the Ok button on the custom logic rule as well as click the Save button for the package.

Table of contents

Calculate field value action

When you need to calculate a value (add, subtract, multiple or divide), use the Calculate field value action. Click the Add field to calculate button to add a new field to calculate. Or you can click on a previously created rule to update it.

This is only available for Integer, Decimal and Money fields.

You can think of this as doing the following in code: InDocument.SetField = FromDocument.Field OPERATOR FromDocument.Field

• For In document select the document where the field exists that will be set to the calculated value.
• For Set field select the field in the selected "in document" that will be used set by the calculation. This is the field that is changed.
• For From document (left side of operator) select the document where the first field can be found.
• For Field (left side of operator) select the field in the selected "from document" that will be used in the calculation. This field is not changed.
• For Operator select the operation to be applied to the left and right hand fields. + means addition; - means subtraction; * means multiplication; and / means division.
• For From document (right side of operator) select the document where the second field can be found.
• For Field (right side of operator) select the field in the selected "from document" that will be used in the calculation. This field is not changed.

Click the Ok button to keep your changes, or click Cancel.

Click the Close button to close the calculate field value actions window.

Click the Delete button to delete the selected action.

Note that you can calculate multiple fields at the same time using this view. Also, if you have a multi-step calculation, you can set the field to the first party of the calculation, and then in the next calculation reference that field in the left or right side to perform more operations on it.

Tip: To save your changes, you will want to click the Ok button on the custom logic rule as well as click the Save button for the package.

Table of contents

Send email action

When you need to send an email other than the party activation email (which is set in the package party view), use the Send email action. Click the Add email to send button to add a new email to send. Or you can click on a previously created rule to update it.

• For Email template choose the email template to send.
• For For party (${LINK}) select the party whose unique link will be used anywhere ${LINK} is specified in the selected email template. Note that whoever receives such a link will be able to act as that party.
• For Email address spec (${EMAIL}) enter an email address or ${ } field specification that will resolve to the email address to send to. This will replace the ${EMAIL} wherever used in the selected email template. If the For party above is selected and this email address specification is blank (or set to ${EMAIL} -- better to leave blank), the system will attempt to use the configured package party's email notification specification.
• For Attach document(s) select one or more documents from the package to send with the email. This will be the document snapshot that exists for the selected document and party. Of course, you can also choose the "Latest" party for a document to send whatever is the latest snapshot of that document at the time the email is being sent.
• Check Attach as PDF to combine the document snapshots into a single PDF file rather than sending them as attached HTML files. If any of the selected documents is configured for 'Landscape' orientation then all documents will be rendered as landscape in the PDF.

Click the Ok button to keep your changes, or click Cancel.

Click the Close button to close the send email actions window.

Click the Delete button to delete the selected action.

Note that you can send multiple emails at the same time using this view.

Tip: To save your changes, you will want to click the Ok button on the custom logic rule as well as click the Save button for the package.

Table of contents

Change tran/party status action

When you need to cancel a transaction or skip a party step in your workflow, use the Change tran/party status action. Click the Add status change button to add a new status change. Or you can click on a previously created rule to update it.

Cancel transaction action

Change the Status change type to 'Cancel transaction':

• For Status change type choose 'Cancel transaction'.
• For Reason provide a reason (it can include field specifications ${ } for variable substitution) why the transaction is being canceled.

Skip party action

Change the Status change type to 'Skip party':

• For Status change type choose 'Skip party'.
• For Reason provide a reason (it can include field specifications ${ } for variable substitution) why the party is being skipped.
• For Parties to skip select one or more parties to skip.

Click the Ok button to keep your changes, or click Cancel.

Click the Close button to close the transaction/party status change window.

Click the Delete button to delete the selected action.

Note that you can do multiple status change actions using this view.

Tip: To save your changes, you will want to click the Ok button on the custom logic rule as well as click the Save button for the package.

Table of contents

Map report fields

By default, all fields in your documents are fully encrypted and can only be accessed by a given package party in a transaction. However, often you may want some fields to be available for reports or shown in the To Do queue. For these reasons, you can map fields from the package to report fields.

Each time a transaction is saved (updated by a package party), all of the field mappings are applied so that reports will have the latest field values.

This also lets you map various fields that may be named "SSN", "SocialSecurityNumber", "so_sec_no" or "Tax_ID" to a single report field name so that you can create a report that essentially merges all such fields into a single report field. Use care when mapping such fields so that you map them to a common set of report fields and don't create multiple report fields that really have the same meaning.

Click the Map report fields button on the package version to set up mappings to report fields.

Click on the Map new report field button to add map a new report field. Or you can click on a previously created mapping to update it.

You can drag to re-order existing field mappings to control the order they will appear in the To Do listing. Otherwise, the order does not matter.

• In the Document drop down select the document from the package where the field to be mapped resides.
• In the Field drop down select the field in the selected document to map to a report field.
• In the Save value as report field drop down, select an existing report field that applies. If no such report field exists, select the "+Create new report field" option and a new report field of the same name and appropriate type will be created.
• Check Show To Do to have this field appear in the To Do queue for internal users who will process transactions this way.

Click the Ok button to keep your changes (you will need to do this if you re-order fields, too). Otherwise click Cancel to discard them.

Click Close to close the data field mapping window.

Click Delete to delete the selected field mapping.

You can also click the Reload tran report fields button to reload existing transactions should you have created new mappings after previous transactions were completed. Since report fields are only mapped when a transaction is updated, newly mapped fields won't be available to the reports for older transactions (or in progress transactions until a party next accesses it) unless you manually reload them here.

Tip: To save your changes, remember to click the Save button for the package.

Table of contents

Reload transaction report fields

To manually reload report fields for existing transactions using the current field mappings, click the Reload tran report fields button from the package's map report fields window.

• Select which transaction type(s) should be reloaded. Only those transactions you have access to and which use this package are listed.
• Select Production to reload production transactions, or Test to reload test transactions.
• Select the type of date and date range to limit which transactions are reloaded.
• In Tran id only reload enter a single transaction id to reload only that one specific transaction. Otherwise leave it blank.
• In Party email enter the email address of a party to limit the reload to just those transactions. Otherwise leave it blank.
• Check In progress to reload transactions that are in progress.
• Check Completed to reload transactions that are already completed.
• Check Canceled to reload transactions that are canceled.
• Check Suspended to reload transactions that are suspended.

Click the Reload report fields for matching transactions button to begin the reload.

Note that this process can take a long time based on the number of transactions that will match your selection criteria. (This process includes first finding all matching transactions, then loading each one, decrypting all of its data, parsing its XML structure, and then running the field mapping specifications.) Whenever possible, define all report field mappings before you start transactions, and if you do create new mappings later, attempt to limit the number of transactions that must be reloaded. You only need to reload them if you have reports or To Do transactions that otherwise show a blank field because the mapping was not in place when those transactions were last updated.

Table of contents

Transaction Templates

Transaction templates are used to define a runnable package of documents.

Click on Programming->Tran templates to list all transactions templates available to you.

Click on a transaction template to view or configure it. To create a new transaction template, select a template or similar existing transaction template you have permission to access and click the Create like button.

• Select Production enabled if you are ready to run production-level transactions. Your package must be at the production level, and you should also ensure all components used by the package are also at the production level. When you first enable production transactions, please run a "Test Like Production" transaction to see how it works using only production-level components. Select Production disabled to prevent production transactions from starting.
• Enter a # number and Production retention value to specify how long to keep production transactions. If you select "Forever" or "Now", the number field will not be necessary. Use of "Now" makes little sense in this context.
• Select Test enabled if you are ready to run testing-only transactions. You will then be able to run test transactions. Select Test disabled to prevent test transactions from starting.
• Enter a # number and Test retention value to specify how long to keep test transactions. If you select "Forever" or "Now", the number field will not be necessary. Use of "Now" makes little sense in this context. We recommend shorter retention values for test transactions, such as keeping them for 3 to 6 months.
• In PathName enter the name of this transaction template. It will be displayed under the Start transaction menu item.
• In Description give a brief overview of what this transaction is.
• In Package to use select the package that will be run.
• In Branding library to use select the library to be searched first to resolve components like images/logos, property sets, To Do parties, email templates, etc. If those items are not found in the branding library, it will look in the library where the current document is defined, and then ESF/Library/Template last.
• In Comments enter any information you want to maintain about the transaction.

The transaction template has standard List, View Details, Create Like, Update and Delete permissions under Permissions to access this transaction template.

It also has special permissions related to the transactions that are specified under Permissions for transaction

• Start permission specifies who can start the transaction. Specify ESF/Group/ExternalUsers to allow non-authenticated users to start the transaction, such as from a link on your web site.
• Cancel permission specifies who can cancel a running transaction.
• Re-Activate permission specifies who can re-activate a canceled transaction.
• Suspend permission specifies who can suspend a running transaction.
• Resume permission specifies who can resume a suspended transaction.

On the lower left side are URLs that can be used to start a transaction of this type. The Production URL is the base URL used to start a transaction. The Test URL adds the ESFTEST=Yes parameter. And the Test like Production URL adds the ESFLIKEPRODUCTION=Yes parameter to the Test URL.

Table of contents

Report Templates

Report templates are used to define a custom report that lists data elements about and from within the package of document specified in a transaction template. You must first map data elements in the package to report fields to list them in a custom report.

Click on Programming->Report templates to list all report templates available to you.

Click on a report template to view or configure it. To create a new report template, select a template or similar existing report template you have permission to access and click the Create like button.

• Click Enabled to allow this report to be run. Click Disabled to prevent it from running.
• In PathName give this report template a name. The name will appear under Reports menu item.
• In Description enter a short description of this report.
• In Comments enter any information you want to remember about this report.
• In Tran templates select one or more transaction types to be included this report. Of course, for the report to run as expected, the report fields must make sense across the various transaction types. Any report field that is not mapped by the transaction's package will be blank in the report.

The report template has standard List, View Details, Create Like, Update and Delete permissions under Permissions to access this report template.

It also has special permissions related to the reports that are specified under Permissions for reports

• Run permission specifies who can run the report. By default, users can only see test transactions they started themselves.
• See transactions started by external users specifies who can also see transactions started by external users.
• See transactions started by any other user specifies who can also see transactions started by any other user.
• See Production Transactions as well as Test specifies who can also see production transactions. By default, only Test transactions can be seen.
• Download report data in Excel or CSV format specifies who can download report data in Excel or CSV formats.
• View transaction email log specifies who can see email details about a transaction.
• View/download document snapshots specifies who can see and download document snapshots.
• View/download data snapshots specifies who can see and download data snapshots, which includes the data values stored in documents.
• Download complete transaction archives specifies who can download a complete transaction archive. This feature is not yet implemented.

Click on the Report fields button to configure the report fields that will appear in the custom report.

Table of contents

Report fields

Click the Report fields button on the report template to set up the report fields to include in the custom report.

Click on the Add report field button to add a new field. to the report. Or you can click on a previously created report field to update it.

You can drag to re-order existing fields to control the order they will appear in the report.

• In Report field select a user-defined or built-in report field to show in the report. The following are the built-in fields:
• esf_cancel_timestamp is the date/time the transaction was canceled.
• esf_created_by_user is the user who started the transaction, when it's not started by an external user.
• esf_expire_timestamp is the date/time the transaction is set to expire and be deleted from the system (this is set based on the transaction template's retention values).
• esf_last_updated_by_user is the user who last updated the transaction, when it's not last updated by an external user.
• esf_last_updated_timestamp is the date/time the transaction was last updated.
• esf_literal allows you to specify a fixed Literal value that will always appear in the column. This is mostly used for CSV integration with other systems where you need to provide a fixed value.
• esf_package_name is the PathName of the package referenced by the transaction.
• esf_stall_timestamp is the date/time the transaction stalled (was in progress, but had no active party), indicating a programming error.
• esf_start_timestamp is the date/time the transaction was started.
• esf_status is the transaction status: In progress, Canceled, Completed, or Suspended.
• esf_status_text is the transaction status description, which is typically the current document and party in the process flow.
• esf_transaction_id is the unique transaction id.
• esf_transaction_template_name is the PathName of the transaction template.
• In Column header specify the label to show in the column header for this field in the report.
• In Output format specify the format to use for the field.
• For general fields, you can select to show the entire value, or mask the leading or trailing characters and just show up to 4 of the actual characters.
• For date fields, you can select the format for the date.
• For date/time fields, you can select the format for the date/time.
• For user fields, you can select whether to display the name and/or email address of the user.
• For decimal/money fields, you can specify the format for the number.
• For integer fields, you can specify the format for the number.
• Check the Allow search box, when available, to allow for searching transactions based on the values held in this report field.

Click the Ok button to keep your changes, or click Cancel. This applies to changes to the report field specification, but also if you re-order the fields by dragging them to a new position.

Click the Close button to close the list of fields in the report window.

Click the Delete button to remove the selected report field.

Tip: To save your changes, you will want to click the Ok button on the list of fields window as well as click the Save button for the report template.

Table of contents

Integration Interface (API)

There are various ways to integrate other applications and web sites with Open eSignForms. They all assume the ability to access HTTPS links to the web site.

Each transaction template shows the "Start URL" which is used to start a new transaction of its type. There are two standard options you can include on the URL (or as HTTPS POST parameters):

• ESFTEST=Yes means that you want to start a Test transaction. We recommend using this during all integration testing. If you omit this parameter, it will be assume to be a Production transaction, but you can send it as ESFTEST=No to make it explicit.
• ESFLIKEPRODUCTION=Yes is only examined if ESFTEST=Yes is also included and controls whether the Test transaction should run using any Test versions found or not. When set to Yes it means even though it is a Test transaction, it will only select Production-level versions. We recommend setting this to Yes on your final integration tests to ensure it is working as expected using only Production-level versions. If this param is not present, it is assumed to have a No value.

From an email you send out, inline process

If you already have an email generating system, or you manually send them out, you can start a new transaction by embedding the transaction template's "Start URL" in the email you send out. When external users click on your link, it will take them to your Open eSignForms site where they can complete and sign as necessary.

The external user will start the transaction and act as the first party defined for the package of document(s).

Note that the transaction template must allow for "External users" to have "Start" permission on the transaction.

We call this "inline process" because the external user works on the document directly after clicking on the link.

From your web site, inline process

If you already have a web site, you can start a new transaction by embedding the transaction template's "Start URL" in your web site. When external users click on your link, it will take them to your Open eSignForms site where they can complete and sign as necessary. The link may also be embedded in an IFRAME or FORM, with the FORM allowing you to post some initial data collected from your form or provided by your web site.

The external user will start the transaction and act as the first party defined for the package of document(s).

Note that the transaction template must allow for "External users" to have "Start" permission on the transaction.

We call this "inline process" because the external user works on the document directly after clicking on the link.

From another web site or web-accessible application, inline process

Like above, this processing allows you to start the transaction as a specific user of Open eSignForms rather than an external user. This is often done from other web portals and applications where the user is authenticated in that system, and now you want to tie that user together with the Open eSignForms user. The link may also be embedded in an IFRAME or FORM, with the FORM allowing you to post some initial data collected from your form or provided by your web site.

To do this, you must include the following two additional HTTPS POST params (we do not recommend you ever including username and passwords in the URL as those values will be recorded in web server logs as well as the user's browser cache):

• ESFLOGINUSER=useremail@example.com specifies the user's login email address to authenticate the user who will start the transaction.
• ESFLOGINPASSWORD=user+password specifies the user's login password to authenticate the user who will start the transaction.

You must include both params as the system will not attempt authentication without both. That is, it will be treated just the same as an "external user" starting the transaction.

Note that the transaction template must allow for a group that the user belongs to to have "Start" permission on the transaction. You generally would not allow "external users" to start this type of transaction as the purpose is to run only user-authenticated transactions that are tied to the specified user.

We call this "inline process" because the user works on the document directly after clicking on the link.

From another web site or web-accessible application, email process (API)

Unlike the process above, this is suitable for full-API integration where your other application will start a new transaction without any user interactions. This API uses web-standard HTTPS POST of name-value pairs and will receive a simple text response for easy parsing of success or failure. Generally, the first party is fully processed and then the second party is notified by email for external users (or perhaps via the To Do queue for an internal user) to process the transaction.

Unlike the previous "inline process" versions, no web page is returned because it is assumed that the user is not present to handle the documents immediately.

Add the following additional HTTPS POST params for API-processing:

• ESFLOGINUSER=useremail@example.com specifies the user's login email address to authenticate the user who will start the transaction in API mode.
• ESFLOGINPASSWORD=user+password specifies the user's login password to authenticate the user who will start the transaction in API mode.
• ESFAUTOCOMPLETEFIRSTPARTY=Yes means that the first party, as defined by the required ESFLOGINUSER and ESFLOGINPASSWORD params, will be completed as a result of this API request, with any second party then notified.

Since no user is actually present, a standard web page response is not returned. Instead of a text/html (content/mime type) response, a text/plain response is sent as follows:

• If the request is not even processed due to an error, an HTTP 404 response code is sent to indicate the error.
• OK:transaction-id is returned if the transaction was successfully started and includes the transaction id after the colon.
• ERROR:error-mesage is returned if there was an error in user authentication or other transaction processing error, such as data validation errors. The error message may span more than one line with embedded newlines if more than one error was detected.

We call this "email process" because the next user will only gain access to the transaction after receiving an email containing their unique link. The link the user receives will not be the "Start URL" at all, but will be a pickup-link to retrieve an existing transaction. Of course, if there is no second party, the transaction will complete as expected.

Note that no document snapshots will exist for the first party since the documents were not, in fact, presented in Review mode. Data snapshots still are done.

Table of contents