Appendix B   Migrating from Previous Releases


This appendix describes how to run or edit PAE 4.0 and Process Manager 1.x applications in Process Manager 6.0.

This appendix contains the following topics:

• Migrating from PAE 4.0 to Process Manager 6.0

• Migrating from Process Manager 1.x to Process Manager 6.0

Migrating from PAE 4.0 to Process Manager 6.0

---

Process Manager 6.0 runs on iPlanet Application Server 6.0. It also requires iPlanet Web Server 4.1 (iWS 4.1).

If you have been running PAE 4.0, you need to perform the following tasks to upgrade to Process Manager 6.0:

1. Backup your applications that you have on your PAE 4.0 server (you can do this by saving them using your PAE 4.0 Builder to a your local hard drive).

2. Backup your PAE 4.0 applications directories that are within your Builder applications directory for safekeeping (the application directory is located at builder-root/applications/yourappname).

3. If you are installing Process Manager 6.0 on the same machine as PAE 4.0, shutdown all PAE 4.0 services (ldap server, applications server). Uninstall PAE 4.0.

4. Install Web Server 4.1 if it is not already installed. Create a new instance of the web server.

5. Install Process Manager 6.0. See the Installation Guide for details.

6. Create a new Process Manager cluster.

7. Copy your backed up applications directories to the new Process Manager 6.0 Builder applications directory.

8. Fix any user-defined assignment scripts, as discussed in the next section.

9. Redeploy your PAE 4.0 application using the Process Builder 6.0 to your new Process Manager 6.0 cluster.

Assignment Function Changes

In Process Manager 6.0, assignment scripts return an array of user IDs and/or group names instead of an array of distinguished names. If your applications use the built-in assignment scripts, you do not need to make any changes to your applications. However, if you wrote your own assignment scripts, you must rewrite them to return an array of user IDs and/or group names.

Method Changes

The following JavaScript functions changes have been implemented:

Process Instance Methods

• getCreatorDN() has been removed.

  Use getCreatorUser() instead.

• getRoleDN() has been removed.

  Use getRoleUser() instead.

• RoleByDN() has been removed.

  Use setRoleById()() instead.

• setTitle() has been removed.

• setPriority() has been removed.

WorkItem Methods

• getAssigneesDN() has been removed.

  Use assignees() instead.

• assignTo() has been removed.

  Use removeAssignees() to remove assignees, and use addUserAssignee() and addGroupAssignee() to add users and roles as assignees.

• getCurrentActivityCN() has been removed.

  Use getNodeName() instead.

• expire() has been removed.

User Methods

• getDN() has been removed.

  You can get the user's distinguished name using user.dn.

Global Functions

• checkUserDNs() has been removed, it is no longer needed.

• emailByDN() has been removed.

  Use emailById() instead.

• setErrorMsg() and setErrorMessage() have been removed.

Migrating from Process Manager 1.x to Process Manager 6.0

---

This section has the following topics

• Getting Started

• Importing an Application to Process Builder

• Migrating SSJS-specific Objects

• Migrating Custom Fields

Getting Started

Before users can begin working with a Process Manager 1.x application, you must first import the application into 6.0's Process Builder 6.0, then deploy that application to a cluster. The major steps are as follows:

1. Import the application to Process Builder.

2. Run Check Errors on the application.

3. Add an exception node, if necessary.

4. If the application uses SSJS-specific objects, you must perform the recommended migration action specified in Migrating SSJS-specific Objects.

5. Update Assignment Scripts if necessary.

6. Deploy the application as usual.

Importing an Application to Process Builder

To begin migrating an application to Process Manager 6.0, you must import the Process Manager 1.x application to Process Builder by performing the following steps:

1. From the Application menu of Process Builder, choose Import from ZIP.

   The Import Application from Zip File dialog box appears.

2. Using the Browse button, navigate to the Applications folder where your Process Manager 1.x files are stored.

3. Select the application you want to open.

   The application file name should begin with wf and end with .zip.

4. From the Application Folder drop-down menu, choose the folder where you want Process Builder to extract the application files.

5. Click OK.

   Process Builder expands the .zip file into the selected folder.

Assigning Exception Nodes

In Process Manager 1.x, exception nodes were required when your application used subprocesses. However, in Process Manager 6.0, these nodes are assigned to every step in the process. Therefore, an exception node must be assigned to each step in your imported process. When you import a Process Manager 1.x application, Process Builder detects that the application is lacking exception nodes and will automatically create a default exception and assign each step to this exception node for you.

The application is now in Process Manager 6.0 format and you can open it as usual.

Checking for Errors

Now that your Process Manager 1.x application has been imported to Process Manager 6.0, you must run Check Errors before you can deploy the application for use. To run Check Error, perform the following steps:

1. Open the application in Process Builder.

2. From the Application menu of Process Builder, choose Check Errors.

   The Checking Application dialog box appears.

3. The Messages window appears, displaying any errors, warnings, or information pertaining to the application.

You may see exceptions for JavaScript errors in the Messages window. Previous versions of Process Manager did not perform automatic syntax checking.

If JavaScript errors appear regarding email notification, be sure you have selected both a Content Type (text/html or text/plain) and a Character Set (e.g., us-ascii) in the Inspector window for the notification.

If a "No exception node" exception appears in the Messages window, you must manually assign an exception node to each step in your imported process (see Assigning Exception Nodes). To do so, perform the following steps:

1. Drag an exception node from the Palette to your process map.

2. Double-click or right-click the new node and enter a name for the node.

3. Right-click an action in your process map to bring up the Properties window.

4. From the Exception Manager drop-down menu, choose the new exception node.

   The action is now assigned to the exception node you created in Step 1.

5. Repeat Step 3 and Step 4 for each action in your process map that is not assigned to an exception node.

   Assign a form to the new exception node.This process is described in Setting Access to Forms."

6. Click Save to save the changes to your application.

Updating Assignment Scripts

Assignment scripts now return an array of user IDs and/or group names instead of an array of distinguished names. If you wrote your own assignment scripts, you will need to update them. See the section "Assignment Function Changes" for details.

Deploying the Application

When you have successfully imported your Process Manager 1.x application, checked for errors, and assigned exception nodes as necessary, and if your application does not use SSJS-specific objects or custom fields written in JavaScript, you are ready to deploy your application as usual. See " for instructions.

If your application does use SSJS-specific objects or custom fields written in Java, see the following sections, and for more information.

Migrating SSJS-specific Objects

Server Side JavaScript (SSJS) is not longer supported by Process Manager 6.0. You can still use standard JavaScript in your applications, but if you imported an application developed with SSJS-specific objects, you must rewrite those portions of your application. The following table describes the recommended migration path from SSJS-specific objects to code compatible with Process Manager 6.0:

SSJS object	Recommended migration
Database DbPool Connection ResultSet StoredProc Cursor	Each of these objects relates to database access. In Process Manager 6.0, you should access the database with Java DB access methods (JDBC) using the Custom Activity or Custom Fields features or using JavaScript to access the JDBC methods using Live Connect. For more information on Live Connect, see http://developer.netscape.com/docs/manuals/js/core/jsguide Note that this does not concern access to the main process instance database in the course of normal process development or operation. Process Manager 6.0 handles this access transparently. Rather, the SSJS objects listed in the left column were occasionally used in Process Manager 1.x to access databases external to Process Manager 6.0 or in other extraordinary circumstances.
File	Use Custom Activities to mimic the File Object functionality. You can also use java.io.file.
SendMail	Use Custom Activities to mimic the SendMail functionality. You can also use the SMTP SDK. Note: If you used the drag-and-drop email component on the Process Manager 1.x palette when designing your applications, you do not need to make any changes to your code for this feature.
Project Server Request Client	These objects were often used to store data for server-side information. You can now store information in the Process Instance data or in a Custom Field.

Migrating Custom Fields

Developers should note that Custom Fields in Process Manager 6.0 are different than those in Process Manager 1.x. If your imported application uses Custom Fields, you may have to rewrite portions of code.

In Process Manager 1.x, Custom Fields were written in JavaScript. In Process Manager 6.0, they are written in Java. There are two parts of a Custom Field: a .jsb file, also called a properties file, that contains information about a field, and a .js file, also called an implementation file. The .jsp or properties file remains the same in PAE 4.0 as in Process Manager 1.x, but you must substitute the content of the .js file with a Java implementation.

For more information about using custom fields, see the Process Manager Programmer's Guide.