Integration Link Versioning

When calling an Integration Link from a Business Object, you must select a Version Filter. This filter applies to any further Business Objects (e.g. a Script Function) used during the Integration Link execution.

Once an Integration Link is activated, all Process instances calling it will trigger the execution of the activated version. This happens regardless of the calling Process instance version.

Even though you may have many different Integration Link versions for a specific Integration Link in the Business Object repository, only one version will be running. This running version will be used by all Process Instances regardless of when the Process Instancesand the Integration Links were started were started.

Here is an example Integration Link:

If you start this Integration Link, all Process Instances will use THIS processor chain.

Most important to note is that the Return IntegrationLinkDemo:SimpleScript() script is executed for all calling Process Instances, regardless of when they were started. This is one of the key features of the Integration Link.

Integration Link Version Filters

In your Process you use the Integration Link Task:

The Version Filter property is used in the Integration Link during call execution to select the referenced Business Objects.

Important : This property is NOT used for selecting the Integration Link version.

Another common misconception is that the version filter selects the Integration Link version. Again, be aware that there is only one version of an Integration Link running at any time for all Process Instances.

So, how does the Version Filter property impact execution of the Integration Link?

Same Version (Inherited)

In this case, the Version Filter of the Process Instance is used to select Business Objects. In the example above, it is used to select the definition of the Script Function SimpleScript. This allows old Processes to work with the mappings from/to Process structures that were 'active' when the Process Instances were created.

This approach has the following drawback: if the signature of the script function changes and the Integration Link uses that new signature, old Process Instances call the function with the wrong number of parameters. This happens because the version filter that is applied selects an old script function version which does not have the same number of parameters. It leads to an exception, and possibly to a suspended Process.

Newest Committed Version (Timestamp)

In this case, a timestamp filter with the current system time is created. The filter can then be used to select Business Objects. This allows old Processes to work with the latest/newest mappings from/to Process structures.

This approach has the following drawback: The latest script function implementation is always called, therefore there are no signature mismatch problems. However, the structures which are returned to the Process might not be 100% compatible with the old model that the calling Process Instance requires.

Summary

Following is a summary of the two approaches explained above:

Version Filter	Same Version (inherited)	Newest Committed Version (Timestamp)
Description	Version filter of the Process instance in which the Integration Link was called. Selects the version of other Business Objects according to the time at which the Process instance was started.	Timestamp Filter with the current system time. Selects the last committed version of other Business Objects at the time the Integration Link is called.
Pros	Allows an old Process instance to work with the mappings from/to process structures that were "active" at the time that Process instance was created.	Allows an old Process instance to work with the newest mappings from/to process structures.
Cons	If the signature of a Script Function changes and the Integration Link uses that new signature, old process instances call the function with the wrong number of parameters. The Version Filter applies to the old Script Function version, which does not have the same number of parameters. It leads to an exception and may suspend the Process instance.	Always calling the latest implementation of Script Functions avoids signature mismatch problems. However, the structures which are returned to the process might not be 100% compatible with the "old" model that the calling Process instance requires.
Recommended use case	|Large expected service structure changes compared to process model changes. For example, a new service still under development means many potential changes. The Same Version filter applies the conversion strategy that was built specifically for the calling Process instance's version.	Small expected service structure changes compared to process model changes. This strategy gives you the most control over how structures are converted as the same strategy is used for every calling Process instance. Fixes can be applied easily by changing the Script Functions and Integration Link involved.

Note: If you need to call different versions of an external service for different Process instances, this cannot easily be done using Integration Links. Integration Links are best suited to deal with non-versioned services.

Example and Demo

As a simple demo we have created a Package (note this was created in Appway 7) with two Processes, NewestVersion and SameVersion. Both Processes are identical, except for the version filter on the Integration Link function.

The Process begins with a Script Function which sets the version filter of the Process to 'now': ProcessInstance().setVersionFilter(VersionFilter('TimestampFilter'));

Why are we changing the Process Instance version filter? The reason is because when you start the Process from the Process Editor, the Process Instance starts in 'Head' mode. Starting both Instances in 'Head' mode would mean there would not be any difference when we later commit a newer version of the SimpleScript function. Remember: When a user starts a Process from the Workspace, that Process Instance gets a timestamp. Based on this timestamp, a committed version filter is applied to the Instance.

The Integration Link is then called to run SimpleScript() and return the result.

Here are the steps to follow:

1. Import the IntegrationLinkDemoPackage, and start the Integration Link from the Data & Integration tab.

2. Start the NewestVersion and SameVersion Processes from FNZ Studio Composition. They both display the following output:

3. Edit the SimpleScript to return Version 2 instead. Save and commit.

4. Go back to each of the running Processes and click the Redo button.

   • The NewestVersion Process is now calling the 'Newest Committed' version of the SimpleScript function: It's not using the Version Filter of the Process Instance.

   • The SameVersion Process is using the version filter of the Process Instance to select Business Objects. The version filter was set to 'Timestamp' before you made the new commit, so it does NOT get the latest version of the SimpleScript (and still returns Version 1).

Recommendations

We recommend that you discuss and select the most suitable strategy with your solution architect .

If the 'service structure' changes are small compared to the 'process model' changes, consider using the Newest Committed Version filter:

• This gives you more control over how structures are converted as the same strategy is used for every single call.
• Fixes can be applied easily just by changing the involved script functions and Integration Link.

If 'service structure' changes are significant when compared to the 'process model' changes, consider using the Same Version filter. An example situation would be if a service is new, and still under development.

• The Same Version filter takes the specific conversion strategy which was built for the specific Process Instance version.