These release notes describe new features, known issues, and other information related to the current Cleo Clarify 5 release.

Note:  This release is available as a new installation only. Currently, there is no Product upgrade or migration path from Clarify v4. However, existing Projects (those created in Clarify v4) can be upgraded to work with Clarify v5. See below, or you may contact Technical Support at +1 815-282-7894 or    1-866-444-CLEO (2536) for more information.

If using previous Clarify Projects

If you are currently using Clarify 4.x and would like to use those projects in Clarify 5, they must be manually upgraded in order to work with the v5 Studio and Server. To do so, use the Upgrade project configurations menu option (shown here) for each Project to upgrade from your 5.x workspace.

Dependencies

There are dependencies between the v5 Studio and Server. For this release’s functionality to operate fully, both server and studio must be at v5.  Never mix deployments! 

For Fresh Installs

Refer to the installation instructions provided in the Getting Started with the Cleo Clarify v5 Server/Studio install guides, available from the Support Portal on cleo.com.

What’s new in this current release

Clarify 5 represents a significant technical upgrade to the platform. New features and enhancements made to Ruleset and Business Process functionality form the basis of these changes, along with tech stack upgrades and improved deployment scalability.

Overview

Improvements to Ruleset functionality now allow for many-to-many transformations from a single Ruleset, since multiple source and targets can be defined. With this functionality, you can:

• build multiple request bodies for different APIs using one Ruleset.
• use multiple APIs to build a single document.
• use the data from a single source document to call multiple APIs.

New Business Process (BP) tasks have been created for easier API integration, providing the ability to read response data and create request data without necessarily using a Schema and Ruleset.  With new control flow BP tasks such as If/Then/Else, or For Each, you can retrieve data from simple API responses and then use it to call additional APIs.

An example could be the use of an API to retrieve a list of IDs. Using a For Each Business Process task, you could have Clarify loop through the list of IDs and then perform resulting actions – calling additional APIs to retrieve data associated with those IDs, and then possibly updating records using an API, as just one possibility.

The next sections of these Release Notes provide additional information on these features.

Ruleset Enhancements

The following enhancements have been made to current Ruleset functionality.

StorageNode variable type an option in Ruleset Methods

In Clarify, a StorageNode represents data that may be defined by a Schema. The StorageNode variable type can be used as a source and/or target for a Ruleset Method. This means that the Ruleset Method can now transform data that is created/retrieved within the Ruleset itself. This data may use a different Schema than the Ruleset’s source and /or target Schema.

Many-to-many Rulesets now possible using Methods

In previous versions, Rulesets were limited to a maximum of three Schemas: Source, Target, and Update. Now we can include additional Schemas by using Methods and StorageNodes. This allows you to transform more data without having to build multiple Rulesets to do so.

In addition to being able to define a StorageNode as the Source/Target of a Method, a user can define multiple sources and targets for a Method. This means that a user can map data from many sources to many targets within one Method. Rulesets can be used to produce multiple outputs in different formats. Many-to-many transformations are now possible using Ruleset Methods. Previously, this would have required several Methods and possibly additional Rulesets.

The Method Wizard has also been enhanced to allow for the selection of multiple Sources and/or Targets.  At least one Source is required.  Selecting the StorageNode type will present Schema selection pages similar to those used when creating a Ruleset. When you select a StorageNode, you will also define the syntax and select the Schema.

Mapped highlighting works for Ruleset Methods

Map highlighting is now working for Methods.  You can now select a Rule and see tick marks in the Schema views which correspond to mapped fields in the selected Rule.

Additional validation over changing Transformation Connectors

Now that a Ruleset Method may have multiple StorageNodes and may require multiple Transformation Connectors, the Transformation Connector can be modified per StorageNode. There is now additional validation over Connectors in the Properties view’s Runtime Options section in the Ruleset editor. This validation helps ensure a compatible connector is selected. 

Additional information can be found in the Designing Integration Solutions | Transforming the Data section the Product Help.

Business Process (BP) Enhancements

The following new types can be used as parameters and variables in the Business Process editor.

• Dictionary: A collection containing key value pairs.
  • Tasks include: Create, Get, Has Key, Keys, Values, Put, Remove, and Size.
• List: A collection containing an ordered list of objects.
  • Tasks include: Create, Get, Add, Remove, Last, and Size.
• JSON: Data that is structured in the JSON format.
  • Tasks include: Read from Create, Type, Get, Set, To Dictionary, To List, and To StorageNode.

New control flow tasks

Several new control flow tasks (i.e. a task composed of several other tasks) are available that provide easier data looping and conditional constructs. The editor has also changed to reflect this structured flow. New tasks include:

For each: For each item in a list, a specified task is executed.

Do while: Executes a task while a specified condition is true. The specified task is executed before the condition is checked. This means that the specified task is always executed at least one time.  Then the condition is checked.  If the condition is true, then it executes again (then the condition is checked again). And so on.

While do: While a specified condition is true, a specified task is executed. The condition is initially checked before the given task is executed.  This means that the condition is checked first before the task is performed. So, if the condition isn't immediately true, then the task is never executed.

If/Then/Else: (Shown here) If a given condition is true, a specified task will be executed in the “then” block. If the given condition is false, the specified task will be executed in the “else” block. In the example below, different Business Processes will execute based on the result of the initial “If” statement. 

Using Pass/Fail Parameters with Control Flow tasks

Task labels and pass/fail parameters can still be still used to control the sequence of logic in a Business Process. While task labels and pass/fail parameters can be used at the control flow task level (If/Then/Else, for example) they cannot be used by the sub-tasks contained within control flow tasks themselves.

Force Step Failure task (typically used with If/Then/Else)

The Force Step Failure task can be used to force the entire step that it is contained within a control flow task to fail. When using control flow tasks, if a singular task does not complete successfully, the overall control flow task (If/Then/Else, for example) does not necessarily stop nor appear as failed in the Auditor.  By using the Force Step Failure task, an optional error message can be provided when the task is executed (thereby providing better troubleshooting).

For example, in the Business Process below the Force Step Failure task has been included within a While Do task. If the ReadLocationsFA (File Adapter) task fails, then the entire step fails, and an error message can be made to appear in the Auditor. 

Better task labeling

Actual names of Business Process tasks have been relabeled for better readability.  While new names appear on the left, the older legacy name is still shown in parentheses to the right, as shown below.

Both names are searchable in task filter.

Additional information on these Business Process enhancements can be found in the Designing Integration Solutions | Processing the Data | Business Processes section the Product Help.

Adding an AbstractTask

An AbstractTask is an abstract Java class that can be extended to add custom tasks to the Business Process task library.

To create a new task:

1. In the src folder of a Studio project, right-click -> New -> Java Class
2. Extend AbstractTask
3. Add an execute method
4. Wrap arguments using Variable interface
5. Return values should be specified as output arguments

The new task should now be available when adding a step to the script section of your Business Process.

Miscellaneous

The Business Process Diagram Editor is no longer available in this version of the Studio. 

Updated Tech Stack

The following software components have been updated.

• Java updated to 8.0_202 (was 1.7.0_51)
• Eclipse updated to 11 (was 3.8)
• Xtext updated to 17.1 (was 2.3.1)
• Akka updated to 5.16 (was 2.4.20)
• Subclipse (replaces Subversive as SVN client in Studio)

Note: certain Database drivers will require updating if using an earlier version of Java.

Improved Deployment Scalability

Improved deployment scalability means more Projects can be deployed than had been the case for earlier Clarify server versions. There is no change in user experience or deployment processes.

Known Issues

The following known issues and related workarounds apply to this current Clarify release.

• If closing the Studio or switching workspaces with open Ruleset editors, the next time that workspace is opened those Rulesets must be closed and reopened; this is so that the types of source and target Schemas will correctly reload.
• The new Business Process editor won’t show an error in the Script section when no tasks have been created (as it did in earlier versions). While an error will appear in the Problems tab, it might not be apparent to the user should a deployment error occur (i.e. trying to deploy a blank Business Process).
• When adding multiple control flow tasks to the Business Process editor, the columns to the far left of the Script section my shrink to the point that error and navigational icons disappear.

Cleo Products Compatibility

Please be aware of the following compatibility between the different Cleo products and this current Clarify release.

Cleo Dashboards

• 3.2 is required for full compatibility with the Clarify v5 server.
• 2 is the minimum required version for use with a Single Server.

Cleo Harmony or Cleo VLTrader

• Recommended: 6
• Minimum: 4.1

Cleo VLProxy

• 8