Upgrading legacy solutions to LiveCycle ES4

Use legacy processes, resources, and events as starting points for developing LiveCycle ES4 solutions that take advantage of new features. After importing legacy processes, resources, and custom events into applications, make them independent from their legacy runtime instances. Then, modify the assets as required.

Make sure that you have imported all processes, resources, and custom events that are referenced. For example, if you are upgrading a process, import the process, forms, and other resources that it uses, custom events, custom render and submit processes, and subprocesses. (See Importing resources, processes, and events to applications)

    Upgrading legacy artifacts

    Workbench automates the process of upgrading legacy solutions and artifacts with the Upgrade ES Artifacts tool. You can bundle a legacy processes and its dependencies (forms, images, etc.) into a LiveCycle ES4 application. Instead of maintaining runtime references, Workbench makes copies of legacy artifacts in the LiveCycle Server when they are selected to be included in an application. Before you attempt upgrading your process, see About the upgraded environment.

    1. In Workbench, access File > Upgrade ES Artifacts.

    2. On the Process Selection screen, select the processes you wish to upgrade. Note that, you can select specific versions of a process you wish to include in your application by drilling down to the appropriate process version. Use the Select All Processes option to select all processes. Click Next.

      Note: Do not import or upgrade pre populated system processes that are provided with Workbench. For example, Process Management Email (system).

    3. Review the summary of selected processes on the Process Preview screen. There might be processes, flagged as Implicit, listed that you may not have selected earlier. These are processes that are referenced by other dependent processes selected earlier on the Process Selection screen. To this end, they are implicitly selected to be upgraded and bundled into an application. You can choose to override these implicit selections by deselecting appropriate assets. Click Next.

    4. On the Resource Selection screen, select the resources you wish to upgrade. Click Next.

    5. Review the summary of your selection on the Selection Process screen. It is recommended that the number of selected resources should not exceed 400. Click Next.

    6. Enter a name and provide a meaningful description for the application on the Enter Application Information screen. Click Finish.

    7. Complete all the manual tasks listed in the dialog box.

    Note: On the Process Selection screen, when folder level selections are made, latest versions of processes are selected by default. To select the previous version of a process, deselect the folder level selection.

    Breaking the link to existing run-time instances

    Break links between imported assets and their legacy run-time counterparts to change assets without affecting existing run-time instances.

    For example, you want to reference a legacy form in an application in the LiveCycle ES4 environment. The new application requires you to change the form. However, the changes cause errors with a legacy process that still uses the form. So, you add the form to the application, and then break the link between the form and the run-time counterpart. Now, the changes do not affect the legacy process.

    All items that are imported from the run-time environment have a value for their Deployment ID property. This property identifies the location of the item in the run-time environment. The value also persists the link between the imported asset and the run-time counterpart. To break the link, remove the value for this property.

    You can still change the run-time instance of a legacy asset after you break the link. Import the process version, resource, or event type again from the run-time environment.

    Remove the value of Deployment ID:

    1. In the Applications view, right-click the asset and click Properties.

    2. Next to the Deployment ID box, click the Reset button and then click OK.

    Note: If you no longer want legacy processes to be available for invocation, remove the endpoints of the process.

    Creating endpoints for processes

    Endpoints that were created in the LiveCycle ES environment are no longer associated with imported processes that have a reset Deployment ID property. To invoke processes using the same type of endpoints, create them.

    In LiveCycle ES4, you create endpoints by adding start points to process diagrams. When the application is deployed, the start points cause the automatic creation of endpoints. You can add the following types of start points:

    Workspace:
    Users invoke processes from Workspace.

    Email:
    Users send an email to the LiveCycle Server to invoke the process.

    Mobile (Deprecated):
    Users invoke processes via LiveCycle express installed on mobile phones.

    Programmatic:
    Oracle™ Java™ and web service applications, REST, and applications built with Flex, can invoke processes.

    Before you add start points, use Administration Console to review the end points that were used in the LiveCycle ES environment. Note the end point properties so that you can duplicate them in the start point properties. (See Managing Endpoints.)

    Note: Workspace start points generate Task Manager end points. Before you can configure Workspace start points, configure assets and xml variables. (See Upgrading human-centric processes.)

    Before you add a start point, you need to reset the Deployoment ID property. (See Breaking the link to existing run-time instances.)

    To add a start point:

    1. Drag the start point icon onto the process diagram.

    2. Select the type of start point to add and click OK.

    3. Click the start point and provide values for properties in the Process Properties view.

    Replacing legacy subprocesses

    If your process invokes legacy processes (subprocesses), import the legacy subprocesses into an application and reset the Deployment ID. The application that contains the subprocess to invoke must be deployed. When deployed, the service in LiveCycle ES4 for the process is created.

    Before you replace a legacy subprocess, note the name and property values.

    Replace legacy subprocesses:

    1. Delete the icon for the subprocess from the process diagram.

    2. Drag the Subprocess icon to the process diagram.

    3. In the Find box of the Define Subprocess Activity dialog box, type the name of the process to invoke.

    4. Select the process that exists in the application and click OK.

    5. Select the subprocess icon and configure the properties in the Process Properties view.

    Configuring security settings

    Security settings of legacy processes are not persisted when the Deployment ID property is reset. Configure security settings manually using Administration Console. (See Modify security settings for a service.)

    Upgrading LiveCycle 7.x QPAC processes

    Processes that use LiveCycle 7.x QPACs will not function in LiveCycle ES4 as there is no direct upgrade path defined. Workbench will indicate the lack of support for such processes and if you intend to use them in the LiveCycle ES4 environment, their QPACs have to be replaced with LiveCycle ES update 1 compatible DSCs. Once this intermediary step is complete, you can use the Upgrade Legacy Artifacts wizard to upgrade processes and their dependencies to an LiveCycle ES4 compatible application.

    Workbench indicates QPACs whose functionality can be directly replaced with DSC. To find a replaceable DSC, select the activity with the QPAC and review the information in the Process Properties view. Replace the QPAC with a DSC as indicated.

    For more information on upgrading legacy processes, see Upgrading legacy artifacts.

    Note: There may be QPACs which might not have a direct functional DSC replacement. Functionally replaceable custom DSCs have to be created for such QPACs.

    Using deprecated operations

    Some operations have been deprecated since the previous release. Typically, deprecated members are replaced with new ones. Replace deprecated operations in your legacy processes to take advantage of improvements they provide. Also, replacement operations are supported longer than deprecated ones.

    In lists of services and operations, such as on the Services view, the names of deprecated services and operations have the suffix "(deprecated)".

    Exporting embedded documents from operation properties

    In LiveCycle ES, some service operations allowed you to select documents from the file system to use as property values. After selecting the document, it became embedded in the process properties. For example, you could select DDX documents from the file system to configure the properties of invokeDDX and invokeOneDocument operations of the Assembler service.

    LiveCycle ES4 now enables you to select documents from applications so that you can more easily update them. Consequently, after importing a process that includes embedded documents, you cannot use the Process Properties view to view or edit the documents. To view or edit embedded documents, export them to an application. After exporting, open the asset to view or edit it.

    You can export embedded documents only after you import the process to an application. The process must also be checked out when you export. When you export the document, the operation property is automatically configured to use the new asset as a value.

    Export embedded documents:

    1. On the process diagram, select the operation that uses an embedded document as a property value.

    2. In the Process Properties view, locate the property that uses the embedded document as a value.

    3. Click the Export button .

      The Export button appears only when an embedded document value exists.

    4. In the File Name box, type a name for the file. Use the correct file name extension.

    5. Select the application version and folder in which to save the file, and then click OK.

    Changing the reliance on null value results from XPath expressions

    Review any logic in your processes that rely on the following situation:

    • Null values are returned from XPath expressions.

    • The XPath expressions retrieve values from data types that are defined by service components or custom Java classes in custom components (service container files).

    In LiveCycle ES4, this situation causes XPath expressions to return an empty-value instance of the data type instead of null. If your business logic relies on null values from XPath expressions, make sure the XPath expressions still return null. Otherwise, change the implementation of the business logic.

    Note: XPath expressions that return values from xml variables continue to support null values.

    Upgrading human-centric processes

    Human-centric processes that are imported into applications and have reset Deployment ID properties require several changes due to the following changes in LiveCycle ES2:

    • Forms and form data are represented differently.

    • Render and submit services are configured differently.

    • Task Manager end points are created using Workspace start points.

    • The User service is deprecated, and replaced with the User 2.0 service.

    Note: Although the User service is supported, product changes have complicated its use in LiveCycle ES4 solutions. Adobe strongly recommends that you use the User 2.0 service.

    Processes that use the User service or Task Manager end point require the following changes:

    Replacing form-specific variables

    Configuring Workspace start points

    Using the User 2.0 service

    You must have already imported your processes (including custom render and submit processes and subprocesses), forms, and other resources into one or more applications. (See Importing resources, processes, and events to applications.) You also need to reset the Deployoment ID property. (See Breaking the link to existing run-time instances.)

    Replacing form-specific variables

    In LiveCycle ES4, xfaForm, Document Form, and Form variables are not used to represent forms and form data. Instead, form assets are referenced directly and data is saved in xml variables. When forms submit PDF documents, the document is saved in document variables.

    Note: Render and submit services are no longer configured in form variable properties. Instead, they are associated with the action profiles of form asset properties. Action profiles control which render and submit services are used, and other properties that involve presenting assets and data to users.

    Before you replace an xfaForm, Document Form, or Form variable, note its property values. Perform the following procedure to create an xml variable for each xfaForm, Document Form, and Form variable in your process. You must have already imported the forms that the variables represented into applications.

    Create an xml variable:

    1. In the Variables view, click Create New Variable .

    2. In the Name box, type a name for the variable, following these naming rules:

      • Must be a valid XML element name that contains only valid XML characters.

      • Must not start with a digit.

      • Must be less than 100 characters long.

      • Must be unique and therefore cannot be id, create_time, update_time, creator_id, or status, which are reserved variables always in the process data model.

    3. In the Type list, select xml.

    4. If the variable is used to store process data, select Process Variable in the Purpose area.

      • If the variable stores input data that is provided when the process is initiated, select Input.

      • If the variable stores data that is returned to the process initiator when the process is complete, select Output.

      • If the variable stores input data that is mandatory to initiate the process, select Required.

    5. To import a schema to make the xml data structure appear in XPath Builder, click Import Asset.

    6. Select an XSD file or an XDP file that has an embedded schema from an application and click OK.

    7. Click OK.

    Using legacy render and submit processes

    Action profiles provide more flexibility for prepopulating, rendering, and submitting presentation assets such as forms. The features of action profiles can negate the need for custom render and submit services. However, you can still use your custom render and submit processes from LiveCycle ES in your LiveCycle ES4 solutions.

    Note: To determine whether your custom render and submit processes are still needed in LiveCycle ES4, see Designing data capture and presentation.

    In LiveCycle ES4, render and submit processes must include an input variable of type Task Context. To invoke your legacy render and submit processes directly, redesign them so that they use a TaskContext value as input. To avoid redesigning, create a process that invokes your legacy render or submit process:

    • Legacy render and submit processes require no changes.

    • Input values for the legacy process are configured on the service’s invoke operation.

    • The TaskContext value that is automatically passed to the new process contains useful data for configuring the invoke operation.

    Perform the following procedures for each form asset to use custom render and submit processes. You must have already imported the custom render and submit processes into an application. (See Importing resources, processes, and events to applications.)

    Reset Deployment ID properties:

    1. Reset the Deployment ID property of the legacy render and submit processes that you have imported. Resetting enables you to invoke them as subprocesses. (See Breaking the link to existing run-time instances.)

    2. Right-click the application that contains the render and submit process and click Deploy.

    Create new render and submit processes:

    1. In the Applications view, right-click the asset and click Manage Action Profiles.

    2. Select the default action profile, or create an action profile to preserve the default one.

    3. To create a render process, under Render Process click the Create A Render Process button .

    4. Type a name for the process and click OK.

    5. To create a submit process, under Submit Process click the Create A Submit Process button .

    6. Type a name for the process and click OK.

    7. Click OK to close the Manage Action Profiles dialog box.

    Configure render and submit processes:

    1. In the Applications view, right-click the new render or submit process and select Open.

    2. Define the operation that was automatically added to the process:

      • For render processes, right-click the Render operation and click Define Operation.

      • For submit processes, right-click the Submit operation and click Define Operation.

    3. Select the invoke operation of the legacy render or submit process and click OK.

    4. On the Confirm dialog box, click Yes.

    5. In the Process Properties view, configure the Input and Output properties of the invoke operation.

    Configuring Workspace start points

    Configure the Workspace start point that you added using the procedure in Creating endpoints for processes.

    Most of the values for the Workspace start point are the same that were used for the LiveCycle ES Task Manager endpoint. The following table shows how to use the values from the LiveCycle ES Task Manger endpoint properties to configure the Workspace start point.

    LiveCycle ES Task Manager endpoint property

    Corresponding Workspace start point property

    Name

    General/Name

    Description

    General/Description

    User Can Forward Task

    Options/User Can Forward Task

    Show Attachment Window

    No equivalent property. If Permit Adding Attachments is selected, the attachment window appears.

    Allow Attachment Adding

    Attachment Options/Permit Adding Attachments

    Task Initially Locked

    Options/Task Initially Locked

    Add ACLs for Shared Queues

    Options/Add ACLs For Shared Queues

    Task Instructions

    General/Task Instructions

    Process Owner

    General/Contact Info

    Categorization

    General/Category

    Operation Name

    Not needed. The current process is invoked.

    Other Workspace start point properties configure the form and variable to use to store form data:

    Asset:
    The presentation asset to display to the user. Click the ellipsis button and select a form or Guide file. You can select a file from any application.

    Action Profile:
    The action profile to use with the asset. The action profiles that appear are already created for the asset that you selected.

    Variable:
    The variable in which to store the submitted data. Select either an xml, document, or Task Result variable:

    • Select an xml variable if the asset submits field data that is en XML or XDP format.

    • Select a document variable if the asset is a PDF form that submits a PDF document.

    • Select a Task Result variable to save the field data as well as other information about the task.

    Reader Submit:
    Properties for enabling the submission of XDP or PDF forms that do not include a submit button. LiveCycle ES did not support this situation so you do not need to configure this property.

    Before you configure the start point, configure your form assets and xml variables. (See Replacing form-specific variables.)

    Configure the Workspace start point:

    1. In the process diagram, select the Workspace start point.

    2. In the Process Properties view, configure the properties using equivalent values from the LiveCycle ES Task Manager endpoint according to the previous table.

    3. Expand the Presentation & Data property group and provide the following values:

      • Asset: Select the form or Flex application to present to users.

      • Action Profile: Select the action profile of the asset that you want to use.

      • Start Point Output: Select the xml variable for saving the submitted data.

    Using the User 2.0 service

    Replace each Assign Task operation (User service) on your process diagram with an Assign Task operation from the User 2.0 service.

    Most of the values for the new Assign Task operation are the same that were used for the deprecated Assign Task operation. The following table shows how to use the values from the deprecated operation to configure new Assign Task operations.

    Deprecated Assign Task property

    Corresponding Assign Task operation (User 2.0 service) property

    General properties

    General properties

    Route Evaluation properties

    Route evaluation properties

    Initial User Selection properties

    Initial User Selection properties

    Task Instructions

    Task Instructions

    Form Data Mappings

    No corresponding properties. Forms and form data are represented differently in LiveCycle ES4.

    Task Access Control List (ACL) properties

    Task Access Control List (ACL) properties

    Delegation and Consultation properties

    Reassignment Restrictions properties

    Attachments and Notes/Show Attachment Window For This Task

    Attachments/Show Attachment Window For This Task

    Attachments and Notes/Do Not Initialize This Action With Any Notes Or Attachments

    Attachments/Input List (Do not specify an input list)

    Attachments and Notes/Copy All Notes and Attachments From Previous Task

    Attachments/Input List (Use the list variable that saved output attachments from the previous task)

    Attachments and Notes/Copy All Notes and Attachments From A List Of Documents

    Attachments/Input List

    Attachments and Notes/Output Attachments

    Attachments//Output Attachments

    Routes And Priority/Initialize Task With Route Names

    User Actions/Specify Custom Names For Actions. Add a user action for each route name.

    Routes And Priority/User Must Select A Route To Complete The Task

    No corresponding property. In LiveCycle ES4, users must always select a user action to complete the task.

    Routes And Priority/Select Priority For This Task

    Priority/Task Priority

    Reminders properties

    Reminders properties

    Escalation properties

    Escalation properties

    Deadline properties

    Deadline properties

    Custom Email Template properties

    Custom Email Template properties

    Before you replace deprecated Assign Task operations, you must have already configured your form assets and xml variables. (See Replacing form-specific variables.) Use the following procedures to replace a deprecated Assign Task operation.

    Add an Assign Task operation:

    1. Drag the Assign Task operation to the process diagram.

    2. In the Process Properties view, configure the properties using equivalent values from the deprecated Assign Task operation that you are replacing according to the previous table.

    3. Expand the Presentation & Data property group

    4. Select Use An Application Asset, click The ellipsis button next to the Asset box, and select the form asset.

    5. Make sure the action profile that you want to use is selected.

    6. (Optional) To prepopulate the asset, in the Variable list select an existing xml variable that contains the data. For example, select the variable that was used as the Start Point Output property value. To create an xml variable to use as the property value, click the Create New Variable button .

    7. Expand the Output property group.

    8. (Optional) To save submitted task data, in the Task Result list select a Task Result variable. To create a variable to use as the property value, click the New Variable button and create a Task Result variable.

      Task Result variables were introduced in LiveCycle ES2. They store all data that is submitted with tasks, such as asset data and information about the task.

    9. (Optional) To save submitted asset data, in the Output Data list select an xml variable to save the data. Saving the asset data separately is useful for using the data to populate the asset of a subsequent task.

    Draw routes for the new Assign Task operation:

    1. If the routes that lead to or away from the deprecated Assign Task operation include conditions, note the expressions of the conditions.

    2. Delete the routes that lead to and away from the deprecated Assign Task operation.

    3. Draw routes to and from the new Assign Task operation that you added in the previous procedure.

    4. (Optional) If the deprecated Assign Task operation used route names as task submission options, add a user action for each route. For example, if the route names were Approve and Deny, add user actions named Approve and Deny:

      • Expand the User Actions property group.

      • Click the Add A User Action button .

      • In the Action Name box, type the name of the action as you want it to appear to the user.

      • From the Destination list, select next operation to execute when the user action is clicked, and then click OK.

    5. (Optional) If the routes to or from the deprecated Assign Task operation included conditions, add the conditions to the routes of the new Assign Task operation:

      • Select the route and in the Process Properties view, expand the Conditions property group.

      • Click the Add Route Condition button.

      • In the Expression box on the left, type the first part of the expression. If the condition is complex, click the ellipsis button to display the XPath Builder.

      • In the Operation list, select an operation.

      • In the Expression box on the right, type the second part of the expression. If the condition is complex, click the ellipsis button to display the XPath Builder.

      • Click OK to close the Route Properties dialog box.

      • If you have more than one routing condition in the Conditions category, select the join condition to determine how the conditions are evaluated:

        • Use AND Join For Conditions means that the route is valid only if all the conditions evaluate to True.

        • Use OR Join For Conditions means that the route is valid when one or more of the conditions evaluate to True.

        The default join condition is Use OR Join For Conditions.

    Delete the deprecated Assign Task operation:

     Right-click the deprecated Assign Task operation and click Delete Operation.

    Migrating LCAs to LiveCycle ES4

    *New for 10*

    Workbench is integrated with the Archive Migration tool, which allows you to upgrade LiveCycle archive files to the application model. The tool was available as a plug-in for earlier versions, but is a standard feature of Workbench 11.

    The Archive Migration Tool converts 8.x LCAs to the application model. The application model is a functional equivalent of the resources model seen with LiveCycle 8.x.

    1. To access the Archive Migration Tool, go to File > Archive Migration Tool.

    2. Click the Browse button and point to the LCA that you intend to migrate.

    3. Enter a name and description for the new LiveCycle ES4 application. Click Finish.

    4. In the applications view, you can now see that a new application has been created.

    The newly created application has not been stored into the LiveCycle Server yet. You can accomplish the same by checking in the application and its assets in Workbench.

    Perform the following tasks after migrating your LCA:

    • When you migrate your LCA, references to process variables and activity configurations break. Sift through activities and ensure that activity configurations and process variables are intact. Update the references manually when ever necessary.

    • Replace deprecated APIs with new APIs.

    • If your processes use Events, redeploy the process and refresh the Events view.

    Note: Archive Migration tool does not migrate custom components. Migrate them manually by reimporting them in the components view.

    Updating references to assets

    After importing legacy processes, resources, and event types into applications, the URL of the item is changed. Update the references to the items in your forms (if the relative location has changed) and custom client applications.

    Process services

    Change custom applications that you created with the LiveCycle ES SDK if they invoke services that are created for deployed processes. In LiveCycle ES4, the name of these services in your Java™ code must be in the following format:

    [Application Name]/[Service Name]

    • [Application Name] is the name of the application that the process belongs to.

    • [Service Name] is the name of the process service.

    Resources

    Change references to resources to use URLs in the following format:

    repository:///Applications/[Application Name]/[version]/[legacy path]

    • [Application Name] is the name of the application that the resource belongs to.

    • [version] is the version of the application.

    • [legacy path] is the path of the resource as it appeared in the Resources view.

    For example, in the Resources view, the path of a form is Loan/Forms/request.xdp. The form is imported into version 1.0 of an application named NewCustomers. The new URL is repository:///Applications/NewCustomers/1.0/Loan/Forms/request.xdp.

    // Ethnio survey code removed