Skip to main content
Mitratech Success Center

Email Templates

Process Director sends automated email notifications when certain workflow events occur. A workflow definition can specify a custom email template for any User step by referencing an email template stored in the Content List.

The email template specified in the step will only be used for that step. To modify the default emails for other events (e.g. step completed) you can create a new template email file. When an email needs to be sent, the system checks for the existence of the appropriate email file listed in the Email Template field of the step and if one is not found, the default email file is used instead.

image

Creating and Customizing Email Templates

You can create an email template by using creating a new eForm definition within Process Director. Ensure that you check the box that says "Email Template" when the Create eForm screen opens.

image

You can also use a custom ASCX file for your email template, just like you can when creating a regular eForm definition. Simply select the option you desire from the dropdown marked "Use Empty Word Doc eForm". In most cases, the "Use Empty Word Doc eForm" default choice is the simplest option.

Your email template is now stored in the Content List. You can edit the template by selecting the template to edit and then select the Edit tab. You can make changes to your template in your preferred editor.

Email Variables

Variable substitutions are performed when an email file is processed for a workflow request. System variables can be added to the email using the {varname} keyword. This entire keyword will be substituted with the system variable for the corresponding varname. To see the complete list of system variables (i.e. varname) refer to the chapter on eForms, in the section named System Variables. Not all system variables are available for every event that generates an email.

The Subject, FromEmail, MailPriority, FromDisplay, SendAsAttachment, GroupName and CancelEmail are contained in each email file as property of a built-in control called EmailData.

EmailData Control

The Email Data object is available from this control in MS Word: Add-ins > BP Logix eForm Controls > Other Controls > Email Data

Untitled-2.png

Inserting the Email Data control produces this object in your eForm. By double-clicking on it you can edit its properties in the Email Data Control box below.

image

Properties

SYSTEM VARIABLE

DESCRIPTION

OPTION

Subject

Subject for email

 

MailPriority

Low

Low Priority

   

Normal

Normal Importance

High

High Importance

Sets the priority of the email. Supports the following values:

FromEmail

If the “FromEmail” address is not filled in on the EmailData tag in the email template, it will be set by the first value that is not empty from the following list:

 
 

Value configured in IT Admin under “Installation settings” in “Global Variables” Configured in email or eForm If Cancelled, Administrator email that performed operation; Workflow Initiator; The “Registered Email Address” in the IT Admin section under Installation Settings; “process-director@bplogix.com”.

 

FromDisplay

To configure a “FromEmail” address that contains a display name that is different than the email address, use this property. This will allow you to have a different reply address than the one the user sees.

 

SendAsAttachment

This property allows you to send an object as an attachment in the email. You can specify what attachment to send by using a “GroupName” for the object(s) and using the “GroupName” property.

GroupName

GroupName

Only attach documents in the specified group of attached documents. If you don’t specify the GroupName of objects to include in the email, it will send all groups of attachments in the eForm.

 

CancelEmail

Set this property to true when an email does not need to be sent out based on a condition.

 

PlainText

Selecting this check box will strip the email of HTML information and transmit it using plain text. This is used sometimes to make emails more legible on PDAs or less advanced operating systems (Mac OS X) receiving email from Exchange servers.

 

CCEmail

A list of comma separated or semi-colon separated email address that will be CC'd.

 

BCCEmail

A list of comma separated or semi-colon separated email addresses that will be BCC'd.

 

You can add multiple EmailData controls to an email template. Use the condition builder to optionally show and hide these by going to the control in the eForm properties page and setting a condition on each EmailData tag created. Each tag has a unique ID.

image

Once you have multiple Email Data objects on the email template, you’ll need to set up conditional visibility of the objects. On the eForms Controls tab of the email template file, you can set conditions of what email data or email sections should be used like this:

image

This Email Data object will be visible when the email type is “Task Assigned”. There is more about these Email types in the next section, “Email Template Conditional Processing”. One more thing to note: when multiple Email Data objects’ conditional statements will evaluate as “true”, then PD will work through the separate Email Data objects in order, and information in properties input boxes will be replaced by non-blank properties boxes of the next Email Data object. If any of the “Cancel Email” boxes are checked in any displayed Email Data objects, the email will not be sent.

There is one email type that is sent when a user's task is completed due to a condition that completes the task without the user's involvement. For example, a task may assigned to a group of users, but be set to complete when the first user in the assigned group completes the task. In this case, the default behavior is for all users to receive the task completion email. Essentially, for any function that causes a user to be marked as "Not Required", all assigned users will receive email notifications that the task is complete. If you do not want this behavior, add an "emaildata" tag or control to the email template with the "Cancel Email" option set to True.

Be sure to place that Email Data control in a section that is visible when the email type is "not needed".

ASPX Format

<bpx:EmailData ID="StepStarted" runat="server" Subject="…subject line…" MailPriority="High"

FromEmail="{CREATE_USER, format=email}" FromDisplay="{CREATE_USER}" SendAsAttachment="True"

GroupName="Resume" CancelEmail="True">

</bpx:EmailData>

Email Template Conditional Processing

The email templates can optionally contain Section tags that can control what portions of the email should be displayed under different conditions (e.g. value of a form field). You can optionally display any control that has an ID which will display in the list of controls on the eForm properties page. Conditional processing allows you to display a type of email to use such as the reminder email type. You can conditionally display controls based on the type of email. The following email types are available in Process Director:

  • Task Assigned
  • Reminder Email
  • Task Timeout
  • Task Cancelled
  • Step Started
  • Step Stopped

Refer to the chapter on eForm Definitions for more information on conditional processing. To test email templates that contain eForm tags, upload the email template to Process Director as an eForm but marked as an Email Template to have the built-in parser validate the use of your eForm tags. This will only allow the email template to be validated; it will not be a valid eForm.

Task Links in an Email

The email templates can optionally contain links that allow the user to complete their task. This system tag will add the task URL to the link tag in the HTML email allowing the user to click on it to open in the browser and complete their task.

In MS Word:

{EMAIL_URL}

In .ascx:

<bpx:HTML ID="emailLink" runat="server" HTMLString="<a href="{EMAIL_URL}>Click here to view the workflow</a>">

</bpx:HTML>

This system tag will return the URL that can be placed within an <A> tag on the HTML email.

Complete Links in an Email

Email templates can contain links that allow the user to complete their task without having to view an eForm.

{EMAIL_RESULT_LINKS, comments=1, confirm=1, separator="&lt;br>", icon=1}

This system tag will return the possible branches to take. It creates an HTML link with the URLs for all of the possible branches in a Workflow or results in a Process Timeline activity assigned to the user.

ARGUMENT

TYPE

DEFINITION

comments

true/false(default value)

The user is prompted to comment if true

Confirm

true(default value)/false

The user is required to confirm the task has been completed

Separator

HTML tags

characters to separate the list of links

Icon

true(default)/false

Optional icons/images from the workflow branches appear next to each of the links.

NOTE: Process Timeline results do not have image icons.

Example

Possible Branches to Take:

{EMAIL_RESULT_LINKS,comments=1,confirm=1,separator="&lt;br>",icon=1}{Emai l_result_list}

This system tag will return a comma separated list of all of the possible results from the current branch in a Workflow or a result in a Process Timeline activity assigned to the user. This tag is useful for reply options the recipient must use. The next process may be scanning to match text in the sent Email.

Example

Please enter one of these keywords in responding to this Email: {Email_result_list}

{EmailCompleteLink, text=Approve, comments=1, confirm=1, action=Approve}

This System Tag is a links to a web page allowing their user to complete their task.

Each EmailCompleteLink System Tag with its arguments corresponds to one branch in a Workflow or a result in a Process Timeline activity. Remember to name this Email as the “Default Email template” in the Workflow or Process Timeline activity.

ARGUMENT

TYPE

DEFINITION

Text

string

text to display on the link (e.g. Approve, Resubmit, Reject)

Comments

true/false(default value)

The user is prompted to comment if true

Confirm

true(default value)/false

The user is required to confirm the task has been completed

Action

string

The Workflow branch name or the Process Timeline activity result (e.g. Approve, Resubmit, Reject)

Example

{EmailCompleteLink,text=APPROVE, comments=true, confirm=true, action=APPROVED}

{EmailCompleteLink,text=RESUBMIT, comments=true, confirm=true, action=RESUBMIT}

{EMAIL_COMPLETE_URL, action=Approve, comments=1, confirm=1}

This system tag will return the URL that can be placed within an <A> tag on the HTML email.

ARGUMENT

TYPE

DEFINITION

Text

string

text to display on the link (e.g. Approve, Resubmit, Reject)

Comments

true/false(default value)

The user is prompted to comment if true

Confirm

true(default value)/false

The user is required to confirm the task has been completed

Action

string

The Workflow branch name or the Process Timeline activity result (e.g. Approve, Resubmit, Reject)

URL Access to the Process Instance

Workflow (wd.aspx)

Description

This URL can be used for in Workflow emails. It is used to construct a hotlink back to the originating workflow.

Parameters

PARAMETER NAME

DESCRIPTION

forminstid

The ID of the form instance to display.

Examples

This example will create a hotlink in an ASCX Email template which points back to the workflow eForm

<bpx:HTML runat="server" HTMLString="<a href='{INTERFACE_URL}wd.aspx?forminstid={FORM_INSTANCE_ID}'>

Click Here to View the Form Instance</a>">

</bpx:HTML>

Process Timeline (pd.aspx)

Description

This URL can be used for in Process Timeline emails. It is used to construct a hotlink back to the originating Process Timeline.

Parameters

PARAMETER NAME

DESCRIPTION

forminstid

The ID of the form instance to display.

Examples

This example will create a hotlink in an ASCX Email template which points back to the Process Timeline eForm

<bpx:HTML runat="server" HTMLString="<a href='{INTERFACE_URL}pd.aspx?forminstid={FORM_INSTANCE_ID}'>

Click Here to View the Form Instance</a>">

</bpx:HTML>

Dropdown List Content Objects

This object allows you to create content for a dropdown on your eForm. This will automatically populate a dropdown control with the data you create. You can create a Dropdown List Content Object by selecting from the Create New dropdown. Enter a name for the object and click OK.

image

Click on the “Add DropDown Entry” button to add items to the dropdown list. Enter a name and optional value to each item.

Additionally you can manually enter date into your dropdown list as rows in the TextBox View tab. You can enter this data directly into the text box or Copy-Paste from another application.

image

eForms

Electronic forms (eForms) are web-based forms that can be published and made available to users so they can fill them out and submit them online from within their browser. When an eForm is completed, it can be automatically routed using a workflow definition. This chapter will describe how to create and manage an eForm, how to set the validation policies for the form fields and the optional scripting APIs that are available for interfacing with external systems and providing custom business logic.

The eForms can be created using the eForm Builder or an ASPX development tool. The eForm Builder requires the BP Logix Plug-in.

eForm Definitions

eForm definitions are stored in the Process Director database. eForm definitions (templates) have properties similar to other objects, such as documents.

An eForm definition is made available to users through their profile, the content list or from within a Knowledge View. The eForm definition allows a user to fill out and submit form based information directly from within their browser. When an eForm is submitted, the form data entered by the user is saved as a form data object. This form data is stored in the Process Director database and can be processed by a workflow. When viewing the data for a completed form the eForm definition that was used to submit the information is used to display the data.

eForms In the Content List

When an eForm is filled out and submitted the data is stored in the content list as an object under the eForm definition. To view the completed forms for an eForm definition, click on the eForm name or the image icon in the content list.

The completed forms are similar to other objects in the Process Director database supporting permissions, categories, properties and workflows. Users must be given View permission to view completed form data in the content list. Users that are given View Children permission to an eForm definition will automatically be given View permission when form data is captured and stored under that eForm definition.

image

Adding a New eForm Definition

To create a new eForm definition, use the Create New dropdown in the content list and choose the eForm Definition menu item. A user must have Modify permission to the parent folder to create an eForm definition. If a user does not have the appropriate permission, the hotlink will not appear.

image

The Create eForm dialog will display, select "Use Empty Word Doc eForm" from the dropdown. Enter a required name for the form and optionally give it a description. Click OK to create the form.

image

You will be directed to “Edit” tab of the newly created form. You can now make changes to this eForm definition using the Edit button in the form properties. Refer to the section named eForm Builder in this chapter for more information on building and modifying the eForms.

Updating an eForm Definition

When an eForm definition is stored on the server it provides many of the same capabilities available to documents. It supports a version history, properties, permissions, check-in and check-out, and categorization options. Users with Modify permission to an eForm definition can modify or update it. To update the eForm, view the properties by selecting the image icon in the content list and select the Edit button.

This will display a screen that allows the eForm to be checked-out and modified. Selecting the “Check Out And Edit” button will automatically check-out the eForm so no other users can modify it. It will also download the eForm and open the eForm Builder in MS Word. When you are done with your changes save and close the document. Navigate back to the server and click on the “Upload and Check In”. If you are going to make changes to the eForm offline, or for extended periods, use the “Check Out” button and download the eForm to your desktop. When you are done making changes, login to the server and click on the “Upload New Version” button that is displayed.

image

eForm Definition URL

eForms can be run using a URL (for example linked from your Intranet portal). This URL can be found on the eForm Definition property page, and looks similar to this:

http://server_name/form.aspx?pid=PP&formid=NN

Where server_name is the hostname of BP Logix and PP is the internal ID of the Partition and NN is the internal ID of the eForm Definition. You can pass values for form fields on the URL which will default or override the values for the specified fields. For example:

http://server_name/form.aspx?pid=PP&...me+Value&EXT_F Ield2=Another+Value&nohome=1&completepage=URL&completetext=text

Prepend EXT_ for any form fields on the URL. Be sure to URL encode any values.

The nohome parameter controls whether the home page should be opened when the link to the task list or eForm is clicked. Set nohome to 1 to ensure that the home page isn’t opened.

The completepage and completetext specify the URL of the page that completing the eForm should redirect to and the text displayed with the URL.

Other eForm Definition Options

There are a number of eForm options available from the options menu that drops down once you click the Options button in the upper right corner of the eForm definitions screen.

image

Permissions

The permissions option enables you to create custom permissions for the eForm to determine who may view, edit, modify, or perform other actions on the eForm.

image

You can set various permissions for specific users or for user groups, giving you complete control over user access to the eForm. The "Add Permissions" section is where you can set the permissions you desire by setting the appropriate settings, then clicking the "Add Permissions" button. Below the "Add Permissions" section is a list of all permissions that have been created for the eForm.

Meta Data

Meta Data categories and attributes can be assigned to each eForm.

image

When you click the "Assign Meta Data" button, it opens a dialog box from which you can choose the Meta Data categories you wish to assign.

image

Once you have chosen the Meta Data categories, the eForm definition screen will display any attributes from the categories. You can then enter the appropriate attribute values into the text boxes provided. Once you have filled in the attribute values, you have two options for adding the Meta Data to the child instances of the eForm definition.

Click the "Add Meta Data to All Child Items" button to add the Meta Data to the child items. Click the "Replace Meta Data to All Child Items" button to replace the current Meta Data assignments with the ones currently displayed on the eForm definition screen.

image

References

There are a number of cases when you may wish to automatically attach a document or some other file to a form instance. For example, you may wish to attach a policy document to a Human Resources form. Adding a

reference to the form will attach the references file(s) when a new eForm instance is created. Adding a "Show Attachments' control the eForm definition will enable the attached document to be displayed on each eForm instance.

image

You can add an attachment by using the dropdown menu in the upper right portion of the screen, which is labeled "Create New…"

image

You have the choice of adding a reference to an existing document from the Content List, or by uploading a new document from your computer to the Content List. If you select "Reference to item", Process Director will open the "Add Reference" box to allow you to choose an item from the Content list to create the reference.

image

If you choose Document/File, Process Director will present an upload dialog box to choose the file to upload. Checking the "Use Detailed upload" checkbox will expose additional uploading options. Among the additional upload options are options to upload two versions of the document: a copy of the managed document, which is useful for controlled documents, and a copy of the document that is optimized for viewing in a web browser.

image

Object Links

The Object Links screen shows all Process Director objects which have a link to the eForm definition, or to which the eForm definition has a link. Examples of linked objects would include the Process Timeline or Workflow that the eForm starts on submission, or Business Rules used by the eForm, or which use eForm fields to evaluate conditions.

Radios buttons allow you to switch between views of Process Director objects that point to the eForm, or objects to which the eForm points.

image

Create view (SQL)

When you create an eForm definition in Process Director, there is a tendency to think of the eForm instances as being stored in a table, with each eForm field as a column, and each row containing an eForm instance. In reality, though, the database schema is far more complicated than that. Yet, there are many times when you wish to use tabular data from an eForm to use elsewhere in Process Director.

Let's take an example where you may have an eForm that contains customer data, with one eForm instance per customer. You may wish to create a dropdown in another form that displays customer names from the customer eForm. In this case, you can create a view from the customer eForm that extracts the customer names and adds them to a view that is accessible through the Process Director internal database. In essence, doing so is similar to creating a database table that lists customer names, and which you can use to fill dropdown objects.

image

You can create the view you desire by checking the field names in the "Fields to use in view" section of the screen, then clicking the "Re-Generate View" button.

image

Once you click the "Re-generate View" button, the appropriate SQL syntax that creates the view is automatically written into the "SQL Create View Command" section of the screen.

image

You can customize the SQL syntax as you desire, or you can simply accept the default SQL command that was created when you clicked the "Re-generate View" button. When the SQL syntax creates the desired view you wish to create, click the "Create View" button to automatically create the view in the Process Director internal database.

image

When the view is created, an editable SQL delete command is created in the "SQL Delete View Command" section. You can run this command by clicking the "Remove View" button, which will delete it from the Process Director internal database.

Once you have created the view, it is accessible in Process Director through the database connector. This means that you can use the views to create dropdown fills from the database, or to use the view in reports.

eForm Builder

eForm definitions are stored in the Process Director database. These eForm definitions can be created using the BP Logix eForm Builder or with your existing HTML authoring tool. The BP Logix eForm Builder runs as a plug-in to Microsoft Word.

Regardless of the method used to create the eForm, end-users are presented with an HTML rendition of the electronic form. This allows your users to fill out and submit forms from within their browser.

The eForm Builder is used to control what the form looks like. The properties of the eForm definition on the server control the default values, validation and pre-population of fields on the form.

To use the eForm Builder, the BP Logix plug-in must be installed. The eForm Builder runs as an add-in to Microsoft Word.

You can download the plug-in here: http://www.bplogix.com/install/wd/BPLogixPlugin.exe

To edit an eForm, open an eForm definition in Process Director. If an eForm definition does not exist, create a new MS Word document and save it. Use the Create New dropdown in the content list and choose the eForm Definition menu item.

image

The eForm Builder will display a new menu button in MS Word called eForm Controls. This menu will display a dropdown with the input controls that can be added to this form. The input controls use the native MS Word form fields for constructing the eForm. The standard MS Word formatting options are used to format the layout and control the appearance of the eForm. Using tables inside MS Word is important because that is how you can control the layout and formatting of the form when it is rendered in the browser. If you have the BP Logix plugin installed, you can use it by opening MS word, clicking on the Add-Ins tab, then on the BP Logix eForm Controls dropdown.

image

Edit an eForm Definition

By clicking on the “Edit” tab you will have the option to “Check Out” the eForm and make changes.

image

Once you have made your changes you will have to upload the edited eForm to the server. This is also located under the Edit tab.

image

When developing your form you are working in the ASP.Net environment. You have all of the ASP.Net controls available to you. You will also have additional controls available see the chapter labeled Controls.

eForm Properties

Once you have made your changes, you may also set specific options for the form and form fields. As well as providing an eForm definition name and an Instantiated eForm Name. Use the eForm properties page to display these options.

image

You will notice a series of tabs; eForm Options, Custom Task Event Mapping and eForm Controls. These tabs provide options to your eForm.

eForm Options

The eForm options tab allows the default behavior of the form to be changed. The options include the ability to change default styles and how to handle validation errors.

Associating processes with eForms allows the eForm to reference steps and other information in that process. “Default Styles” control the stylized borders and colors around eForm controls depending on the controls’ statuses (enabled, required, disabled, or error).

The Instantiated eForm Name field determines the name of each eForm instance. One should usually use System Variables here so that the eForm’s instance’s name is relevant to the specific instance.

Entire form is read-only when

Form definitions can be configured as "read-only". If the relevant condition is met, the form will act as though the user does not have modify permission on the form (whether or not that would otherwise be the case). An open form in "read-only" state will not trigger form locking.

Custom Task Event Mapping

This tab allows eForm Custom Tasks to be mapped to different events that occur when the form is run. The eForm Custom Tasks provide enhanced functions to connect to external data sources and manipulate data on the form. The different events that a Custom Task can be mapped to are in the dropdown list.

image

The following eForm events can be mapped using custom tasks. The order in this table is the order that the events will be called.

EVENT

DESCRIPTION

specific form event

This allows you to tie a custom task to a specific form control that is marked as an event field.

[Event]

Any event from the form (a button, an event field being changed, etc.) will call this event.

[Form Creation]

This event is only called once per form instance to initialize the form data.

[View State Init]

This event is called every time a form is opened. It will not be called for postbacks on the current view.

[Before Conditions]

This event is called prior to evaluating the form conditions (which control the visibility, the required setting, the enabled setting, etc.).

[After Conditions]

This event is called after evaluating the form conditions.

[Before Validation]

This event is called if the user hits a complete button, prior to the form validation.

[After Validation]

This event is called if the user hits a complete button, after the form validation.

[eForm Completed]

This event is called if the user hits a complete button, and the validation was successful.

[eForm Display]

This event is called prior to displaying the form. This will be called on every postback, and when the form is fist displayed.

The order of the events is very specific. For example, If the user changes a dropdown form field which is an event field, the custom tasks mapped to events in the following order will be called if configured: specific form event, [Event], [Before Conditions], [After Conditions], [eForm Display].

If a user hits the OK button on a form, and the validation succeeds, the events will occur in this order: [Event], [Before Conditions], [After Conditions], [Before Validation], [After Validation], [eForm Completed].

If a user hits the OK button on a form, and the validation fails, the events will occur in this order: [Event], [Before Conditions], [After Conditions], [Before Validation], [After Validation], [eForm Display].

eForm Controls

The tab displays a list of all the controls (i.e. form fields) on the eForm definition. Properties can be configured for these form controls (fields) by clicking on the ‘Edit’ link.

image

Form Field Properties

The Form Field Properties page allows you to configure the properties of the form field: you can configure the form field’s tooltip, its Friendly Name, the minimum and maximum values it can hold, as well as under what conditions the form field will be enabled, viewable, or required. You can also configure the form field’s default value, data type, and attribute to which it links.

image

The form field properties include:

Event Field

If checked off, this form field will trigger an event when interacted with. Events can be used to update the form by triggering custom tasks or custom form scripts.

Synchronize Field Within Process

If checked, this field will synchronize values will all other form fields that have the same names but are on different forms with different definitions in the same Process. When the value of a synced form field is updated, the value will be synchronized with all other form fields with the same names in the Process, whether or not those form fields are also marked as synchronized. However, if a form field’s value is updated and that form field is not marked as a synchronized field, it will not update the values of other fields with the same names in the process, even if those fields are marked as synchronized.

If a column in an array is marked as synchronized, the number of rows and the content of that column will be synced with all other arrays in the process containing a column of the same name. This means that adding and removing rows in an array with a synced column will also add and remove rows in other arrays in the process with columns of the same name. Because synchronized array fields are so powerful, caution is recommended when using synchronized fields with arrays. Instead, we recommend alternatives, like the Copy Form Data custom task.

ToolTip

When moused over, the form field will display the text entered into this text box as a tooltip.

Link to Dropdown Object

This allows you to fill a Dropdown field with the content from a dropdown object. You can link multiple dropdowns to dropdown objects, which allows you to reuse dropdown objects in multiple forms.

Data Type

image

Setting the data type will enforce that the form field accepts data formatted as the appropriate type. The Data Type can be any of the following:

  • Text: this option allows for arbitrary text to be entered into the form field
  • Examples: “foo”, “bar”
  • Number: this option ensures that the form field contains a number (either with or without a decimal)
  • Examples: “10”, “9.75”
  • Date: this option ensures that the field contains a date. Dates must be in a format that can be interpreted by .NET.
  • Date/Time: this option ensures that the field contains a date and time. DateTimes must be in a format that can be interpreted by .NET.
  • Time: this option ensures that the field contains a time, which can be in any of the following formats. Times must be in a format that can be interpreted by .NET.
  • Currency: this option ensures that the contents of the field can be interpreted as an amount of currency
  • Examples: “22”, “22.32”
  • Integer Only: this option ensures that the field contains an integer. It also allows you to specify a minimum and maximum value that the integer can be.
  • Examples: “1”, “394221”
  • Email Address: this option ensures that the field contains an email address. As a user warning, email addresses should not have any trailing spaces, or they will be rejected as invalid.
  • SSN: This option ensures that the field contains an American Social Security Number, with or without dashes.
  • Examples: “123456789”, “123-45-6789”
  • Phone Number: This option ensures that the field contains a phone number. Most formats people usually use to type phone numbers will be accepted.
  • Examples: “(123) 456-7890”, “+1 123-456-7890”, “123-4FO-OBAR x 4321”
  • ZIP Code: This option ensures that the field contains an American ZIP Code. The ZIP code can contain only five digits or all nine digits.
  • Examples: “12345”, “12345-6789”, “123456789”

Changing Data Types

Occasionally, it may be necessary to change the data type of an eForm Field. For instance, one common mistake implementers make is setting the data type of a field like a Zip Code to "Number", because the field contains only digits. The natural assumption implementers make is that, since the field contains only digits, it must be a number field. This is generally incorrect, since the best practice is that if you are not going to do math on a field value it is not a number. Moreover, treating fields like Zip Codes as numbers will cause them to sort differently (in numerical order) than they would sort if they were text (alphabetical order).

Often, problems don't become apparent until a number of processes have already been started, so you not only wish to change the data type for future instances of the eForm, you also want to change the data type for past instances as well. Happily, Process Director enables you to make the change retroactive by following the procedure below:

  1. Place the mouse pointer in the workspace tab area at the top of the page, and click the right mouse button. This will place the page in Debug mode, and a dialog box will appear notifying you that the mode has been changed. Click the OK button to close the dialog box.
    image
  2. Open the eForm Definition and click the the eForm Controls tab. In Debug mode, the eForm Controls Tab will look slightly different.
    image
  3. Click the edit button to open the field properties dialog box for the field you'd like to change.
  4. Change the data type of the field to the desired data type and click the OK button to close the field properties dialog box.
  5. Click the Update button to save the change to the eForm Definition.
  6. In the Commands column of the eForm Properties tab, click the Update Old Instances link. A confirmation dialog box will appear.
    image
  7. Click the OK button to confirm the change, close the dialog box, and update all previous eForm Instances to the new data type for the field.

Default Value

image

You can specify the default value of a form field. The Default Value dropdown allows you to select from a list of common default values, like Workflow Instance Names or the results of Business Rules. You can also specify the default be set to a custom value or result from a System Variable Tag.

Set Read-only Options

This option gives you the ability to Enable or Disable a form control including the sections and collapsible sections. You may also Enable or Disable based on a condition using the Condition Builder.

image

Set Display Options

This option gives you the ability to Show or Hide a form control including the sections and collapsible sections. You may also Show or Hide based on a condition using the Condition Builder.

image

Set Required Options

This option gives you the ability to set the form control as required or not required including the sections and collapsible sections. You may also set the form control as required or not required based on a condition using the Condition Builder.

image

image

The following video will show you how to configure an eForm using a sample form:

Validation Rules

The tab allows you to add custom validation to the form. By clicking on the Add Validation Rule button you can your own validation message. Create a condition and if that condition is met or not met you can display a custom message.

image

Using the MS Word Form Fields

The eForm Builder runs as a plug-in to MS Word. It supports the native MS Word form fields. Only certain properties in these form fields are supported by the eForm Builder. When a form field is added, it must contain a name in the Name field. Default names are used when fields are added (e.g. Text1, Text2), however it is recommended these be changed to a field name that is meaningful to the form. If a Name is empty, the field will not appear on the eForm. These field names must be unique and cannot contain spaces. When a name in the Name field is entered, if that name is a duplicate of another field, the other fields Name will be removed.

See the eForm Controls topic for specific information on the different eForm Controls, and how to add them to the Word Template.

Stylizing eForms using MS Word and CSS

You can apply a CSS style to eForm elements using Microsoft Word. Create a customized style in Microsoft Word. Click to find out how. Apply that customized style to the text, table rows, or other elements you want stylized.

In a custom CSS file, create a class with the same name as the style, and set the style’s properties there. In all eForms on Process Director, all elements with that style name will be stylized the same way.

To add a custom CSS file to Process Director, see the Developer’s Guide.

Using Word Templates for eForms

Process Director allows the use of Microsoft Word templates. This enables control of formatting changes to multiple eForms. By Checking Out and Editing a form you can have the form changed based on the template that is attached to the form. This template can be stored on a network drive.

To Create new eForm template using the eForm Builder in MS Word

  1. Create MS Word template eForm.
  2. Create MS Word Styles for all areas that want formatting.
  3. Create default text and data for eForm.
  4. Upload this eForm to Process Director as an eForm document template (To be used as for new eForms).
  5. Save this doc as a Word Template (.dot or .dotx) in a shared network folder.
  6. Ensure Word doc is "linked" to Word Template and "auto-apply" in Microsoft Word's Templates and Add-ins options.
    image

To create a new eForm (using a template)

  1. Copy eForm document template in Process Director.
  2. Ensure the Word Template "link" correct in Microsoft Word's Templates and Add-ins options.
  3. Edit new eForm

To change styles of the template

  1. Edit the Word Template (.dot or .dotx).
  2. Check out and Edit any eForm that uses this.
  3. Ensure new template styles are applied.
  4. Upload and Check in.

eForm Locking

EForms can be locked by users, preventing other users from making changes to that instance of the form while the form is still locked. If a user views a form that is unlocked, but for which form locking is enabled, the form will be locked for all users except that user. The form remains locked until the user leaves the form. If another user views a locked form, all controls will appear disabled. You can display text for users viewing a locked form and optionally allow them to unlock a locked form using the Lock Form Control.

image

To enable form locking, select the “Enable Form Locking” checkbox in the options tab on the eForm definition properties page.

image

EForm locking can be problematic in some cases. If one user needs to review the form, without making changes, while another user in the process is trying to complete a task, the reviewer would lock the form, preventing the task assignee from completing his work. If multiple users can access the form, then the user that opens the form first will lock the others out.

For this reason, the eForm definition allows you to create conditions on the "Entire form is read-only when" option. This option allows you to determine conditions when the form can be made read-only. This prevents editing in specified circumstances, without locking the form for all users.

eForm Controls

The eForm Builder runs as a plug-in to MS Word. It supports the native MS Word form fields, but only certain properties in these form fields are supported by the eForm Builder. BP Logixs recommends using the BP Logix Word plugin to create eForm fields in the Word Template, as these are controls that can be natively incorporated into the eForm Template by process Director.

When an eForm control is added to the template, the control must contain a name in the Name property. Default names are used when fields are added (e.g. Text1, Text2), however, it is recommended these be changed to a field name that is meaningful to the form. If a Name is empty, the field will not appear on the eForm. These field names must be unique and cannot contain spaces. When a name in the Name field is entered, if that name is a duplicate of another field, the other fields Name will be removed.

Adding eForm Controls to the Word Template

The Process Director Plugin for Microsoft Word implements all of the controls you need to build eForms. The controls can be accessed from the Add-Ins tab of Microsoft Word, using the BP Logix eForm Controls menu. This dropdown menu contains the Process Director eForms controls, organized to group similar controls together. Selecting any control from this menu places the control on the Word page at the current cursor location.

image

The image below is a sample of what each input control type will appear like on a form when displayed to a user in their browser. The following sections described how each of these types can be added using the eForm Builder. This sample contains no formatting and is only intended to show how the input controls are rendered in the browser.

image

Common eForm Controls

The items in the top portion of the eForms Controls dropdown displays the most commonly-used controls for the eForm Builder.

Input Control

Selecting this menu item places an input box in the document where the cursor is located. The name of the input control can be changed in the properties menu, and the size can be changed by dragging the sizing handles of the input field to the desired dimensions.

image

Set the Name to the name of the field you want to use on the eForm. The fields name and description can be changed in the “Input” tab of the properties, while the formatting can be changed in what we conveniently call the “Formatting” tab of the properties.

image

Check Box

Selecting this menu item places a check box in the document where the cursor is located.

image

The name and settings of the check box can be modified by right clicking on the field and selecting the Properties menu item. Set the Name to the name of the field you want to use on the eForm.

image

DropDown

Selecting this menu item places a dropdown box where the cursor is located.

image

The name and the entries in the dropdown list can be modified by right clicking on the field and selecting the Properties menu item.

When an item is selected in the dropdown list the text of the item will be stored in the form field on the server. If you choose to associate a value that is different than the text, it can be accomplished by adding a colon (“:”) followed by the desired value (e.g. August:8).

ITEM VALUE

VALUE STORED IN DATABASE

August

August

August:8

8

To set the default value for the dropdown list, specify the value of the item in the Default Value field of the eForm definition on the server (see the section named eForm Properties in this chapter for more information). To configure the dropdown field as a required field in the eForm Properties, forcing a user to choose an item in the list, ensure the first entry contains a NULL value. This is accomplished by having the item in the list followed by a colon. For example, add the item called “(Choose Rating):” to the top of the list. If the required flag is set for this field, the user must choose an item other than the “(Choose Rating)” entry before the form can be submitted.

Finally, you can assign a dropdown object to provide the values for the dropdown control. In eForm definition, in the field properties of the dropdown control, you can set the Link to Dropdown Object field to populate the dropdown control with the values in the selected Dropdown content object. See the section of this document entitled Dropdown List Content Object for more information.

image

Radio

Selecting this menu item places a single radio button in the document where the cursor is located. You can add multiple radio buttons to the form.

image

The text of the radio button can be modified by right clicking on the field and selecting the Properties menu item. Set the “Text” property in this popup to the text name you want displayed on the eForm. Set the “Name / Group” to the desired eForm field name. Each radio button you want added to the same group of controls should be given the same Name / Group. To add multiple radio button groups, use different Name / Group values for each collection of radio buttons.

image

The radio button input controls can be sized on the page by clicking and dragging the control to the desired size. To specify a value for a radio button that is different than the text, enter the radio button’s value in the “Value” field.

Date Field

Selecting this menu item inserts a form control that will display a date input control where the cursor is located. The name and size of the input box can be modified by right clicking on the input field and selecting the Properties menu item.

image

When the date control is clicked on in the eForm a popup date picker is displayed making the selection of a date easy for the user. Under the control properties window, you can configure whether the picker should be just a date picker, just a time picker, or a datetime picker.

image

When setting the value of a date picker control programmatically (for example, using a custom task), any time information included will be discarded. Note that such information will not be discarded when setting the value of a date/time picker.

Custom eForm Controls

The items in the lower portion of the eForms Controls dropdown displays the custom controls provided by the eForm Builder. This includes conditional control TAGs, special buttons, attachments, etc. The eForm definition supports these extended custom TAGs to allow extended HTML controls to be included on the form.

image

When using these menu items, the available parameters are also listed with the inserted tag to show the syntax of the command. These must be overwritten or removed with the appropriate parameter values.

Other Controls

This contains other form controls that can be used to display password fields, list controls, user/group pick lists folder pick list from the Content List, etc.

User / Group Pickers

image

User and Group pickers allow the eForm user to select users or groups from the server’s Active Directory.

image

The User or Group Picker’s options allow you to configure filter data as well as display data. The pickers can be displayed in the eForm as dropdowns, pop-ups, etc.

image

You can specify that only users in certain groups show up in the user picker by specifying a comma-separated list of groups in the “Only users in groups” field. If you type “AND” into the “Groups AND / OR” field, then only users belonging to all the specified groups will appear as options in the user picker controller. If you type “OR”, then users belonging to any of the specified groups will appear as options in the user picker control.

The “dropdown prompt” is the text that is shown before an option has been selected in the dropdown. Common values might be “<Select User>” or “<Select Group>”

The user picker will not list users who are members of groups specified in the “Ignore users in group” field, and the user picker will only list users returned by the Business Rule specified in the “Only users in rule” field (if that field is set).

Content Picker

image

The Content Picker control allows the user to select objects within the content list (e.g. processes, forms, etc.)

image

The Content Picker options allow you to set the control’s name, the type of object it can pick from the content list (document, folder, rule, KView, workflow, wfinstance, form, FormInstance, dropdown, DBconnection, Process Timeline, ProjectInstance, or Process), the extension the object must have, and the folder that the content picker starts in when the user clicks “Browse.”

image

Control Picker

image

The Control Picker is a dropdown list that contains the names of all the controls that are placed on the eForm. The Control Picker does not have a visual placeholder, and is placed on the page in Process Director's markup language as:

{ControlPicker:control_picker1, ControlType=, DropDownPrompt=}

When placed on the page without any modification, the control will appear as a dropdown control.

image

You can customize the prompt that appears in the dropdown by changing the DropDownPrompt attribute. For example, using the following markup:

{ControlPicker:control_picker1, ControlType=, DropDownPrompt="Select One"}

Will cause the control to appear as follows:

image

ListBox

image

Selecting this menu item inserts a form control that will display a multi-line list input control where the cursor is located. The form control looks as follows:

image

The ListBox control contains a list of checkboxes in a scrollable frame, where multiple checkboxes may or may not be selected. You can configure the name of the control, as well as its content, height, width, and formatting in its properties window. The height and width must beset using CSS syntax (e.g. 20px, 10%, 3em, etc.)

The contents of a ListBox can also be set using a dropdown object.

Slider

image

The Slider control allows you to select a numerical value using a slider.

image

In the slider’s property window, you can configure its size, minimum and maximum values, and whether or not the handles and tick marks are displayed. The SmallChange property determines how much the value of the slider changes when the adjacent arrows are clicked, and the LargeChange property determines how much the value of the slider changes when a position on the slider is clicked.

image

Rating

image

The Rating control allows the user to set a rating out of a possible number of stars.

image

The properties window for the Rating control allows you to configure the name of the rating control, the maximum number of stars, and whether the user can select half stars or not.

image

Lock Form Control

image

imageThe Lock Form control allows the user to see whether a form is locked and, if the control is configured to allow it, unlock it.

The properties window of the Lock Form control allows you to set the text shown to the user when the form is locked, and optionally allow the user to unlock the form. It can also be configured to periodically check to see whether the form has been locked after a number of seconds specified in the Polling Seconds property. To put the name of the user who locked the control into the Lock Text text, use the {FORM_LOCK_USER} system variable.

image

Calculation

image

The “Calculation” eForm control displays a number that is the result of a calculation involving any combination of the values of eForm controls, constants, and the multiplication, division, addition, and subtraction operators (“*”, “/”, “+”, and “-“ respectively).

In the eForm builder, the calculate control will look like the following, though only the number will be displayed to the eForm user:

image

The field’s properties include the actual algorithm, the name of the control, the CSS styles, and the Format String field, which determines what built in .NET style the value is displayed as (e.g. currency, double, etc.)

The algorithm can incorporate system variables and form fields. For example, to add the value of two form fields, use the following equation, substituting the appropriate control names:

{#FORM:fieldA} + {#FORM:fieldB}

image

Date Difference

image

The Date Difference control displays the number of days, hours, minutes, etc., between two dates. This control has no visual placeholder and is placed on the page in Process Director's markup language, with the following syntax:

{DateDiff:datediff1, Date1=, Date2=, Type=}

There are three attributes that must be provided to enable the control to display the proper value in the eForm:

  • Date1: This is the start date for calculating the date difference.
  • Date2: This is the end date for calculating the date difference.
  • Type: This is the time increment to be calculated. This can be any standard .Net time increment, such as "Days" "Hours", etc.

When properly configured, the Date Difference control will display a simple text number reflecting the value of the date difference. For example the following Date Difference control configuration:

{DateDiff:datediff5, Date1="1/1/2015", Date2="1/3/2015", Type="Hours"}

Will result in the control displaying "48" when the form runs.

In addition to using hard-coded dates as one of the date attributes, as shown in the example above, you can also use the values of date controls as the dates to use in calculation, using the syntax:

Date1={FORM:SubmittedOn}

In this example, the start date of the date difference calculation will be the value of a DatePicker control named "SubmittedOn".

Invite

image

The invite control allows a user to invite other users in Process Director to a task. The inviter can select to add the invitees to perform the task with the inviter, or to reassign the task from the inviter to the invitee.

The Invite control will appear as a user picker in the eForm, as shown below.

image

The properties tab contains a number of options to configure the eForm control.

image

PROPERTY

DESCRIPTION

Name

The name of the control

Text

Replaces the default text on the picker's button ("…").

Picker Type

Determines whether the user picker will show as a pop-up dialog box, or a dropdown control.

Only user in groups

The name of Process Director user groups from which the users will be displayed. This is useful to restrict the users that can be selected.

Ignore users in group

The name of Process Director user groups from which the users will not be displayed.

Dropdown Prompt

A brief prompt message that will appear in the dropdown, if the Dropdown picker type is selected.

HTML Height

The desired height of the control in pixels.

HTML Width

The desired width of the control in pixels.

Cancel Inviting User?

Checking this box will remove the task from the user's task list when others are invited.

Allow multiple users to be selected?

Allows more than one user to be invited.

Reassign the inviter?

Reassigns the task to the inviter.

Scheduler

image

The Scheduler control is part of the Process Director Scheduler Module (PDSM), which is used to launch processes (workflows or timelines) at pre-defined intervals within a specified window of time.

image

  • • Repeats: Choices are hourly, daily, monthly, or yearly.
  • • Repeat Every: Specify the frequency with which the process will be launched.
  • • Starts On: (Optional) The specified process will not be launched before this date/time.
  • • Ends On: (Optional) The specified process will not be launched after this date/time.
  • • Lead Time: (Optional) Tells the scheduler to launch the process a certain number of days prior to “Starts On” (effectively moves “Starts On” date up the indicated number of days).
  • • Business Days Only: When checked, only launch the process on business days.

Complete details about the scheduler component are available through the Scheduler Module guide.

HTML Code

image

The HTML Code control allows you to insert HTML into the eForm definition. This can be either normal HTML, or it can include JavaScript. Both of these also work with System Variables. So, to send an alert that greets the user, you could say:

<script>
Alert(“Hello {CURR_USER}”);
</script>

You can also place ASP.NET server –side controls in this tag. For example:

<asp:TextBox runat=”server” ID=”bpLogixTextBox” />

Server-side ASP.NET controls also act as normal BP Logix form fields, allowing you to reference them with System Variables and through Process Director. You can place an HTML control on an eForm, leave the Name property blank, then place the ASP.NET control markup in the HTMLString Property. Entering a Name for the HTML control will cause Process Director to treat it like a Process Director Control and override the ASP.NET control. Leaving the Name property blank will cause Process Director to take the HTML markup for the ASP.NET control, and display the ASP.NET control in the eForm. By wrapping a native ASP.NET control in an unnamed HTML control, Process Director supports the use of any native ASP.NET control on a eForm.

You can stylize your HTML with CSS, either in the tag you want to stylize or in a separate <style> tag.

<!-- You can do This: -->
<p style=”text-align: center;”>Text</p>
<!-- Or this: -->
<style type=”text/css”> p{
Text-align: center;
}
</style>

NOTE: If your inserted HTML includes { or } characters, you must leave the control Name blank. Otherwise the "{" and "}" characters will be interpreted as System Variables.

To use the ASP.NET controls, you must have the latest version of the BP Logix server install.

Datasource Picker

image

The Datasource Picker control displays a dropdown list of data sources that have been added to the Process Director installation. The control has no visual placeholder and is placed on the page in Process Director's markup language, with the following syntax:

{DSNPicker:dsn_picker7,DataSourceType=SQLServer|Oracle|SharePoint}

The DataSourceType attribute accepts one of three values to determine the database type from which to draw the data sources: SQL Server, Oracle, or SharePoint.

At runtime, the control appears as a standard dropdown list.

image

Category Picker

image

The Category Picker allows the user to select from one or more categories on Process Director.

image

The category properties can be accessed by double clicking the category control in MS Word. You can configure the name of the category picker, and the category that the user can start his search at when he clicks on the category picker. You can also allow the user to select multiple categories.

Attribute Picker

image

The attribute picker allows the user to select an attribute on Process Director.

image

The attribute properties can be accessed by double clicking the attribute control. You can configure the control’s name, and the category that the user will start searching in when he clicks the attribute picker on the eForm.

Radio Button List

image

The Radio Button List control returns a single value from a list of radio buttons. The control has no visual placeholder and is placed on the page in Process Director's markup language, with the following syntax:

{RadioList:radio_list8, RepeatDirection=Horizontal|Vertical, item=, item=}

The RepeatDirection attribute enables you to select whether you wish the radio buttons to be arrayed horizontally across the page, or vertically in a single column. The Item attributes enable you to add as many items as needed to the list. Examples of each RepeatDirection attribute are shown below.

One item to note in the examples is that one radio button option uses the term "3rd". Microsoft Word will, by default, place the "rd" in superscript, so that it appears as "3rd". You should eliminate the superscripting, and use standard text rather than superscript to avoid formatting problems.

The return value for the selected radio button will be the literal text of the option item.

Examples

Syntax (Horizontal)

{RadioList:radio_list8, RepeatDirection=Horizontal, item="Item One", item="Item 2", item="The 3rd Item"}

Run-Time Appearance

image

Syntax (Vertical)

{RadioList:radio_list8, RepeatDirection=Vertical, item="Item One", item="Item 2", item="The 3rd Item"}

Run-Time Appearance

image

Form Error String Location

image

This eForm control is used to identify the area(s) where error messages are displayed on the eForm. If this control is not present on an eForm, then the error messages are placed at the top and bottom of the form. This control has no visual placeholder, and is placed on the form using Process Director's markup syntax as:

{FormErrorStrings}

Form Info String Location

This eForm control is used to identify the area(s) where informational messages are displayed on the eForm. If this control is not present on an eForm, then the informational messages are placed at the top and bottom of the form. This control has no visual placeholder, and is placed on the form using Process Director's markup syntax as:

{FormInfoStrings}

Knowledge View Control

image

Knowledge view controls allow you to display a knowledge view within an eForm, or within a popup window.

image

The properties window allows you to configure the name of the control, as well as its width and its height (either as percentage points or pixels). The “Type” dropdown can be set to Iframe or Pop-Up. If “Type” is set to Iframe, the Knowledge View will display inline, on the eForm. If it is set to Pop-Up, the Knowledge View will be displayed in a pop-up window. You can also send QueryString parameters to the Knowledge View.

image

To specify which Knowledge View this control will display, in the eForm “Properties” page on Process Director, set the default value of this control to the content item for the Knowledge View you want displayed.

QueryString Parameters can also be set in the QueryString Parms property, as described in the KView control section of this document.

image

Show Report Control

image

The Show Report control displays a report in an eForm. The Show Report control can display a report in a variety of ways, configurable in the control’s properties.

image

The properties window allows the user to configure the name of the control, the text the Show Report button displays, and the height and width of the report. It also allows the user to pass QueryString parameters to the report, configuring the data it returns. Separate parameters should be separated by new lines, using the [variable name] = [value] format to specify parameters and their values.

image

The Type dropdown allows the report to be displayed in the eForm in three different ways. The report can be displayed in an iframe in the eForm, as a popup, or as an image embedded in the eForm. The image is static, but the data it returns can still be configured using QueryString parameters.

image

Label Control

image

The Label control adds a piece of text to the eForm that can be dynamically changed by accessing it via the control name.

image

The Label configuration properties can be accessed by double clicking the label control in the form builder. You can configure the label’s name, its default text, and its CSS styling.

Hotlink

image

The hotlink control creates a link to a specified URL. These are often placed in emails to link the user to the task he needs to complete. As such, one will usually set the hotlink’s URL dynamically using System Variables.

image

In the hotlink control’s properties window, you can set the name of the hotlink, the text displayed to the user, the URL the user is directed to, the CSS style of the link, and the JavaScript function triggered when the user clicks on the link. You can optionally make the hotlink open in a new window.

image

The “Text” field sets the text displayed on the form.

The “URL” field sets the URL to which the hotlink control will link. The “Style” field determines CSS styling for the link.

The “OnClientClick” field specifies JavaScript code to be executed when the user clicks on the link. It must be encased in quotation marks.

Audit Button

image

The Audit Button control allows the user to view a history of the controls whose values have changed on the eForm, so long as the “Audit eForm Changes” checkbox is checked on the eForm properties tab in Process Director.

image

The Audit Button’s properties can be accessed by double clicking the button in the form builder.

image

You can configure the control’s name, and the text displayed on the button. Using the Control Name, Step Name, and Activity Name fields, you can also filter the audit history to only display eForm changes relevant to the specified controls, activities, and steps.

Image Control

image

The Image Control inserts an image at a specified URL into the eForm.

image

The Image Control properties can be accessed by double clicking on the control in the eForm builder. The properties allow you to configure the name of the image control. The Image URL field specifies the URL at which the image can be found. If text is entered in the URL field, the image will redirect the user to that URL if the image is clicked on. You can check the checkbox to open the link in a new window.

The image can also be stylized using CSS, and its height and width can be set in pixels.

Manage Process Users

image

This system variable allows a user to delegate tasks to other users, remove users from tasks, and perform other process management functions without going to the process’ administrator’s page.

The “Manage Users” tab of the properties window for this control allows you to set the name, button text, and group name for the Manage Users control. You can also specify what features the eForm user is allowed to access. Through the Step Name and Activity Name textboxes, you can make it such that the reassign button only appears for a specific set of activities or steps.

Checking the “Start Pending Users Only” checkbox makes it such that, if the step is restarted, only users who have not completed the task in this workflow instance will be asked to complete it.

image

The Button Properties tab allows you to configure the URL of the button image and the style of the button, as well as the behavior upon clicking the button.

Email Data

For information on this control, see the section of this document entitled EmailData Control.

Email Complete Link

For information on this control, see the section of this document entitled Complete Links in an Email.

Comment Start / Comment End

image

The Comment Start and Comment End controls are used to define an area in the eForm to act as a comment. A commented area will only display when building the eForm in MS Word: any controls or text put inside the commented area will not affect the eForm once it is deployed.

image

Signatures / Comments

Process Director provides controls to show the routing the process has gone through as different users have been assigned tasks, as well as controls that enable participants to make comments as the process cycles through different users.

Routing Slip

image

Routing slips show the path that an eForm has taken through a workflow or process. They have a list of the users’ names and signatures. An optional signature image file can be associated with a user ID causing it to be displayed next to their name in the routing slip when they complete their task. You can upload a signature for each user in the User Administration section of the system. It is recommended that a “.gif” file be used with a transparent background so the image can be displayed on web pages with different color backgrounds. If a signature file is found it is automatically displayed anytime the Routing Slip is viewed. Below is an example of how an actual routing slip will appear.

image

To add a user’s signature to the database, see the User Administration portion of this guide. The routing slip will be represented as an image of a sample routing slip when you are building the eForm.

Through the routing slip’s options, you can change the name of the routing slip, as well as configure what fields appear on the routing slip. If you specify text in the “Only Result” textbox, then only steps whose results match the text in the “Only Result” textbox will display on the routing slip.

image

Signature Comments

image

Signature Comments are fields that prompt the end user to enter a comment before he can complete the eForm. Signature Comments are not necessarily required for completion, even when the control is added.

Signature Comments will appear like this in the eForm builder:

image

You can configure the control’s name, default text, and styles in the control’s properties.

image

Signature Control

image

The signature control allows the user to draw his signature on an eForm using a mouse or stylus. In the signature properties, you can configure the name of the control, the prompt for the control, the color of the signature, the color of the background, and the width of the electronic pen.

image

The ESIGN Act of 2000 guarantees that a signature stored via this control is legally binding: according to the act, “a contract … cannot be denied legal effect, validity, or enforceability solely because an electronic signature or electronic record was used in its formation.” (ESIGN Act Section 106(2))

Topaz Signature Control

image

The Topaz signature control is a special signature control designed to be used with electronic signature pads and signature software produced by Topaz Systems. For users of Topaz Systems components, this signature control would be used in lieu of the regular Signature control.

Comment Log

image

A comment log is an eForm control where users of the eForm can add text of any sort, which will be displayed to all subsequent users of the eForm. Comment logs also keep track of and display which users wrote what.

A comment log will look like this in the eForm builder:

image

In this control’s properties, you can configure the Comment Log’s group name, the control name, the default text, and the width of the log.

image

Sections

image

A Section control is a type of control that you use to organize, show, or hide controls on a form. A section actually consists of two separate controls: the Section and Section End. Every Section control must have a Section End. Every control that is placed between the Section and Section End controls become part of that section. You can also nest sections, meaning that you can place a section inside of a section.

image

There are two kinds of sections: normal sections and embedded sections. Embedded sections are used to gather various controls on an eForm into one group, making it easier to set properties common throughout the group. Embedded sections are not visible to the user. Normal Sections are visible to the user, and are collapsible and expandable.

All section controls automatically include HTML anchors using the syntax:

<a name="SECTIONNAME"></a>

The anchor has the same name as that of the Section control. Form designers can give their users the ability to scroll down to any section by providing a link (using the Hotlink control) with the URL:

#SECTIONNAME

Simply replace "SECTIONNAME" with the actual name of the Section control. You may find the ability to link to document sections useful when designing long forms.

Section / Section End

Sections with Titles will look like this on your word document:

image

In the section’s properties, you can edit the name of the section, the title of the section (which is visible to the user), whether the section can be collapsed or expanded, whether it is expanded by default or not, and the image URLs for the collapse / expand buttons. The default images are just “+” and “-“ buttons.

image

Checking the “Floating?” checkbox will make the section, when expanded, display on top of other sections.

image

Expanding/Contracting Sections

In addition to the regular field settings for visibility or enabling the control, Sections can also expand or collapse. The Section control's Value property determines whether control is expanded or collapsed. Setting the value to "0" will collapse the section, while setting the value to "1" will expand the section. The default value is "1".

You can set the value in the eForm control's at design time by either:

  1. Checking or unchecking the "Expanded?" property's check box in the Section control's Properties dialog box in the eForm template, or
  2. Setting the Default Value property in for the eForm field's properties dialog box in the eForm Controls Tab of the eForm Definition.

You can also set the value at run time by using the Set Form Data Custom Task in the Custom task Event Mapping Tab of the eForm Definition to change the Value based on some condition you desire.

Embedded Section / Embedded Section End

Embedded Sections are somewhat simpler. They’re represented in Microsoft Word as large square brackets, though they’re invisible to the eForm’s user.

image

You can edit the section’s name in the properties tab for the section.

Client Section / Client Section End

image

The Client Section control is generated through JavaScript in the browser client, unlike the normal Section control, which is rendered as a server control through ASP.NET. Because the client control is generated on the client, the control can be expanded or contracted without having to perform a postback of the form to the server. The Client Section control, therefore, provides faster performance than the regular Section control. On the other hand, the Client Section control cannot trigger any rules or logic, nor can it support any visibility or enable/disable rules like a regular Section control.

The Control Picker does not have a visual placeholder, and is placed on the page in Process Director's markup language as:

{ClientSection:client_section2, Text=xyz, InitialExpand=Yes|No, ExpandDefault=Yes|No}

This is content for the Client Section

{ClientSectionEnd}

The Client Section control has three attributes:

  • Text: The text that appears in the title bar of the section.
  • InitialExpand: Determines whether the control is displayed in expanded mode when initially displayed. Setting this attribute overrides the ExpandDefault attribute. To allow the ExpandDefault to determine whether the section is expanded, do not set this attribute.
  • ExpandDefault: Determines whether the section will be expanded by default. This will determine the initial state of the control when the form is opened for the first time in a browser session. After the initial display, the Client Section's expanded state is stored in a session cookie. If the form is opened again during the same browser session, the Client Section's expanded state will be controlled by the session cookie. In other words, if the Client Section was not expanded when the form was last closed, it will not be expanded if the form is re-opened during the same browser section.

Tab Strips

image

Tab strips allow you to separate form content into different tabs, thus conserving space. Each tab can be viewed individually. To declare the start of a tab strip, use the Tab Strip control.

image

The properties window allows you to configure the number, text, and IDs of tabs.

image

Everything inside the Tab Strip control must be part of a tab. To declare the start of a tab, use the Tab Content Control.

image

EForm content goes between the Tab Content and Tab Content End controls. The Tab Content and Tab End controls define the start and end of a tab.

image

The ID of the TabStrip Content control, configured in the properties, must match the ID of one of the tabs defined in the Tab Strip properties.

image

Titled and Embedded Sections are ended with an “end section” or “end embedded section” control, respectively.

Arrays

The eForm builder supports creating lists of input fields. An “array” tag can be used to surround a group of information or input fields on the eForm. This allows the information to be repeated dynamically when the eForm is displayed to the user. This can be used when a form has a list of items.

Repeating Rows (Arrays/Lists)

The array control allows rows of items to be dynamically increased or decreased using an array tag. You can allow the user to manually add or remove a row from an array by adding the “Add Row to Array” and “Remove Row from Array” in your array.

The Row Number control simply displays the row number (starting with row #1).

image

Using the array controls, you will notice that red brackets mark the beginning and end of each array.

image

You can add a definition for the rows of the array by adding eForm controls within the brackets.

image

The sum control displays the sum of all of the elements in a column of the array.

image

To configure a sum control, open up the properties window by double clicking on the control inside the eForm builder.

image

In the “Column” field, enter the name of the control in the column you would like to sum.

The Sort Array control gives the user a button to sort the array alphabetically. The array can be sorted by three columns, in order of preference. This means that, if two elements in the primary column are the same, that those rows will be sorted according to the secondary column, and so on.

image

To configure the Sort Array control, open the properties window by double clicking the control.

image

The Sort Array tab allows you to configure how the control sorts. You can define the text of the control button, its name, and the columns it uses as keys to sort the array. You can also have the control sort the array in descending order.

image

The Button Properties tab allows you to configure the button for the Sort Array control. You can provide the URL of an image to use for the button, and style it via CSS. Upon clicking the button, you can ask the user to confirm that he wants to sort the array. You can also specify a JavaScript function to be run when the user clicks on the button.

Buttons

These controls enable adding various types of buttons to the eForm. This includes buttons for printing, custom event buttons, and completing the eForm.

image

From the Button’s Properties window you can configure the button’s name, text, icon image, etc. The “OnClientClick” field calls the JavaScript onclick () function using the text you enter as a parameter.

Button Controls

There are four built-in button controls: the Button Area, the Print eForm button, the Save eForm Button, and the Cancel eForm / Workflow / Process Timeline button.

The Button Area adds an Okay and Cancel button the bottom of an eForm, allowing the user to submit the eForm.

image

The text and confirmation text on the various buttons in the button area is customizable via the button area’s properties. You can configure whether the Button Area should contain and OK or Cancel button, and you can configure whether it should display buttons allowing the user to complete the task and move on with the workflow or Process Timeline.

If the “Assign task to first user to accept” checkbox is checked on this eForm instance’s step or activity definition, the button area will first display a button allowing the user to accept the task. The “Accept Text field in the properties window allows you to set the text of this button, and the Accept Confirm text allows you to set the text of a dialog box asking the user to confirm his decision. Once the user has accepted the task, the button area will display as it usually does.

image

The Print eForm button does what it says on the tin: it allows the user to print the eForm. The Save eForm button saves the eForm’s state, including the values of its fields, without submitting the eForm. This allows the user to complete the form at a later time.

The Cancel eForm / Workflow / Process Timeline button allows users to cancel the process that the user is in.

Attachments

These entries allow documents to be attached to an eForm (as a reference or as part of a workflow package). Documents that are references or part of a workflow package can also be embedded and viewed on the eForm or displayed with hotlinks using these various controls.

Attach Objects

image

You can allow the user to attach a document by inserting an “Attach Objects” control. An Attach Objects button appears as this in MS Word.

image

Double clicking the control allows you to access and configure its properties. You can configure the name field, as well as the text that appears on the button. Using the Attach Type and Object Type dropdowns, you can restrict what types of items the attach control can upload. The Group Name field specifies the group that the attachment will be assigned to when uploaded.

image

The Clipboard Image Name is a name assigned to an image that is copied to Process Director via the clipboard (rather than uploaded from a file system). You can check the “Single File Upload?” box to allow users to upload only one file at a time.

As of Apple iOS 6.2, when clicking on the attach button in Safari or Chrome, iOS will prompt the user to either take a picture or select one to attach from his photo library.

In addition, the attach objects control also allows you to call JavaScript client behaviors. You can specify the JavaScript call you'd like to make by entering it in the OnClientClick property of the control.

image

eForm Definition

Additional properties are available for the Attach Objects control in the eForm Controls properties Tab of the form definition. Opening the control's property in the eForm Controls tab will display the properties dialog box to access the additional properties.

image

The relevant properties are:

PROPERTY

DESCRIPTION

Min

The minimum allowable file size for the attachment.

Max

The maximum allowable file size for the attachment.

Show Attached objects

A Show Attached Objects field appears like this in MS Word.

image

To show objects that are attached, you use the “Show Attached Objects” control. By default, this control does not display the attached object in the browser, but just adds a link to be able to download or view it. To show it within the browser, go to the control’s Properties window and activate the “View Inline?” checkbox.

image

If you are displaying Process Timeline/workflow/process references, ShowAttach will not display the current form despite the fact that it is a Process Timeline/workflow/process reference.

Process Director versions 3.45 and higher have the ability to show thumbnails in the ShowAttach control by selecting the Show Thumbnail check box. Thumbnail display is available for the following file types"

  • JPG/GIF/PNG/TIF/BMP
  • DOC/DOCX
  • XLS/XLSX
  • PPT/PPTX
  • TXT/CSV
  • PDF

For thumbnails to display, you must also set the EnableThumbnails custom variable to "True" in the Customization File.

Also, for Process Director v3.45 and higher, when selecting the "Show Edit?" option Process Director will no longer display the History tab in the popup. If a user requires access to the history of a document from the eForm, select "Show History?" property to display a link on the form that opens a popup to the document history.

  • Was this article helpful?