Recording and playing back process

Record process instances as they execute at run time and then play them back to observe the behavior of the process:

  • See which routes are followed when the process is executed.

  • Determine the values that variables are assigned at each step in the process.

Recording and playing back is useful for testing process versions in the development environment before performing formal testing in a staging environment.

Note: If your process includes no operations or includes only an event start point, you need to add the Decision Point operation to the process diagram so that process Input variable values are recorded.

Process recordings are saved on the LiveCycle Server so that they are available to other developers running other installations of Workbench.

Before testing process versions by recording and playing them back, you should validate them. (See Validation reports.)

The following procedure describes the tasks that you perform to record process executions and play them back:

  1. Enable recording for the process version. (See Enabling and disabling recording.)

  2. Record and playback a process when invoking a process. (See Invoking processes directly.)

  3. Invoke the process version. (See Invoking process versions.)

  4. Play back the recorded process instance. (See Playing back process recordings.)

  5. Delete recorded process instances that you no longer need. (See Deleting recordings.)

  6. Disable recording for the process version. (See Enabling and disabling recording.)

Note: In case an endless loop is executing in a process instance, for each process instance a maximum of 250 operation executions can be recorded. This limitation preserves server resources in the event of an endless loop.

Enabling and disabling recording

Enable recording for a process version to record the execution history of the process version. While recording is enabled, a new recording is saved each time the process version is invoked. Disable recording when you no longer want to record process executions.

Note: Recording uses resources on the LiveCycle Server, and reduces performance. You should record only in development environments.

When recording is enabled for a process version, the icon for the process version in the Processes view includes the image of a red recording button in the upper-right corner  .

When you create recordings for a process version and then make changes to the process version, the recordings are still available for playback.

To enable recording, the process version must be activated.

Keep in mind that you can also enable record process executions when invoking a process. (See Invoking processes directly.)

To enable or disable recording for a process version:

 In the Applications view, right-click the process version and click Record And Playback > Start Recording or Record And Playback > Stop Recording.

If a process version has recording enabled, recording is automatically stopped if the process is deactivated.

If the process version is open, you can right-click an unused area of the process diagram to access the commands.

Invoking process versions

When recording is enabled for a process version and you invoke the process version, the execution of the resulting process instance is recorded. You can invoke process versions directly by using Workbench or using the endpoints that are configured for the process service:

Invoking processes directly

You can invoke process versions from within Workbench for testing purposes. Invoking directly is useful for focusing only on the process version functionality.

After focusing on the process version, you should perform tests that mimic usage scenarios that are expected in the production environment. (See Testing using realistic scenarios.)

When you invoke process versions directly, specify values for input variables. The results of the process execution appear in a dialog box. The information that the dialog box provides depends on whether the process version is long-lived or short-lived:

Long-lived:
The dialog box indicates the identification of the process instance. (See also Short-lived processes and long-lived processes.)

Short-lived:
The dialog box indicates the values of the output variables for the process instance.

If you invoke a process version multiple times, you can either use the same values for input variables or specify different values.

Keep in mind that you can optionally record process executions and play them back when invoking a process.

To invoke a process version directly:

  1. In the Applications view, right-click the process version and select Invoke Process.

  2. Specify values for the input variables of the process version. Required values are denoted with an asterisk (*):

    • If you previously invoked the process version directly, the input variables are automatically configured with the previously-used values.

    • To change all existing values, click Reset to remove the values and then specify new values.

  3. (Optional) To record process executions, do one of the following:

    • Short-lived process: To record process executions and play them back, select Enable and Playback Recording.

    • Long-lived process: To record process executions, select Enable Recording.

  4. Click OK.

If the process version is open, you can right-click an unused area of the process diagram to access the Invoke Process command.

Invoking processes using endpoints

Invoke process versions to execute them and create process instances. You can invoke process versions by using various tools that LiveCycle provides:

  • LiveCycle programming APIs and EJB, SOAP, and remoting end points.

  • Watched Folder or Email endpoints.

  • Workspace and TaskManager endpoints. (For information about processes that integrate with Workspace, see Designing human-centric processes.)

After you activate a process version, EJB, SOAP, and Remoting endpoints are automatically created for the process version’s service. You must manually create Watched Folder, Email, and Task Manager endpoints by using Applications and Services.

For more information about creating endpoints, see “Managing Endpoints” in Applications and Services Administration Help.

Playing back process recordings

Play back recorded process instances to observe the behavior that occurred at run time. When you play a recording, the associated process version is opened in playback mode:

  • Routes that were followed at run time are highlighted in green.

  • Playback controls enable you to step through the recording.

As you play the recording, you can see the value that process variables contain after each operation was executed. This information is valuable for troubleshooting unexpected behavior.

Opening recordings in playback mode

Open recordings in playback mode so that you can see the routes that were followed at run time and to play the recording.

Note: You cannot edit process maps when they are open in playback mode.
View full size graphic
A.
Playback controls

B.
Route that was followed

To open a recording in playback mode, you select the recording from a list of existing recordings. The list provides the following information so that you can identify the recording that you are interested in:

Process Instance ID:
The unique identification of the process instance that was recorded.

Recording Started:
The date and time when the recorded process instance was invoked.

Process Version:
The number of the process version, and the date and time when the revision was saved.

Recordings are associated with the revision of the process version that they are made with. When you open a recording that was created with a prior revision of a process version, the process diagram appears as it did for that revision.

For example, after you create a recording for a process version, you add an operation to the process map and save the changes. The recording that you created is associated with the previous revision of the process version. When you open the process recording in playback mode, the process diagram appears without the operation that you saved in the latest revision.

You can specify that recordings for a process version are deleted automatically when the process version is saved. (See Customizing record and playback behavior.)

You need to be assigned the Process Administrator role or have the Process Recording Read/Delete permission to play and delete recordings. Contact your LiveCycle administrator, or use Administration Console to set these permissions.

To open a recording in playback mode:

  1. In the Applications view, right-click the process version to play a recording for and select Record And Playback > Play Process Recording.

  2. Select the recording to play and then click OK.

If the process version is open, you can right-click an unused area of the process diagram to access the Record And Playback commands.

Playing recordings

Play recorded process instances to observe process behavior at run time. When playing, you can see variable values at each operation, and information about any errors that have occurred. (See Interpreting recordings.)

Note: Before you play a recording, you need to open the recording in playback mode. (See Opening recordings in playback mode.)

When playing recordings, the progress line indicates the current state of the process instance during execution:

  • Ticks on the progress line represent the operations that executed at run time.

  • The direction of progress is from left to right. The first tick on the progress line represents the process before it is executed.

  • The slider on the progress line indicates the current state of progression. The tick where the slider is positioned represents the last operation that completed executing. This operation is also highlighted on the process diagram.

For example, a progress line that includes five ticks indicates that four operations executed at run time. If the slider is located at the third tick during playback, the second of the four operations has completed executing.

You can either play the entire recording or manually step through the recording. Manually stepping through the recording allows more time for observing variable values at each operation.

You can specify the amount of time that playback pauses at each tick. (See Customizing record and playback behavior.)

To play the entire recording:

  1. Click the play button  .

    While playing, the pause button appears instead of the play button.

  2. To pause playback at a tick, click the pause button  .

To manually step through the recording:

  1. To advance to the next tick, click the step forward button  or click the next tick on the progress line.

  2. To move to the previous tick, click the step backward button  or click the previous tick on the progress line.

Interpreting recordings

Visual indicators on the process diagram provide information about the results of the process execution:

  • Routes that were followed during execution are highlighted in green. Routes that were not followed are blue.

  • As you play or manually step through the recording, the last operation that completed executing is highlighted. The color of the operation indicates the success of its execution:

    • Green indicates that the operation executed successfully.

  • Red indicates that an error occurred during execution.

Use the Variables view to see the run-time values of variables:

  • The values correspond with the current state of execution during playback.

  • Variables whose values changed are highlighted in green. Variables are highlighted only at the steps that cause a change to occur.

  • Values of simple data types appear on the view. Values of complex data types are displayed in a separate dialog box.

  • If a variable value is a document, you can open the document in the application that it is associated with. For example, if your operating system associates XML files with a web browser, then XML files open in the web browser.

  • If a variable is used to store form data and the form location, you can open the form and see the form data.

The Variables view also shows information about any errors that occurred during execution. Errors in the view are highlighted in red. The columns contain the following information:

Name:
Contains Error.

Type:
The type of error and the error message.

Value:
An ellipsis button that opens an Error dialog box that shows the error message and stack trace. Use this information to determine the cause of the error.

If no errors occurred during execution, no Error row appears in the Variables view.

To see variable values during playback:

 When the recording is playing, see the value in the Value column of the Variables view. For complex data types, documents, lists, and maps, click the ellipsis button to see the data or open the document  .
Right-click a variable and select Copy to copy the value of the variable. You can paste the value in an email message for communicating with other developers.

To see details about errors:

  1. In the Error row on the Variables view, click the ellipsis button in the Value column  .

  2. Click Details to see the stack trace.

Deleting recordings

You can delete recordings at any time when you no longer need them.

You need to be assigned the Process Administrator role or have the Process Recording Read/Delete permission to delete recordings. Contact your LiveCycle administrator, or use Administration Console to set these permissions.

You can specify that recordings for a process version are deleted automatically when the process version is saved or deleted. (See Customizing record and playback behavior.)

To delete a recording:

  1. In the Applications view, right-click the process version for which you want to play a recording and select Record And Playback > Delete Process Recordings.

  2. Specify the recordings to delete:

    • To delete all recordings, select Delete All Recordings.

    • To delete one or several recordings, select Delete The Recordings Selected Below, and select the recordings to delete.

  3. Click OK.

Customizing record and playback behavior

Several preferences can be configured that control some of the behavior of the record and playback features. The following table describes the preferences that you can configure.

Preference

Default value

Description

-Dcom.adobe.workbench.recordings.remove_on_save

 

false

Controls whether recordings for a process version are removed when the process version is saved.

A value of true keeps recordings that are associated with prior revisions of process versions.

-Dcom.adobe.workbench.recordings.remove_on_delete

 

true

Controls whether recordings for a process version are removed when the process version is deleted.

A value of true removes all recordings for a process version when it is deleted.

-Dcom.adobe.workbench.playback.max_recordings_to_display

100

The maximum number of recordings that are listed when selecting recordings to delete or play.

-Dcom.adobe.workbench.playback.animation.milliseconds_to_delay

2000

The amount of time, in milliseconds, that the slider pauses at a tick on the progress line when playing recordings.

-Dcom.adobe.workbench.unsupported.audit.maxNumberOfStepsToLoad

250

The maximum number of steps for each recording that can play back.

To configure preferences, modify the workbench.ini file. Each line in the file contains a preference setting in the following format:

preference_name = value

For example, the following preference setting specifies that recordings for prior revisions of process versions are saved:

-Dcom.adobe.workbench.recordings.remove_on_save=false

The workbench.ini file is located in the [install directory]/Adobe LiveCycle Workbench ES3/Workbench directory, where [install directory] is the location where you installed Workbench.

Note: If the -Dcom.adobe.workbench.recordings.remove_on_delete preference is set to true, but you remove a process version by deleting the process archive in the Administration Console, the recordings for that process are not removed. To remove the recordings, stop and start the Audit Workflow DSC component. (See Stopping components and servicesand Starting components and services.) This action will remove all the recordings you created.

To customize record and playback behavior:

  1. Open the workbench.ini file in a text editor.

  2. Modify the values of preferences as required.

  3. Save workbench.ini and restart Workbench.

Limiting storage space used for recordings

To conserve space on the LiveCycle Server’s file system, you can limit the amount of process recording data that is stored. You can configure the following properties of the AuditWorkflowService service:

maxNumberOfRecordingInstances:
The maximum number of recordings that are stored. When the maximum number is stored, the oldest recording is removed from the file system when a new recording is created. This property is useful if you tend to create many recordings and you want to remove old recordings automatically.

maxNumberOfRecordingEntries:
The maximum number of data entries that can be stored for each recording. Data entries are information about operations in the process. Several entries are stored for each execution of an operation, such as whether the operation started, whether the operation completed, and whether the route that leads to the operation is complete. This property is useful when processes can include many operation executions, for example, when an endless loop is encountered.

The AuditWorkflowDSC component provides the AuditWorkflowService service. Use the Components view to configure the service properties. (See Editing service configurations.)

Processes can also be designed to minimize the storage space used for recordings:

  • Use counters in loops to limit the number of loops that are executed. (See Loops.)

  • Segment your processes using subprocesses and enable recording only for the subprocesses that you are testing. (See Process designs for reuse.)

Configuring server memory for large recordings

Playing recordings of processes that include many variables or many operations can require the use of large amounts of memory on the LiveCycle Server. When the LiveCycle Server becomes destabilized when you try to play a process recording, the Java Virtual Machine (JVM) that hosts the application server can require more memory than it is allocated. Also, you may need to restart the computer that hosts the server to establish stability.

To increase the memory that is allocated to the JVM, configure the -Xmx option of the JVM that runs the application server. For example, if the current option is -Xmx1024m, change the option to -Xmx1280m to increase the maximum amount of allocated memory by 256 MB.

The following table lists links to LiveCycle documentation that provide information about how to configure JVM options on your application server.

Application server

Documentation

JBoss

See the “Modifying the JBoss configuration files” topic in the Preparing To Install LiveCycle guide.

WebSphere

See the “Configuring the JVM arguments and properties” topic in the Installing and Deploying LiveCycle for WebSphere guide.

WebLogic

See the “Configuring the JVM arguments” topic in the Installing and Deploying LiveCycle for WebLogic guide.

// Ethnio survey code removed