Integration Link Business Object

Introduction

The 'Integration Link' Business Object provides an interface between FNZ Studio and external systems. It defines a processing flow for internal or external data. Each Integration Link contains a chain of components which receive data, transform it if necessary, and trigger tasks in FNZ Studio or an external service.

Integration Links implement event-driven concepts. Events can be triggered internally in FNZ Studio, or externally by some other application or the operating system. Integration Links handle an event by processing the event message one component after the other until the end of the link chain is reached.

Integration Links can be used to execute internal tasks from outside, or vice versa.

Using Integration Links as interfaces with external systems bring several advantages:

• Integration flows are managed outside FNZ Studio processes, so that Process business objects only contain business flows. The technical aspects of integration are handled in the Integration Link.
• Integration points are easier to understand, configure and maintain than in hard-coded scripts.
• Integration Links provide a loosely coupled infrastructure for integration, thus reducing the risk of failure and the cost of maintenance. Integration Links handle dependencies between FNZ Studio and external systems such as data format, time and location dependencies.
• Integration Links can be executed asynchronously (see more information in the Integration Link: Avoiding Lock and Long-running Service Conflicts article).

Contrary to other business objects, each Integration Link is started independently of the Processes it is called in. Only a single instance of each Integration Link can run at any time. This means that, if multiple Process instances with different version filters send messages to Integration Link "X", all messages will be processed by the same instance of "X".

Once started, an Integration Link listens for incoming messages. A start message can be generated by an FNZ Studio-internal Process, Catalog or script, or by an external system.

The message is then processed through the chain of components defined by the Integration Link. For example, the original message can be routed, split, filtered, or converted into a different format. Integration Link components can also trigger an internal task (e.g. a Process or another Integration Link) or call an external endpoint (e.g. a REST service). Once the processed message has reached the end of the chain, it forms the Integration Link's output.

The engine executing Integration Links relies on Apache Camel, an open source integration framework based on known enterprise integration patterns.

Design Integration Links

An Integration Link is essentially a message-processing chain. Each Integration Link contains a sequence of elements defining processing steps. These steps are applied from top to bottom to each message sent to the first element of the chain.

There are two main ways to call an Integration Link: Either an external service, or FNZ Studio itself, can produce an event that generates a trigger message:

• Internal events: Executing the built-in function CallIntegrationLink, the Process component 'Integration Link Task', or the Catalog source 'Integration Link'
• External events: For example, an email arriving in an inbox, or a file being copied to a specific folder.

When an Integration Link is called, an "Exchange" object is created and sent to it. The Exchange object is a container for the request message (also referred to as "in-message"), the response message (also "out-message") and a set of properties.

An Integration Link chain always begins with a "Start" component defining the source of the trigger message. This initial trigger element is followed by a sequence of endpoint, routing, translation, or processing steps. These are the various types of components available to build the processing chain:

• Start: Source of the event which triggers the Integration Link
• End: Target of an event initiated by the Integration Link
• Routing: To route or filter messages
• Processor: Message-processing tools for debugging and testing
• Transformation: To convert messages or message bodies from one format into another.

Once the Integration Link has received a message, each step in the chain executes its task on that message. The result of executing the Integration Link is the data returned by the last component in the Integration Link's processor chain. At the end of the chain, the processed message is then sent back to the caller of the Integration Link.

Integration Link Properties

You can configure how each Integration Link behaves in a message exchange, and how it handles errors.

To display and edit the General and Error Handler properties tabs, click on empty space in the editor's Composition Area, or on the Integration Link's name at the top of the editor.

General Properties

The available properties are:

• Name — Name of the Integration Link
• Description — Description of what the Integration Link does
• Message Pattern — Configure which exchange pattern this Integration Link uses:
  • Request - Reply — Produces a response message (in/out)
  • Event Message — Does not produce a response (in only).

Error Handler

The available properties are:

• Activate — Check to activate error handling.
• Type — Error handling strategy (currently only Default is available).
• Redeliver — Check to deliver the message again if an exception occurs.
• max. Redeliveries — Number of times a redelivery is attempted.
• back off Multiplier — Number multiplying the redelivery delay after each retry. If set to 1, the time between each retry remains equal for each further attempt.
• Redelivery Delay — Milliseconds to wait before a redelivery is attempted.
• Attempted Log Level — Priority level of logs about redelivery attempts (DEBUG, INFO, WARN, ERROR, or OFF).Select "OFF" to disable logging.

Example: 'Redelivery' is activated with the following settings:

• max. Redeliveries = 2
• back off Multiplier = 2
• Redelivery Delay = 1000

Behavior in case errors occur while executing the Integration Link:

1. 1st attempt
2. Exception #1
3. Wait 2*1000ms
4. 1st redelivery
5. Exception #2
6. Wait 2*2*1000ms
7. 2nd redelivery
8. Exception #3

No further delivery attempts. The exchange is in exception state.

Scripts in Integration Link Components

Integration Link components can contain scriptable properties used for processing a message. Local and Assigned variables are supported and accessible in all scripts. Variables cannot be inherited in Integration Links.

Depending on their purpose, scripts can also provide access to the Exchange and “in” message.

The return value of a script is automatically put into the “out” message of the current exchange.

The variable definitions are:

• $exchange (org.apache.camel.Exchange)
• $in (org.apache.camel.Message)

For example, this script gets the current message body and converts it into a string. It returns the length of that string.

String $s := TOSTRING($in.getBody());
Return LENGTH($s);

Start Components

Start components define the source of the event which triggers the Integration Link. Select from a list of components at the top of the composition area. There can only be one start component for each Integration Link and it is always at the beginning of the chain (it cannot be moved).
The trigger for an Integration Link can be an event inside or outside of FNZ Studio:

• Internal source examples: Direct call via the built-in function CallIntegrationLink, the Process component 'Integration Link Task', or an internal message queue.
• External source examples: message landing in a JMS queue, incoming email, file uploaded to a specific folder, etc.

Integration Link Start Component

The "Integration Link" start component listens for internal messages generated either by the Process activity "Integration Link Task" or by the built-in function "CallIntegrationLink".

The available properties are:

• Forward Message Asynchronous (Boolean) — Specifies whether the message should be forwarded asynchronously or synchronously. Default Value: True
• Timeout (Integer) — Maximum time waiting for a reply, in milliseconds. Specify '0' for no timeout, but set this value only if you understand the risk of operating an Integration Link without a timeout.

Note: When using a REST or SOAP client component, define a timeout which is larger than the timeout set directly in the REST / SOAP client component (see Set Connection and Read Timeouts for REST). The reason for this approach is that the Integration Link starts a new thread in the background which then performs the REST/SOAP call. If, for example, this REST/SOAP call needs 30 seconds to respond, but the timeout here in the Start component is set to 10 seconds, you cannot catch potential timeouts or other exceptions thrown by the REST/SOAP call. In some cases, you might decide to deactivate the timeout ("0") in the Start component (for instance when using dynamic timeouts in REST / SOAP components), but do so only if you understand the risk.++ Default Value: 30000

• Consumers (Integer) — Number of concurrent asynchronous consumers. Default Value: 5

Directory Scanner Start Component

The "Directory Scanner" start component scans a folder for new files. The scanned folder must be located on a local file system, but must not necessarily be in the FNZ Studio Data Home.

The available properties are:

• Directory Name (String) — Path to the directory to be scanned. Use {DATA_HOME} to reference FNZ Studio's Data Home directory.
• Auto Create (Boolean) — Automatically create missing directories in the file's path name. Default Value: true
• Buffer Size (String) — Write buffer sized in bytes. Default Value: 128kb
• Charset (List) — Select the encoding of the file.

The following properties are available on the Consumer Tab:

• Initial Delay (String) — Milliseconds before polling the file/directory starts. Default Value: 1000
• Delay (String) — Milliseconds before the next poll of the file/directory. Default Value: 500
• Use Fixed Delay (Boolean) — Select to apply a fixed delay between pools. Otherwise, a fixed rate is used. Default Value: false
• Use Done File (Boolean) — Only start reading file if a file with the extension *.done exists. Default Value: false
• Recursive (Boolean) — If a directory, scan for files in all its sub-directories as well. Default Value: false
• Delete (Boolean) — Select to delete the file after it is processed. Default Value: false
• No Op (Boolean) — Select to prevent moving or deleting the file in any way. The operation will also avoid consuming the same files over and over again. Default Value: false
• Pre Move Filename (String (dynamic)) — Set the file name when moving it before processing.
• Move Filename (String (dynamic)) — Set the file name when moving it after processing. Default Value: .done/${date:now:yyyyMMddHHssSSS}-${file:name}
• Move File on error (String (dynamic)) — Set the file name when moving it after processing failed. Default Value: .error/${date:now:yyyyMMddHHssSSS}-${file:name}
• Include Filename RegEx Pattern (String) — Include files for which the file name matches the regex pattern.
• Exclude Filename RegEx Pattern (String) — Exclude files for which the file name matches the regex pattern.

Process Message Queue Start Component

The "Process Message Queue" start component listens for messages from an FNZ Studio Message Queue.

The available properties are:

• Message Queue (List) — Select a process message queue.

End Components

"End" components designate the endpoints of an Integration Link. Each "End" component represents the target of an event initiated by the Integration Link. A target may be internal, such as a Process or another Integration Link. An external system can also be the receiver of an "End" component, such as web services, files, databases, JMS queues, mail servers, etc.
"End" components can be used anywhere and multiple times within a chain of components.

Logger

The "Logger" component writes messages to a logger for development and debugging purposes.

The available properties are:

• Logger (String) — Name of the logger. Default value: com.nm.integrationlink.LoggerEndpoint
• Level (List) — The log level. Default value: DEBUG

Notify Integration Link

The "Notify Integration Link" component sends a message to another Integration Link.

The available properties are:

• Notify (List) — Select the Integration Link for which the temporary queue must be notified.

Notify Process Queue

The "Notify Process Queue" component sends a message to an FNZ Studio Message Queue.

The available properties are:

• Message Queue (List) — Select a Process message queue.
• Recipient (Expression) — Name / ID of the recipient. This is an arbitrary name which will be recognized by the Process instance reading the message from the queue. The information can be used to verify if a message is really intended for a specific Process instance.
• Recipient Workflow Instance ID (Expression) — Workflow instance ID of the recipient.

Routing Components

"Routing" components are related to message routing, filtering, etc. When a message is received by an endpoint, it is forwarded to the next element in the Integration Link chain. If the element is a routing component, the message will be inspected and either further processed, consumed, or sent to multiple recipients.

Message Filter

The "Message Filter" component decides about further processing of the exchange.

Message Multicaster

The "Message Multicaster" component sends the message to the given target Integration Links. It then aggregates the results of these Integration Links into one.

Message Router

The "Message Router" component routes the exchange to specific target Integration Links, based on decision expressions.

Transitions Tab

Processor Components

"Processor" components are used for general-purpose processing of messages.

Asynchronous Processor

The "Asynchronous Processor" component executes the subsequent components in an asynchronous way.

Copy File

The "Copy File" component copies files that have been scanned with the "Directory Scanner" start component to a target folder

Scripted Processor

The "Scripted Processor" component executes a script, the result of which is the new message content.

Splitter

The "Splitter" component splits a message into one or more sub-messages. It then executes the rest of the Integration Link chain sub-message by sub-message. Once all sub-messages have been processed, their results are aggregated back into one output.

Throttler

The "Throttler" component applies throttling to the Integration Link chain. It ensures that a specific endpoint does not get overloaded, or does not exceed an agreed SLA with some external service.

Transformation Components

"Transformation" components convert messages from one format into another. It allows you to transform external data into FNZ Studio data (e.g. a Data Entity), which can then be used in FNZ Studio. On the other hand, FNZ Studio data can also be converted into formats that can then be forwarded to external services.

For example, an external CMS system holds data about John in an XML structure. A Process needs to access John's address data as an "Address" Data Class. The XML version of the address data must be translated into an instance of an "Address" Data Class. An Integration Link can execute the conversion with the "Convert XML to Data Entity" component.

Body To String

The "Body To String" component converts the message body into a String. It does not require any property settings.

Convert Data Entity To XML

The "Convert Data Entity to XML" component transforms any Data Entity (e.g. Data Class or Primitive Type) into XML data.

Convert XML to Data Entity

The "Convert XML to Data Entity" component transforms XML data into a Data Entity.

Scripted Translator

The "Scripted Translator" component executes a script that translates the structure of the in-message body.

Workflow Message Data Extract

The "Workflow Message Data Extract" component extracts the data property from a process message that is stored in the exchange body.

Additional Components

The following extensions contain additional components for Integration Links:

• Mail extension (IMAP, POP3, SMTP, email conversion and attachment handling)
• Web Services extension ( SOAP clients)
• Integration Link Components extension (Active MQ listener and notifier). See documentation.

Manage Integration Links

Only one instance of an Integration Link can be active at any time. FNZ Studio Composition's Data&Integration module lets you start, stop or restart Integration Links. You can also test them or view details on their use such as exceptions or number of invocations. Moreover, you can configure the behavior of Integration Links in the Administration tool.

Activation and Versioning

Integration Link Business Objects differ from Process or Screen Business Objects in that they only have one running instance at any time. Each Integration Link must be started from the Data&Integration module, independently of other Business Object versions.

The running version of an Integration Link is used by all Process instances, regardless of when they were started, and regardless of when the Integration Link was started. For example, if multiple Process instances with different version filters send messages to Integration Link "X", all messages will be processed by the same instance of "X".

The decoupling of Integration Link versions with that of other Business Objects is due to the Integration Link's nature as an interface with the outside world. External systems do not offer versioned endpoints corresponding to FNZ Studio version filters. Integration Links provide ways to handle changes in external systems.

Configuration

You can configure which version of Integration Links must be started, and whether to start them automatically upon committing. You can also specify a list of exceptions which override standard exception handling.
These configurations apply to all Integration Links. They cannot be set differently for each Integration Link.
To set configuration properties for Integration Links:

1. Go to System Configuration > Configuration Properties
2. Click on the menu icon in top left corner.
3. Select Edit Server Configuration.
4. Add a line to the configuration file in order to override the default configuration. For example:

nm.integrationlink.autoStartCommitted = true

Integration Link Management

You can manage Integration Links from the Integration Link Management menu available in the Data & Integration module. It provides an overview of Integration Links and another of all components available.

The Integration Links table provides the following information for each Integration Link:

:-----------| :-----------| | | ||Started: active, currently running Integration Link
Inactive: currently stopped Integration Link |Name |Name of the Integration Link |Invocations |Number of times the Integration Link has been called since system start-up |Exceptions |Number of exceptions thrown while executing the Integration Link since system start-up |Description |Description for the Integration Link |Version |Version of the Integration Link currently running:

• Latest Committed / Head: The Latest Committed version is the Head version (no changes made after committing).
• Head: Head version
• Latest Committed: Latest Committed version (there exists a non-committed Head version)
• Committed: Some committed version (there are other newer committed versions than the one currently running).

Note : If you are running FNZ Studio in a cluster environment, the Integration Link Consistency health sensor monitors the consistency of Integration Link states across cluster nodes. See Integration Link Consistency Sensor for details.++

Right-click on a row to make the context menu appear. You can execute the following operations on the selected Integration Link:

|Operation |Description | -------- | -------- | -------- | |Details |Opens a test tool and a view with details about the selected Integration Link (e.g. Camel route, exceptions). |Start |Starts the selected Integration Link (if not already started). By default, the latest committed version is started. See Section 3.2, "Configuration" to set an alternative version filter.
|Restart |Re-starts the selected Integration Link (if already started). |Stop |Inactivates the selected Integration Link (if currently started).
|Open Editor |Opens the Integration Link editor |Commit |Commits the current uncommitted version of the selected Integration Link. |Reset Statistics |Resets the counters for invocations and exceptions.
|Show Dependencies |Displays incoming and outgoing dependencies for the selected Integration Link.

The Components table provides an overview of all available Integration Link components, both built-in and added through extensions:

|Column |Description | -------- | -------- | -------- | |Name |Component name |Description |Component description |Category |Type of component (Start, End, Routing, Transformation, or Processor) |Source |Source of the component: built-in, or name of the extension in which it is contained.

Testing and Debugging

Integration Links include a test tool. You can access it through the Data&Integration module or the Integration Link editor.

• Data&Integration module: In the Integration Links tab, right-click on a row in the Integration Links table and select Details.
• Integration Link editor: Switch from composer to preview mode (Preview tab).

Running Tests

If the Integration Link is not yet started, or is started in an older version, a (Re-)Start button is displayed. After (re)starting, the Integration Link runs in Head version and be can be tested.

The test tool allows you to specify an initial message body and any potential assigned variables for the Integration Link. Click Call Integration Link to execute the Integration Link with these parameters.

The execution results are then displayed in the test tool's right panel. In the example above, an exception occurred and the result is the exception message. The details of the last 10 exceptions are listed in the Details tab of the test tool.

Test Details

The Details tab lists general information about the Integration Link.

|Test details |Description | -------- | -------- | -------- | |Id |ID of the Integration Link |Name |Name of the Integration Link |Description |Description of what the Integration Link does |Invocations / Errors |Total number of times the Integration Link was invoked / total number of errors since the last system start |Route |Processor chain defined for this Integration Link based on its components |Camel Route |Same route definition, but including all Apache Camel processors and endpoints used for the route instance |Exceptions |Last 10 exceptions that occurred after calling this Integration Link. Click Clear Exceptions to clear the list

Exception Information

Click on any exception in the Details tab to view more information about the related message exchange and the exception's stack trace.

The Message Exchange Properties section displays information about the exchange object.

Figure 8: Example of message exchange properties

The Exception [x] section shows the stack trace that occurred during exchange processing.

Replacing Integration Links in Packages

Packages may contain many different types of Business Objects, including Integration Links which use the Integration Link (Start Element) start component.

Integration Links are replaced only at runtime, for instance if:

• The CallIntegrationLink function is invoked, or
• The (deprecated) ESBSendMessage function is invoked, or
• The Process contains an IntegrationLink Task.

Note: Replacements for Integration Links are not applied in the following cases, because they do not represent runtime use cases scenarios:

• When tested through the Integration Link 'Details' panel, available at: Data & Integration > Integration > Integration Link Management, right click on any row and click on Details...
• When called from the Integration Link Editor/Preview section:

Best Practices

An Integration Link which listens for external events can be made replaceable by changing its design, for instance by decoupling the 'listening' logic from the logic used to process the messages as shown in the example below:

Original Design:

New Design: 

In the example above, the listening logic (MyActiveMQListener) has been decoupled from the logic used to process a message (MyMessageProcessor). When a new message comes in, the MyActiveMQListener forwards the message to the MyMessageProcessor Integration Link via the NotifyIntegrationLink component. At this point, MyMessageProcessor from Package A can be replaced (because it starts with the IntegrationLink Start component).

Call Integration Links

Integration Links can be called from other Business Objects in various ways:

• Using a script expression anywhere
• From a Process, using the Integration Link Task component
• From a Process, using the Notify Process Queue component
• From a Catalog, setting Integration Link as a source

If your Integration Link's processing chain relies on other Business Objects than the calling one, you need to decide on a Version Filter strategy. This chapter introduces the notion of Version Filters and explains each way to call an Integration Link internally.

Version Filter

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's execution. It does not apply to the Integration Link object itself (see Activation and Versioning).

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's version.

In the example below, the Integration Link's chain contains a script relying on the Script Function ConvertServiceToProcess($response). The Version Filter determines which version of this Script Function will be used during the Integration Link's execution.

You can choose between the same version as the Business Object calling the Integration Link, or the newest committed version at the time of the call.

Select the most suitable strategy for your solution architecture. What do you expect to change least, the structure of external services or the internal process model?

| 1 | 2 | 3 | |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.

Scripted Call to Integration Link

Note: The function ESBSendMessage is deprecated since version 6.0. Use CallIntegrationLink instead.

You can use the built-in function CallIntegrationLink to trigger an Integration Link from any script. The target Integration Link must contain an "Integration Link" start component to receive the trigger message from this function.

CallIntegrationLink($integrationLinkId, $params, $versionFilter, $waitForReply)

Example: Create a new payment order:

Payment $p := new Payment;
$p.accountManager := 'C. Montgomery Burn';
$p.supervisor := 'Marge Simpson';
$p.amount := 1000;
$p.benefactoryAccount := 'Homer Simpson';
$p.beneficiaryAccount := 'Moe Szizlak';
$p.comment := 'Last weak\'s beer bill';

An Integration Link called "Start Payment" can then be called synchronously. The return value of the synchronous call is the value returned by the last component in the Integration Link.

// synchronous call to an integration link
Any $returnValue := CallIntegrationLink('StartPayment', {'payment'=$p, 'correlationId'=UID()}:String, 'HeadFilter', true);

Alternatively, the Integration Link can be called asynchronously:

// asynchronous call to an integration link
Any $future := CallIntegrationLink('StartPayment', {'payment'=$p, 'correlationId'=UID()}:String, 'HeadFilter', false);

The return value of the asynchronous call is a java.util.concurrent.Future object. Its value can later be fetched using the following code:

Any $returnValue := $future.get()

Process Activity "Integration Link Task"

To execute an Integration Link within a Process flow, use the activity component "Integration Link Task". Configure it to call any Integration Link which begins with an "Integration Link" start component.

Figure 11: Process Activity "Integration Link Task"

The following properties can be set for the Integration Link Task component:

|Property |Description | -------- | -------- | -------- | |Name |Name of this process element |Description |Description of what this process element does |Task List Name |Name for this process element if it appears in users' task list, or elsewhere in the Workspace. This field can contain Label objects. |Integration Link |Select which Integration Link must be called |Bind Reply |Specify whether the value returned by the Integration Link must be bound to a data entity |Return Value Binding |Binding expression for the return value (Data Class or Primitive Type) |Return Value Binding |Binding expression for the return value (Data Class or Primitive Type) |Asynchronous |Check if the Integration Link must be executed asynchronously, i.e. the user does not have to wait for a reply. (See note below the table*) |Version Filter |Version Filter used during the execution of the Integration Link to select other Business Objects referenced in its processing chain: "Same Version (inherited)" or "Newest Committed Version (Timestamp)".
Attention: This property is not related to the Integration Link's own version.
See Version Filter for more information. Table 34: Integration Link Task properties

• Note on the 'Asynchronous' property: An asynchronous call with an Integration Link Task does not force the user (HTTP request) to wait, but the process token waits for the Integration Link to complete. Therefore, until the Integration Link execution is completed, the task is not set to Complete, and the token does not move on.

Also consider that, in the Variable Assignment tab, you can enter expressions for variables used in the Integration Link. This tab appears after selecting a specific Integration Link, if it contains any assigned variables.

Process Message Queue

Process message queues can be used for communication between Processes and Integration Links.

First, define a new queue: Go to Solution Maintenance > Processes > Process Messages and select Add Queue from the top left menu.

In an Integration Link:

• Use the Process Message Queue start element for new process messages to trigger the Integration Link's execution.
• Use a Notify Process Queue component to send a message to the queue from the Integration Link's processing chain.

In a Process:

• Use the Message start event or the Receive Message intermediate event to wait for messages from the queue.
• Use the Send Message intermediate event to send a message to the queue.

Catalog Source 'Integration Link'

You can use an Integration Link's response as source data for a Catalog:

1. In the Integration Link, select Integration Link as the start component.
2. In the Catalog, select Integration Link as Source.

Figure 12: Example Catalog with source Integration Link

|Property|Description | -------- | -------- | -------- | |Integration Link Id |Select an existing Integration Link. It will be called when data is requested from the Catalog. |Result Converter Script |This script converts the Integration Link's response to an Indexed Record collection. Make sure that all columns defined in the Output Columns tab are created and assigned to each single record.
If there is no data available, you must return an empty collection, not null.
Example:
//Any $ret is predefined: it is the return value from the Integration Link. In this example, we assume it is a String.<br />//<br />Indexed Record $records := new Indexed Record;<br />Record $r := new Record;<br />//<br />$r.setValue('id', '1');<br />$r.setValue('data', CAST(String, $ret));<br />$records.add($r);<br />//<br />Return $records;

Note: It is possible that a call to an external system via an Integration Link may take some time. To avoid long response times, add a Cache Filter for better usability.

Integration Link Engine

The engine executing Integration Links relies on Apache Camel. Apache Camel is an open source integration framework based on standard enterprise integration patterns.

The Camel API relies on a concept called Message Exchange Patterns (MEP). An MEP defines the messaging style as one-way (InOnly) or request-reply (InOut), i.e. there are IN and optionally OUT messages. This closely maps to other APIs such as WS, WSDL, REST, JBI, etc.

The Exchange API provides two methods to get a message: “getIn” to get the IN message, and “getOut” to get the OUT message.

The diagram below explains how messages are processed:

• The OUT message from each step is used as the IN message for the next step.
• If there is no OUT message, then the IN message is used instead.
• For the InOut MEP, the OUT message from the last step in the route is returned to the producer. In case of an InOnly MEP, the last OUT message is thrown away.

Note for SDK developers: Avoid using “Exchange.getOut” to check if there is an OUT message. “Exchange.getOut()” creates an OUT message if there is none. To verify if an OUT message exists, use “Exchange.hasOut” instead.