Generic Camel Endpoint Application

The generic Camel endpoint allows you to invoke an endpoint defined in Apache Camel. Generally this endpoint is used to integrate with external systems. For example, send JMS messages or invoke a system. It allows you to send and/or receive a Camel message to/from any Camel endpoint from within a process. Hereby process data can be passed as parameters to the Camel request message stored in the header and/or body. On the other hand process data can also be populated from a Camel response message by taking values from the header and/or body.

Viewing and Editing Properties

Following properties should be specified:


Figure: Generic Camel Endpoint Application - Properties

Parameters

You can define parameters to access the data associated with the application. You can specify multiple In or Out access points for the Camel Endpoint to invoke the web service. Click the Add icon to add the parameters.

To delete the parameters, select the added parameter and click the Delete icon.

Due to backward compatibility with the Eclipse-based modeler and implicitly created access point, some names of access points defined explicitly are not allowed. The names are oParam1, mParam2, body and header.

Producer Route

All routes based on a Camel Application Type definition are created and started at application startup by the Spring bean. Routes get stopped and recreated after each model deployment even if a process model is overridden. If a model is deleted from the Audit Trail database, all routes based on a Camel Application Type defined for this process model will be stopped and removed from the Camel Context.

The producer route implements the SynchronousApplicationInstance interface and therefore handles the synchronous Send and Send/Receive invocation pattern.

If the Include Process Context Headers check box is selected, the process OID, activity OID and model ID get added to the header of producer route.


Figure: Generic Camel Endpoint Application - Producer Route

If the Include BPM Type Converter check box is selected, two drop down boxes are enabled allowing to specify type conversion for outgoing messages (send) and incoming messages (sendReceive / synchronous).

Examples:

1- Converting from CSV format to structured data:

In the following example, the CSV input will be converted to the structured data specified in the Parameters tab using fromCSV sub-command

firstName,lastName,salary,DOB
Peter,Adam,2000,03/11/1988

The first line in the CSV input contains the headers. It's required by the converter to know how to map the CSV columns to Structured data fields. Below The structured data output:

Structured data

Figure: Employee Structured data

Retries

The configurable retry mechanism provides the facility to retry the operation in case the target service is temporarily unavailable.

For more information, please refer to Retry Mechanism of Non-interactive Applications section of the Applications chapter.

For example, you have added an application to the model. In the Property page of the application, you can enable the retry, specify number of retries and time between retries. However, note that maximum 10 retries and 60 seconds between two retries are allowed. So, the application will retry for the defined number of times with a pause of the defined number of seconds, until it has success. If the application still fails after the defined number, it will no longer retry.


Figure: Retries

Consumer Route

The Camel Consumer Application type implements the AsynchrnousApplicationInstance interface and therefore handles the asynchronous Receive and SendReceive invocation pattern.

If the Include BPM Type Converter check box is selected, a drop down box is enabled allowing to specify type conversion (from XML, JSON or CSV) for incoming messages.


Figure: Generic Camel Endpoint Application - Consumer Route

if the inbound conversion is FromXML, the route will include the following BPM Type Converter TO endpoint between activity find and activity complete endpoint:

<to uri="ipp:data:fromXML"/>

Configuration


Figure: Generic Camel Endpoint Application - Configuration

Invocation Behavior

The following combinations are supported:

Send/Synchronous

Once the activity instance is activated it sends a message to any Camel endpoints as defined in the Producer Route definition. No response is expected so the activity instance completes immediately and the process moves ahead. The sending message can carry process data as per data mapping definition. There are one or more TO endpoints defined for the Producer Route definition. There is no Consumer route definition defined.

Example

After the Camel message is sent and any synchronous TO endpoints executed, the activity instance is completed and the process moves ahead. Hereby any synchronously executed endpoints are part of the existing transaction initiated by IPP. The application instance:


Figure: Example - Send/Synchronous

Sample Use Cases

SendReceive / Synchronous

Once the activity instance is activated it sends a message to any Camel endpoint as defined in the Producer Route definition. A synchronous response is expected and the same thread handles it. After the response is received the activity instance completes and the process moves ahead. The sending message as well as the received response can carry process data as per data mapping definition. There are one or more TO endpoints defined for the Producer Route definition. There is no Consumer Route definition defined.


Figure: Example - SendReceive/Synchronous

After the Camel message is sent and any synchronous TO endpoints executed, OUT data mappings are evaluated. The activity instance then completes and the process moves ahead. Hereby any synchronously executed endpoints are part of the existing transaction initiated by IPP. The application instance:

Sample Use Cases

SendReceive / Asynchronous

Once the activity instance is activated it sends a message to any Camel endpoint as defined in the Producer Route definition. The activity instance is automatically moved into hibernated state. Once a Camel message is received as per Consumer Route definition, the activity instance is completed and the process moves ahead. The sending message as well as the receiving message can carry process data as per data mapping definition. There are one or more TO endpoints defined for the Producer Route definition and the Consumer Route definition. At runtime the application instances behaves such as described in Send/Synchronous respectively Receive/Asynchronous sections.


Figure: Example - SendReceive/ASynchronous

The application instance:

The receiving component (combination of ipp:activity:find / ipp:activity:complete):

Sample Use Cases

Receive Asynchronous

Once the activity instance is activated it directly goes into hibernate state waiting for an incoming message. Once a Camel message is received as per Consumer Route definition, the activity instance is completed and the process moves ahead. The receiving message can carry process data as per data mapping definition.

There are one or more TO endpoints defined for the Consumer Route definition. There is no Producer Route definition defined. Hereby any synchronously executed endpoints as well as the following activity thread are part of the existing transaction initiated by Camel. The application instance moves activity instance into hibernate state.

The receiving component (combination of ipp:activity:find / ipp:activity:complete):

Sample Use Cases

In all cases, you need to ensure that the Camel Components used in the Tags are part of your Runtime Environment setup. By default, the following Camel Components are available:

Detailed description of each component could be found in the Camel site.

Comments

Click the Comments tab to add comments for the application. To add the comment, specify the comment in the text box and click Submit. The newest comment gets displayed at the top of the table. To delete the comment, select the comment and click the Delete icon. The user, who has submitted the comment, only that user can delete the comment. If the other user selects the comment or no comment is selected, the Delete icon remains in disabled state.


Figure: Comments

Correlating Camel Message to Activity Instance (Consumer Route)

In cases where a Consumer Route is defined (sendReceive / asynchronous and receive / asynchronous) the activity instance needs to be found that is completed on receiving the Camel message.

If the Consumer Route definition contains the <to uri="ipp:direct" /> directive, the same will be replaced by:

<to uri="ipp:activity:find?dataFiltersMap=$simple{header.ippDataFilterMap}&expectedResultSize=1" />
<to uri="ipp:activity:complete" />

If the Consumer Route definition does not contain the directive, the find and complete need to be added explicitly. The find directive is responsible to find the activity instance to be completed. Per default it refers to a Map in the header which contains key/value pairs of process data values taken to filter out activity instances by process data. The expectedResultSize URI parameter indicates how many activity instances are expected to be found. The default would be 1, which means that exactly one activity instance is expected to be found. If more or less are found an UnexpectedResultException is thrown. A value of -1 or the absence of this URI parameter defines an unlimited result size expectation. In such a case each activity instance that is found and matches the filter will be completed. This is especially useful in scenarios where many activity instances are waiting to be notified by one and the same request (For example, request for up-to-date price feeds to calculate fund values).

Note that Before an activity instance is completed as part of the ipp:activity:complete TO endpoint, it's checked if the activity instance is based on an activity to which a Camel Application Type is bound to and if the Camel Application Type is the one that has defined the Consumer Route the current Camel message has been triggered for. If the activity instance does not match, it will be ignored and not completed. This mechanism avoids that any activity instances are completed that do not have the specific Camel Application Type assigned.

The ipp:activity:find and ipp:activity:complete TO endpoints only work if an IPP context has been established. For a Producer Route this is always the case, since it runs inside of IPP. For a Consumer Route it's required to specify an ipp:authenticate:setCurrent TO endpoint with proper credentials of a system user as a very first TO endpoint. Hereby the actual credential values could also be derived from configuration variables.

There are multiple ways to address the correct activity instance to be completed by adding certain header fields to the Camel message.

For the following cases, when we use corelation it should always use activity ID, process ID and data of the same consumer application. In this case only consumer activity will get completed. For example, when we corelate an activity using process ID, activity ID and data, the activity found should be same as Consumer activity for which consumer route is activated. If we give any other activity say DummyAct then in consumer route it will find the DummyAct activity, which won't be useful and no action will be taken on that found activity. In this case, the consumer activity will remain in hibernated state.

Correlate by activity instance OID

The OID of the activity instance is part of the message header with key ippActivityInstanceOid. The activity instance OID is unique and can therefore be used to identify the activity instance to be completed.

Correlate by process instance OID and activity ID

The OID of the process instance and the ID of the activity is part of the message header with keys ippProcessInstanceOid and ippActivityId. Theoretically this combination is not unique, since depending on the process topology there might be more than one activity instance that belongs to a certain activity and process instance. The expectedResultSize parameter can be used to ensure that an exception is thrown in case more than one activity instance is found.

Correlate by process ID, activity ID and process data

The ID of the process, the ID of the activity and a Map containing values of various process data are part of the message header with keys ippProcessId, ippActivityId and ippDataFilterMap. The Map can contain one or more key/value pairs of process data which filter out the list of activity instances searched for. Usually the data map contains on unique business identifier (e.g. Customer ID) but could also contain multiple values to combine business identifiers (For example, Customer ID and Transaction ID).