Designing data capture and presentation

Assets for capturing and presenting data
About captured data
About action profiles
Modifying and creating action profiles
- Creating minimal processes for action profiles
Action profile services at run time
About prepare data services
About render services
About submit services

Involve people in processes to capture information from them, present information to them, or both. The following aspects of a LiveCycle application define the interface that enables users to provide or consume information:

Assets:: Assets, such as forms or Guides, that are presented to users.
Data:: Information that is used to populate the fields of assets that are presented to users.
Action profiles:: A set of services that defines the final form in which assets and data are presented to users.
When you create tasks, configure them to use assets, data, and action profiles. Before creating tasks, you must understand the types of assets that can be used to present data to users. You must also understand the different services that are used to process data and present it to users. With this information, you can decide whether to change default action profiles or create new ones.

Assets for capturing and presenting data

You can use different types of assets for capturing data from users and displaying data to users. Generally, these assets contain fields for displaying items of data. LiveCycle supports Guides and several different types of forms and files for use in processes:

Guide:

A user interface based on Adobe Flash technology that steps users through the data-entry experience.

Adobe PDF form:

A PDF form that is designed using Designer.

Adobe XML form:

An XDP file that is designed using Designer. Adobe XML forms use the Forms service to render Adobe XML forms to HTML or PDF.

Acrobat form:

A PDF form that is created using Acrobat (or a similar tool).

PDF document:

PDF documents can be presented to users for reviewing information.

Flex application:

A SWF file that is created using Adobe Flex Builder.

Third-party file types can also be presented to users. Users need the client software to open the file. For example, users need Microsoft Word installed to open Word documents.

Use the New Form wizard to create Adobe PDF forms and Adobe XML forms. The wizard configures the form automatically for use in processes and opens the form in Designer for developing it. (See Creating Forms.)

Use the New Guide wizard to create Guides and use the Guide Design editor to further develop it. See (Deprecated) Creating Guides.)

About captured data

Data and assets appear as a single entity when they are presented to users. However, they can exist separately before and after users see them:

Before users are presented with data, it is merged with an asset.
When users submit tasks, the process stores the submitted data in variables.

When captured data is stored in a variable, you can pass the data from user to user at different steps in a process. You can modify all or some of the data as required, or extract values from the data to use for decision making. Storing data also enables you to archive it as necessary.

The separation of data and assets also enables you to use the same data with different forms or Guides. Furthermore, when maintaining applications in production, you can update the design of the form or Guide without altering the process or interrupting processes that are executing.

Data formats

Forms and Guides are compatible with data of different formats. The format determines the type of variables to use to store the data that is captured with them.

Media	Format of data	Variable type to use
Guide	XML data (in text format)	XML variable
Adobe PDF form	Either PDF documents (in binary format) or XML data (in text format).	Depends on the format of the submitted data: Use document variables to store submitted PDF documents. Use XML variables to store submitted XML data. Configure the variable to store XDP data.
Adobe XML form	Either PDF documents (in binary format) or XML data (in text format).	Depends on the format of the submitted data: Use document variables to store submitted PDF documents. Use XML variables to store submitted XML data. Configure the variable to store XDP data.
Acrobat form	Either PDF documents (in binary format) or data in text format (FDF, XFDF, or HTML) Note: FDF, XFDF, and HTML data from Acrobat forms cannot be used directly with Adobe XML or Adobe PDF forms.	Depends on the format of the submitted data: Use document variables to store submitted PDF documents. Use XML variables to store submitted FDF, XFDF, or HTML data.
Flex application	XML data (in text format)	XML variable
PDF document	PDF documents (in binary format)	document variable

Typically, forms are designed to submit PDF documents when they must preserve a digital signature on the form.

To specify the variable that stores submitted data, configure the Workspace start point, Assign Task operation, or an Assign Multiple Task operation.

XDP form data

Adobe XML forms and Adobe PDF forms can submit field data in XML data package (XDP) format. XDP is XML that uses a particular structure and specific namespaces. The structure and use of namespaces are required when the data is used with XFA applications, such as the Forms service.

XML data that is retrieved from forms are enveloped with xdp/datasets/data elements. For example, the following XDP is field data that is submitted from an XDP form. MortgateForm is the root element of the form data:

<xdp:xdp xmlns:xdp="http://ns.adobe.com/xdp/"> 
    <xfa:datasets xmlns:xfa="http://www.xfa.org/schema/xfa-data/1.0/"> 
        <xfa:data> 
            <MortgageForm> 
            ... 
        </xfa:data> 
</xdp:xdp>

Configuring XML variables for XDP data

You can configure XML variables so that they store XML data as XDP. The Save Data As XDP property is useful when saving XDP data for forms. For example, data that is submitted from a Guide is in XML data. To populate an XDP form with the same data, you need to add XDP-specific elements to the XML. To do so, you copy the XML data to an xml variable that is configured for XDP data.

Saving data s XDP provides the following benefits:

You do not need to manually add elements to make the XML valid XDP. The variable is initialized with the XML elements, including namespaces, that XDP requires.
You do not need to use XDP namespaces in XPath expressions when working with data in the XML variable. XPath expressions become namespace-unaware, regardless of any namespaces that are registered in the process.
You can see the XDP nodes in XPath Builder so that the XPath expressions that you create use the correct path.

Saving XML as XDP data

To save XML data in an XML variable that is configured for XDP data, use XPath expressions that include the XDP-specific elements. For example, the xml variable named xmlVar contains the following XML code:

<root> 
    <first_child>This is the first child of root</first_child> 
</root>

A process needs to store the XML data in a variable named xdpVar, an xml variable that is configured for XDP data. The following XPath expressions are used with the Set Value service to save the XML in the xdpVar variable using valid XDP format:

/process_data/xdpVar/xdp/datasets/data = /process_data/xmlVar

The xdpVar variable now contains the following XML:

<xdp:xdp xmlns:xdp="http://ns.adobe.com/xdp/"> 
    <xfa:datasets xmlns:xfa="http://www.xfa.org/schema/xfa-data/1.0/"> 
        <xfa:data> 
            <first_child>This is the first child of root</first_child> 
        </xfa:data> 
</xdp:xdp>

Note: xdpVar does not include the root element from xmlVar. The following expressions create the root element in xdpVar: /process_data/xdpVar/xdp/datasets/data/root = /process_data/xmlVar

Overwriting the XDP elements

Saving XML data directly in an xml variable that is configured for XDP data overwrites the XDP elements that the variable is initialized with. The following XPath expressions involve the xml variables of the previous examples:

/process_data/xdpVar = /process_data/xmlVar

The following XML code is the resulting content of the xdpVar variable:

<root> 
    <first_child>This is the first child of root</first_child> 
</root>

Configure an XML variable to save XDP data:

In the Variables view, double-click the xml variable to open the Variable dialog box.
Select Store Form Data As XDP, and click OK.

Displaying the xml data structure in XPath Builder

Seeing the data structure of xml variables in XPath builder is useful when creating XPath expressions. (See XPath Builder (Process Properties).)

To display the structure of xml variables, include the XML schema in the xml variable. Different types of assets can be imported from applications into XML variables to obtain the schema:

An XML schema file.
An XDP file that has an embedded XML schema.
An Adobe data model. The schema is derived from the model.

Note: Assets must be checked in before you importing them.

Schemas are based on the XML Schema Definition (XSD) defined at http://www.w3.org/2001/XMLSchema.

Specifying the root entity

After you import an asset, you can specify which entity in the schema to use as root. The root is important for xml variables that are configured for storing XDP data. When the root node is specified, the initial value of the variable includes an element that represents the root node. For example, an xml variable has the following properties:

The Store Form Data As XDP option is selected. When the option is selected, XML variables ignore prefixes registered for namespaces and XPath expresssions do not require the prefix. When deselected, you must use the registered prefixes for namespaces in the XPath expression.
An XDP file is imported so that the root node is called MortgageApp.

The xml variable is initialized with the following XML:

<xdp:xdp xmlns:xdp="http://ns.adobe.com/xdp/"> 
    <xfa:datasets xmlns:xfa="http://www.xfa.org/schema/xfa-data/1.0/"> 
        <xfa:data> 
            <MortgageApp/> 
        </xfa:data> 
    </xfa:datasets> 
</xdp:xdp>

Note: When you import an XDP file, the file does not need to include an embedded schema to identify the root node. Workbench can determine the root node of XDP files without the schema.

Import an asset:

In the Variables view, double-click an XML variable to open the Variable dialog box.
Click Import Asset.
Select the asset to import and click OK.
In the Root Entity list, select the root node.
In the Variable dialog box, click OK.

About action profiles

Action profiles are used to specify how the assets and data are presented to users. They also specify how data that users submit is processed before being stored in process variables.

Action profiles define a set of services:

Prepare data service:: (Optional) Alters the data that is provided for use with the asset. This service is also used for prepopulating forms and Guides.
Render service:: Renders the data and the asset before it is sent to the user.
Submit service:: Processes the data that the user submits to the LiveCycle Server.
When PDF forms are used, action profiles can also specify how to extend the capabilities of the PDF when opened in Adobe Reader. For example, Adobe Reader users require extended PDF forms to submit them. (See Reader Extensions .)

Default action profiles

Each form and Guide includes a default action profile that is configured according to the type of the asset, such as a PDF or XDP file. The default action profile is also configured according to information that is provided in the New Form wizard and the New Guide wizard if they were used to create the asset.

You can create new action profiles or modify the default action profile if necessary. However, the default action profile is adequate for most use cases.

To specify the action profile to use for an asset, configure the Workspace start point, Assign Task operation, or Assign Multiple Tasks operation.

Modifying and creating action profiles

Modify or create an action profile to affect the way the associated asset and data are displayed to the user. Most often, modified or new action profiles are required in the following situations:

The functionality of a prepare data service is required. (Default action profiles do not include a prepare data service).
An asset is presented in different ways at different parts of the process.

For example, a form is used with several Assign Task operations of a process. Only the first operation requires that a prepare data service is executed. Therefore, the asset requires one action profile that uses a prepare data service, and another action profile that does not.

In addition to the prepare data, render, and submit services, you can specify how to extend PDF forms for Adobe Reader users. To use the Reader Extensions service, specify the Reader Extensions Rights credential to use to extend PDF forms. PDF forms are extended according to the properties of the credential that you select. The credential must already be added to Trust Store. For more information, see Managing local credentials for more information.

The dialog box that you use to modify and create action profiles enables you to create minimal prepare data, render, and submit processes. You can further develop the processes at a later time.

Modify or create an action profile:

In the Applications view, right-click the asset and click Manage Action Profiles.
Select an existing action profile or create one:
- To modify an action profile, click the name of the action profile in the list.
- To create an action profile, click the plus sign button .
In the Name box, type a name. The name appears in the list of available action profiles in the properties of the Workspace start point or User service operations.
In the Prepare Data box, select, remove, or create a prepare data process:
- To select a process, click the Select button .
- To remove the selected process, click the Clear button.
- To create a process, click the New Process button . (See About prepare data services.)
If you are using default render services, in the Render Type area, select the format to present to users:
- For Guides, select Form Guide and select the variation to use.
- For Adobe PDF forms or Acrobat forms, select PDF.
- For Adobe XML forms, select either HTML or PDF, depending on how you want to transform the XDP file.
If you selected PDF and you want to extend the form for Adobe Reader users, select Reader Extend, and then select the credential to use.
Check the Form Will Be Submitted Offline As A PDF checkbox. This enables users to submit the form offline using a supported version of either Adobe Reader or Adobe Acrobat without having to submit it by logging in to Workspace.
To specify a render process to use other than the default, click the Select button to select the process, or click the New Process button to create a render process. (See About render services.)
To specify a submit process to use other than the default, click the Select button to select the process, or click the New Process button to create a submit process. (See About submit services.)

To restore default values for all properties except the name and description, click Restore Default.
Click OK.

Remove an action profile:

Select the action profile and click the minus sign button .

Creating minimal processes for action profiles

When you create or change an action profile, you can create new processes to use for the prepare data service, render service, and submit service. When you create these processes, you can finalize the configuration of the action profile without having to close the Manage Action Profiles dialog box. When you finish configuring the action profile, you can close the Manage Action Profiles dialog box and then complete the development of the new processes.

New processes are given a default name and location with default variables that are required. You can add more variables if you need them.

Prepare data process properties

Process name:

The default value is Asset_NamePrepareData, where Asset_Name is the name of the asset that the action profile is associated with. You can change the name.

Location:

The default location is the location of the asset that the action profile is associated with. You can change the location.

Process Variables:

Two variables are created by default:

taskContext is an input variable of type TaskContext. This variable holds information about the task that is using the asset and data, including the data to manipulate before rendering.
xmlPrepareData is an output variable of type xml. This variable is used to return the data after it is manipulated.

Render process properties

Process name:

The default value is Asset_NameRender, where Asset_Name is the name of the asset that the action profile is associated with. You can change the name.

Location:

The default location is the location of the asset that the action profile is associated with. You can change the location.

Process Variables:

The following variables are created by default:

taskContext is an input variable of type TaskContext. This variable holds information about the task that is using the asset and data, including the asset and data to render.
applyRE is an input variable of type boolean that indicates whether to use the Reader Extensions service to apply usage rights for Adobe Reader users. The default value is false, which indicates no usage rights are applied. You can change the name and data type or delete this variable.
credentialAlias is an input variable of type string that is used to specify the alias of the credential to use for applying usage rights. This property requires a value only if applyRE is true. You can change the name and data type or delete this variable.
outFormDoc is an output variable of type document. This variable is used to return the rendered asset.
runtimeMap is an output variable of type map.

Submit process properties

Process name:

The default value is Asset_NameSubmit, where Asset_Name is the name of the asset that the action profile is associated with. You can change the name.

Location:

The default location is the location of the asset that the action profile is associated with. You can change the location.

Process Variables:

The following variables are created by default:

taskContext is an input variable of type TaskContext. This variable holds information about the task that is using the asset and data, including the asset and data that is submitted. You can change the name.
applyRE is an input variable of type boolean that indicates whether to use the Reader Extensions service to apply usage rights for Adobe Reader users. The default value is false, which indicates no usage rights are applied. You can change the name and data type or delete this variable.
credentialAlias is an input variable of type string that is used to specify the alias of the credential to use for applying usage rights. This property requires a value only if applyRE is true. You can change the name and data type or delete this variable.
outputDocument is an output variable of type document. This variable is used to return the rendered asset. You can change the name.
runtimeMap is an output variable of type map.

Create a prepare data, render, or submit process

On the Manage Action Profiles dialog box, click the create process icon for the type of process to create:
- To create a prepare data process, click the icon next to the Prepare Data Process box.
- To create a render process, click the icon next to the Render Process box.
- To create a submit process, click the icon next to the Submit Process box.
(Optional) To replace the default process name, type a new name in the Process Name box.
(Optional) To specify a different location than the default location, click the folder icon and select the location to save the process.
To add a variable, click the plus sign (+) icon .
To change the name of a variable, click the variable name and type a new name.
To change the data type of a variable, click the data type and select a different data type.
To remove a variable, select the variable and click the minus sign (-) icon .

Action profile services at run time

The services of an action profile are started when a user opens and submits a task. Users open tasks in Workspace in the following situations:

They open a task from the Start Process page of Workspace. The Workspace start point for the process is executed to present the form or Guide.

View full size graphic
They open a form or Guide from their To Do list. The User service dictates which tasks appear in the To Do list.

View full size graphic
Similarly, the services are started when the LiveCycle Server sends a form to a user using email. In this situation, the user opens and submits the form by using a client application such as Adobe Reader.

For information about creating forms for process management, see “Preparing Forms for LiveCycle Process Management” in Designer Help.

About prepare data services

Prepare data services can be used to alter data before it is merged with an asset. Typically, prepare data services are that of an activated process.

For example, you are creating a process that prepopulates a form with a user’s name, employee number, and other organizational information. You create a process that performs an LDAP query to retrieve the information. The process structures the data so that it is compatible with the form layout.

Because the way that data must be prepared is specific to your application or business process, create prepare data processes as you need them. LiveCycle does not provide default prepare data services.

If you create a prepare data process, it must include the following variables:

A document or xml variable that has the Output property selected. The data in this variable is passed to the render service after the prepare data service is complete.
A TaskContext variable that has the Input property selected. This variable contains information about the task, such as the identification of the user who is assigned the task.

You can also include a map variable as output. The contents of the map are appended to the runtimeMap data item of the TaskContext value. If you are also using a custom render service, that service can access the content of the map.

Prepare data processes can include any number of other input variables as you require. The values for the input variables are specified in the properties of the Workspace start point, Assign Task operation, or Assign Multiple Tasks operation.

Advantages over subprocesses

You can use a subprocess to alter data before it is merged with the asset. The subprocess is started before the Assign Task or Assign Multiple Tasks operations are executed. However, no information about the task is available to the subprocess.

The prepare data service is started after the task is created so that the TaskContext value can be passed to the prepare data service. The information in the TaskContext value is useful for altering data based on the context of the task.

About render services

Render services merge data with forms or Guides before presenting them to users. For Adobe XML forms, render services also transform the form to a specific format, such as PDF or HTML. Typically, render services are services of an activated process.

Process Management provides several default render processes that are deployed on the LiveCycle Server. The default action profiles of the different types of assets use these render processes.

It is unlikely that you need to alter the render processes that Process Management provides or create custom render processes. However, if you must create custom render processes, they must include the following variables:

A TaskContext variable that has the Input property selected.
A document variable that has the Output property selected. The data in this variable must contain the rendered form or Guide when the service is complete.

Render processes can include as many input variables as you require. The values to use for the input variables are specified in the properties of the Workspace start point, Assign Task operation, or Assign Multiple Tasks operation.

Rendering to HTML and sending email

When Workspace users are sent email notifications about new tasks, the task form can be attached to the email for filling offline. However, only PDF forms can be attached. If you are rendering forms to HTML for Workspace, the following task configurations cause a PDF to be sent to the user in email:

The task is configured to send email notifications. However, if the task is only configured to send email notifications, then a link to the task in Workspace is sent out and not the PDF.
The form data is included as a task attachment.

The form also requires specific configurations. The service that performs rendering must determine whether to render to HTML or to PDF. When forms are attached to email notification messages, the LiveCycle Server adds the following text to the targetURL field on the form:

mailto: [server address]

where [server address] is the email address that the LiveCycle Server uses.

If you create a render service, it must parse the content of the targetURL field to see if it contains the mailto: text:

If the field contains the text, the service renders the form as PDF.
If the field does not contain the text, the service renders the form as HTML. The form is not sent as a PDF attachment with the email notification.

About submit services

Submit services are used to process data after users submit their form or Guide. After the submit service processes the data, the data is stored in a process variable. Typically, submit services are services of an activated process.

Process Management provides several submit processes that are deployed on the LiveCycle Server. The default action profiles of the different types of assets use these submit processes.

It is unlikely that you need to alter the submit processes that Process Management provides or create custom submit processes. However, if you do create custom submit processes, they must include the following variables:

A TaskContext variable that has the Input property selected.
A document variable that has the Output property selected. The data in this variable contains the data from the form or Guide that was submitted.

Prepare data processes can include as many input variables as you require. The values to use for the input variables are specified in the properties of the Workspace start point, Assign Task operation, or Assign Multiple Tasks operation.