Conversion of deprecated functions in imported process applications and toolkits

To prepare a process application to be deployed to multiple device types, ensure that its artifacts and the artifacts in its corresponding toolkit dependencies are suitable for use on both mobile and desktop devices.

IBM® BPM provides functions that enable you to convert deprecated coach views from artifacts that were built in IBM BPM versions earlier than V8.6.0 into coach views from the BPM UI toolkit.

You can convert coach views from the deprecated Coaches and Responsive Coaches toolkits into BPM UI coach views that are based on newer technologies and can be used to build applications that run on multiple device types.

The conversion ensures that every deprecated coach view has at least one replacement in the BPM UI toolkit. Where one deprecated coach view can convert into different BPM UI coach views, the configuration options that you specified before conversion determine the output after conversion. For more information about the mapping between the deprecated functions and their corresponding functions after conversion, see Mapping deprecated functions to BPM UI functions.

You do not have to convert a process application or toolkit that is created in IBM BPM V8.6.0.
- Build the new process application or toolkit by using only mobile-ready coach views from the BPM UI toolkit for all the new coaches and coach content.
- Avoid mixing non-responsive, responsive deprecated, and BPM UI coach views in the same coach.
Convert a process application or toolkit that you imported from an IBM BPM version earlier than V8.6.0. The conversion UI is enabled for process applications or toolkits that depend on the deprecated Coaches or Responsive Coaches toolkits, or on the Content Management toolkit.
In the conversion process, you replace the deprecated coach views in all or the specified artifacts that belong to the process application or toolkit with BPM UI coach views.
- All the coach view instances in the artifacts selected for conversion remain intact and unchanged.
- All the references to deprecated coach views in the Coaches and Responsive Coaches toolkits are converted into BPM UI coach views.
- All the references to deprecated Content Management coach views are converted into corresponding coach views from the same Content Management toolkit.
- Some but not all the configuration options, bindings, implemented services, and values for responsive device settings that are defined for a converted coach view are preserved after the conversion.
Remember:
- This is a best-effort conversion that ensures that each deprecated coach view has at least one replacement in the BPM UI toolkit. However, the conversion does not guarantee that the behavior, the configuration options, bindings, and some of the implemented services and responsive device settings of the resulting BPM UI coach view remain identical to those of the original coach view. That is why it is important that you test and reconfigure the BPM UI coach view as necessary to ensure that it works as expected. For example, if the implementation of a specified service in a deprecated coach view is not preserved after conversion, you might need to recreate the service implementation in the corresponding BPM UI coach view.
- Post-conversion configuration is also required for custom JavaScript and CSS code that refers to elements and classes in deprecated coach views. Differences in the CSS code for coach views require that you verify and reconfigure the custom CSS to ensure that the CSS is still compatible with the converted BPM UI coach views.
- If you are using or converting to the BPM UI coach views, you must add a dependency on the System DataV8.6.0 toolkit or a toolkit or process application that has a theme. The BPM UI coach views require theme definitions. The BPM Theme in the System Data toolkit provides these theme definitions and it is the default theme for new process applications.

To plan your way through the conversion, understand how the conversion works and the concepts that are involved in the process.

Artifacts that contain deprecated coach views: For a specified process application or toolkit, the conversion UI lists all the artifacts that directly depend on deprecated coach views from that application or toolkit. The artifact list can include a mix of coach views, heritage human services, and client-side human services whose coaches use deprecated coach views. Depending on your business needs, you can select all the artifacts in the list or only some of them for conversion.

Toolkit dependencies: If the listed artifacts that contain deprecated coach views have toolkit dependencies or include coaches or coach views that have toolkit dependencies, the toolkit dependencies are listed in the Toolkit Dependencies section. The list includes all the toolkit dependencies for the specified process application or toolkit, from direct dependencies to dependencies of dependencies.
Important: Regardless of how simple or complex the hierarchy of toolkit dependencies is, when you convert its deprecations you must always start at the deepest level and follow the described bottom-up conversion strategy while you ensure that you convert all the dependencies.; Note: If the Toolkit Dependencies list includes read-only items, the user that you are logged in as is not authorized to upgrade these dependencies. You can, however, change the version of a read-only toolkit to a snapshot version that was converted and taken by another authorized user. If no such snapshot is available, contact the owners of the read-only toolkit to determine whether they want to convert it themselves or grant you permission to do the conversion.

Bottom-up conversion strategy

Whether you start the conversion from a process application or a toolkit, follow a bottom-up strategy that includes the following main steps:

Remember: Before you proceed with the conversion, take a snapshot of the process application or toolkit.

In the toolkit dependencies structure, go to the deepest level that has no custom toolkit dependencies and start the conversion there.
Convert the deprecated coach views in all artifacts for each toolkit dependency, one level at a time, and work your way up until there are no dependencies left to convert.
Tip: Other users might have already converted some dependency toolkits that your process application depends on. If a converted version of a toolkit exists, upgrade the toolkit to that version directly.
For each toolkit dependency, at every level, follow this process:
1. Check - Check whether a converted version of a dependency toolkit exists:
  - If it exists, skip step 2 and update the version of your toolkit to the converted version.
  - If it does not exist, continue with steps 2 - 5.
2. Convert - Convert the deprecated coach views in all the listed artifacts for that toolkit.
3. Test and customize - Test the results of the conversion in the artifacts and customize where necessary. Retest the artifacts to ensure that they work as expected.
4. Refresh- (Optional) Refresh () to make sure that there are no more artifacts and dependencies left to convert for the current toolkit.
5. Take snapshot - Take a snapshot of the converted toolkit.
Move up one level and, from the dependencies listed under UI Conversion or from the library, change the dependency version to the version of the snapshot that you took.
At the top application level, iterate through steps 2 - 4. Then retest and update the custom artifacts as necessary.
(For the Coaches toolkit only) From the library, remove the application's dependency on the toolkit.
Note: The dependency on the Content Management toolkit is automatically upgraded.

The process application and all its artifacts are now suitable for use on multiple device types. You can resume the development in the process application by using BPM UI coach views and coaches.

Example

The diagram shows a three-tiered hierarchy of toolkit dependencies for a process application, PA1.

Assume that the list of toolkit dependencies for your process application consists of a three-tiered hierarchy:

At the top level, the process application (PA1) has one toolkit dependency: TKT1.
TKT1 depends on TKT2 that depends on TKT3.
At the lowest level, TKT3 has no toolkit dependencies.
No converted version exists for any of the specified toolkits.

Start by converting the deprecated coach views in TKT3, and then convert your way up to the top level by completing the following steps:

In the toolkit dependencies structure, go to the TKT3 level.
Apply the conversion process starting at the TKT3 level:
1. Convert the deprecated coach views in all the artifacts in TKT3.
2. When the conversion is complete, test the results of the conversion in the artifacts and make adjustments where necessary. Retest the artifacts if necessary.
3. (Optional) Click Refresh to make sure that the list of artifacts for TKT3 is clean and there are no more dependencies.
4. Take a snapshot of the TKT3 toolkit that has all the artifacts and dependencies converted.
5. Move up one level to TKT2.
6. In the list of toolkit dependencies for TKT2, change the toolkit version for TKT3 to its snapshot version to remove TKT3 from the list of dependencies for TKT2.
7. From the library, right-click the dependency of TKT3 on the Coaches toolkit and remove the dependency. Repeat this step for TKT2.
Iterate through the same conversion process at TKT2 level, and then repeat the conversion process for TKT1.
With all the toolkit dependencies converted, at the PA1 level iterate through steps a - c. Then retest and update the custom artifacts as necessary. PA1 and all its artifacts are suitable for use on multiple device types.
From the library, right-click the dependency of PA1 on the Coaches toolkit and remove the dependency. The dependency on the Content Management toolkit is automatically upgraded.