IBM BPM, V8.0.1, All platforms > Migrating and upgrading your IBM BPM environment > Migrating from previous versions > Migrating from Teamworks 6 > Upgrade Readiness Check

Handling migration issues

How you address potential issues identified by the Upgrade Readiness Check tool depends upon the type of assets that are reported to be problematic.

The following sections describe various types of items whose definition or use can cause the Upgrade Readiness Check tool to issue an error, warning, or info message. In addition, suggestions are provided for addressing these potential issues.

APIs

Implementations that use certain APIs may be affected by migrating to IBM BPM.

• The Teamworks Java APIs were deprecated in Teamworks 6 and they are not supported in IBM BPM V8.0.1. They have been used primarily for modifying Teamworks Process Portal or for implementing alternative client applications. Custom client code that uses Teamworks Java APIs should be updated to use IBM BPM web APIs instead. If Teamworks 6 Java APIs are called from JavaScript in service implementations, that code should be updated to use IBM BPM JavaScript APIs.
• IBM BPM web APIs should not be used in service implementations. Use of these APIs in services.should be replaced with calls to current JavaScript APIs.

  If you have custom client code that uses web APIs, review the current documentation carefully, as some interfaces have changed.

• Use of internal Teamworks APIs is not supported and may not work after migrating. Much of the functionality for which some customers have used the internal Teamworks APIs is now provided by the JavaScript APIs. Update code that uses internal Teamworks APIs to use current JavaScript APIs.
• SQL queries against Teamworks tables (whose names start with LSW) may or may not work in IBM BPM, depending on the context. Queries against the process server database for runtime data are unlikely to be affected, but should be tested after migrating. For queries that access design-time data, for example the name of a BPD, code created for earlier Teamworks releases will not work and new queries of this nature will be extremely difficult to write because of the built-in asset versioning supported by IBM BPM. Use JavaScript APIs rather SQL queries to access design-time data.

Make changes to API calls during the development migration phase, after you import process assets into IBM BPM.

Java code you use in service implementations should be contained in a JAR file that is managed as an external file in a process application or toolkit, and accessed through a Java Integration Component. The use of LiveConnect to access Java code from JavaScript code is not recommended.

For reference information, see Teamworks 7 JavaScript APIs on the IBM BPM Support site at http://wiki.lombardi.com/display/tw7/Teamworks+7+JavaScript+APIs. Teamworks JavaScript APIs information is also correct for IBM BPM JavaScript APIs.

Browser script

Browser scripts are components that contain JavaScript or VBScript programs.

For example, you might use a browser script to perform a mail-merge operation on a user's machine. Browser scripts are independent services, not associated with a Coach. If they use ActiveX controls, they work only in Microsoft Internet Explorer.

When you migrate process assets, each browser script step in a BPD is replaced with a placeholder activity that does nothing. The placeholder identifies the location in the BPD where a browser script was replaced. However, it is preferable to replace browser script steps yourself before migrating process assets.

You should replace free-standing browser scripts with Coaches containing client-side JavaScript. This requires that you translate any VBScript to JavaScript; the syntaxes of these two scripting languages are different, but their capabilities are very similar, and JavaScript can also call ActiveX controls. You can create a managed file containing the JavaScript, and then use that script from a Coach where previously you used a browser script.

Calendar

In IBM BPM, the functions previously provided by Teamworks calendars are now provided by work schedules, which include options for time schedule, time zone, and holiday schedule. Unlike calendars, work schedules are not associated with users or participant groups. Instead, they are defined for specific BPDs and for activities within a BPD.

When you import process assets into IBM BPM, each calendar is split into a corresponding time schedule, time zone, and holiday schedule. However, this may result in more items than are actually needed.

For example, if your Teamworks process contains different calendars for four time zones in the United States and six time zones in Canada, the migrated assets will include ten time schedules and ten holiday schedules. In this situation, you might need only one time schedule (Monday through Friday from 9 AM to 5 PM) and two holiday schedules (US and Canadian). If that is the case, you need to refactor to remove the redundant items after you finish the import.

For activities that previously used a calendar, the time zones are replaced in the migrated version with one of the standard time zones, based on the time zone of the original calendar. You do not need to define time zones.

After you refactor schedules in IBM BPM, test the process assets to ensure that the time-related items work as you expect. See Setting the work schedule for a BPD.

If you currently use Calendars in role definitions, you need to provide additional logic to handle this scenario without using Calendars.

Time schedules and holiday schedules are runtime objects. Therefore, you might need to use deployment services to define time schedules and holiday schedules on runtime servers. This should be done as you deploy process applications from the Process Center to the runtime servers. See Building custom deployment services.

Check business rule

Check business rules originate in processes that were modeled with much earlier releases of Teamworks. Before migrating process assets, you should replace them with an integration service that provides equivalent functionality.

Coach Form and Coach v1

Both Coach Forms and Coach v1s originate in BPDs that were modeled with earlier versions of Teamworks. They must be replaced with Coaches created in the Coach Designer in the IBM Process Designer.

You can either do this in Teamworks before you migrate process assets or in IBM BPM after you migrate process assets.

Replacing Coaches in IBM BPM is simpler than doing so in Teamworks, but it works well only for BPDs with a small number of Coaches. When you migrate process assets, each Coach form and Coach v1 is replaced with an empty Coach. After you migrate process assets, the Coaches that you see in the BPD in IBM BPM lack the content that they had in Teamworks. You must replace the Coach contents manually, based on screen shots and other record-keeping information that you saved from Teamworks. If you have a large number of Coaches, this process can be unwieldy and time-consuming because it is difficult to keep track of which (new, empty) Coach corresponds to each Coach in the older version and because you must manually re-create all the Coaches.

To replace Coaches in IBM BPM, follow these steps:

1. Insert new Coaches into the Human service alongside the Coach Forms or the Coach v1s that they are replacing.
2. Reroute the process flow so that new instances use the new Coaches, but old instances (using the old Coaches) complete without disruption.

Do not simply replace a Coach Form or a Coach v1 with a Coach created in Coach Designer. Any instances with tokens on the old Coach will fail if the old Coach is simply replaced.

For example, the following image shows a diagram of a coach service that uses a Coach Form:

To make the modeling changes required for replacing a Coach Form or a Coach v1 in Teamworks, follow these steps:

1. Using Coach Designer, add a new Coach to the coach service with the layout and functionality of the old Coach.

2. Create sequence lines for each button in the new Coach to each subsequent item of the old Coach.
3. Reroute the sequence lines going into the old Coach so that they lead into the new Coach.
4. Replace the contents of the old Coach with a single OK button and a text message similar to the following:

   This Coach has been replaced. Click OK to view the current Coach.

5. Create an outgoing sequence line from the old Coach into the new Coach.

   The following image shows the same coach service diagram after these changes have been made:

   

6. After all in-flight instances have moved their tokens beyond the old Coach, you can delete the old Coach.

Coach table control - data retrieval

The data retrieval feature of the Coach table control has been deprecated and will be removed in a future release. Use of this feature is not recommended. Instead, use a SQL Integration service to populate a list variable and map the table control to this list.

Custom priority

Unlike previous versions, IBM BPM supports only standard priorities. When you import Teamworks process assets into IBM BPM, any custom priority codes (both definitions and usages) are automatically replaced with the numerically-closest standard priority code. If this mapping will not meet your needs, you should replace custom priorities with equivalent functionality before you migrate process assets.

For example, you could use a saved search.

Custom status

Custom statuses originate in processes that were modeled with earlier versions of Teamworks that did not include the Process Portal. Custom statuses were used to direct tasks into folders in the user's Task Manager interface. In more recent versions of Teamworks, searches are used to accomplish the same goal. However, in process assets that have been migrated through multiple versions of Teamworks, the database column for custom statuses may contain data, and may be used in queries.

If your processes make active use of custom statuses, you should replace them with equivalent functionality before you migrate assets. In more recent versions of Teamworks, the recommended modeling strategy is to attach metadata to processes rather than to individual tasks.

For example, combining saved search for the process with a subject for the task may provide the same capabilities as a custom status. You might be able to achieve similar results with custom tables.

InfoPath

IBM BPM and IBM BPM for Microsoft Office do not support InfoPath forms. To implement forms that can be completed offline, you can create an external activity that provides the form interface and synchronizes the data with IBM BPM.

Database column size incompatibility

Some database column sizes were decreased in IBM BPM. The Upgrade Readiness Check tool issues a warning when it detects columns holding descriptions that will be truncated on migration. For runtime data that will be truncated on migration, the Upgrade Readiness Check tool issues an error with instructions to contact IBM Support to request assistance. With assistance from the support team, you can move all required runtime data to the new environment.

In some cases, search values displayed in IBM Process Portal will be truncated on migration because of column size incompatibility, but this will not affect the actual value in the process instance.

Log variable

Log variables originate in processes that were modeled with much earlier versions of Teamworks. Before upgrading, you should substitute equivalent functionality.

Default value for output variable

Current versions of IBM BPM do not support default values for output variables. The Upgrade Readiness Check tool issues a warning when it detects an output variable with a default value to notify you that these defaults are removed as part of the migration. When preparing for migration, you should ensure that default values for output variables are removed and the necessary output mappings exist for each activity and service.

CSS file reference

If your process assets in Teamworks rely on external cascading style sheet (CSS) files, empty files are added as managed files and the process assets refer to these empty files upon import. Validation errors are reported on these managed files indicating that they are empty.

JavaScript file reference

If the implementations for your process assets in Teamworks rely on external JavaScript files, the references to those files are maintained after migration. However, after migration, IBM Process Designer displays a validation error for each reference so that you can add the external file as a managed file to ensure that all project assets are included in the Process Center repository and also to enable developers to easily locate and select the JavaScript files when needed.

Non-BPD task management

Some items of concern originate in processes modeled with much earlier versions of Teamworks that did not have business process diagrams. These items were used to send notifications and tasks to users, and to communicate data between tasks. They are unlikely to be in active use in libraries being migrated to IBM BPM, but may exist as historical artifacts in a database that has been previously migrated through multiple Teamworks versions.

If they are actively used in your processes, you should substitute equivalent functionality before you migrate assets, preferably using a business process diagram. The following table lists the items and their suggested replacements:

Item type	Suggested replacement
Alert severity	Send Alert service component, available in the service palette in IBM Process Designer
Alert type	Send Alert service component, available in the service palette in IBM Process Designer
Global variable	Environment variable, Exposed Process Value (EPV), or custom database table, depending on usage
Reference to LSW_CUSTOM_TASK table	saved search
Send Alert v1	A Send Alert service component An integration service to notify users via email Tracking points in a tracking group used in a report
Send Task	BPD with a participant group
Shared symbol table	Refactor using only local variables

Organization chart

Organization charts are not supported in IBM BPM.

If they are included in your Teamworks process assets, you should refactor the assets to substitute equivalent functionality before you migrate assets.

For example, you can create nested participant groups that mimic the hierarchical structure of an organization. If you used organization charts to define task routing, you might need to create a service that implements that routing logic.

Process help

In IBM BPM, the process help wiki feature is no longer supported. However, you can achieve a similar result by linking from Coaches to an enterprise wiki of your choice.

Reports and scoreboards

Reports and scoreboards (other than dashboards) are deprecated in IBM BPM V8.0.1.

In Teamworks, access to reports and scoreboards is controlled by folder permissions defined in Teamworks Authoring Environment. In IBM BPM, access to these items is controlled using the Exposed to field in the scoreboard definition. After upgrading process assets, be sure to verify that each report you want to expose is included in a scoreboard, and that this field is set appropriately. You can then specify the participant groups authorized to see each scoreboard. See Defining reports in Process Designer.

Specific date/time UCA

In earlier versions of Teamworks, you could create an Undercover Agent (UCA) that would trigger at a specific date and time. This type of UCA is not supported in IBM BPM. However, you can implement equivalent functionality using a BPD that contains a timer event configured to trigger at a specific date and time. Use JavaScript to obtain the date and time information you need to trigger the timer event. If you need to make this change, do so before upgrading process assets.

User attribute definitions - predefined lists

When you create user attribute definitions with a predefined list of attributes, the values established for the predefined lists do not export from Teamworks 6. You can re-create these user attribute definitions in IBM BPM during the development migration phase.

Versioning

If you created multiple versions of process assets in Teamworks, these items were stored internally with autogenerated unique names, which were displayed as version identifiers in Teamworks Authoring Environment. When you migrate these process assets, they are displayed using their previous internal names.

Use either of the following strategies to handle versioned items that have been imported from Teamworks to IBM BPM:

• Continue working with the versioned items as they appear when imported.

• Create a track for each version of the process.

The first strategy requires the least effort during the development migration phase, while the second strategy may be helpful for ongoing development after the migration project is complete.

Do not rename versioned items before upgrading process assets because names are significant in Teamworks. However, you can rename items in IBM BPM after you migrate process assets and move them into different tracks. Names need only be unique for items of the same type within the track for the process application.

Some types of items were not versioned in Teamworks, specifically variable types and tracking groups. Versioned process assets can share these unversioned items in IBM BPM only if the versioned assets are located in the same process application track.

Therefore, different versions of other process assets can share these items in IBM BPM only if the different versions remain in the same process application (even if they are in separate tracks).

To create tracks for versioned process assets in IBM BPM, follow these steps:

1. Import process assets into IBM BPM.
2. Move items that are shared by multiple processes or versions into one or more toolkits.

3. Create a track for each process version that was defined in Teamworks.

4. In each track, delete process assets that do not correspond to the version that the track represents, leaving only the items appropriate for that version.
5. Take a snapshot of each track before deploying it.

Visible in search

In IBM BPM, the BPD property, Visible in search, is replaced with an equivalent property: Available in search. To retain the same functionality after you migrate, you must manually enable any Available in search properties for BPD variables that had Visible in search enabled. The new property works like the old one. However, you should perform appropriate testing after you migrate process assets to ensure that Process Portal searches still work as you expect.

: Upgrade Readiness Check