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
  • Parameters
  • Producer Route
  • Consumer Route
  • Configuration
    • Invocation Behavior
  • Comments
• Correlating Camel Message to Activity Instance (Consumer Route)

Viewing and Editing Properties

Following properties should be specified:

Figure: Generic Camel Endpoint Application - Properties

• UUID - A unique identifier ID gets generated as an identifier for client server communication
• ID - An ID generated automatically based on the application name. If element with the same name exists then during ID generation, a numerical suffix gets added to the ID. If the element is renamed, the ID gets regenerated.

The UUID and ID options are displayed only when you switch to Integrator profile.

• Application Name - Specify name of the application
• Description - Specify the description
• Public Visibility - By default, this check box is selected. It indicates that the element is visible and available for reference from any other model.

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.

• Body Input Access Point - By default, None is selected. When you select Body Input access point then the data value will be in the body of the exchange. All other IN access points will be set to the header of the exchange.
• Body Output Access Point - By default, None is selected. When you select Body Output access point then the data value will be in the body of the exchange. All other OUT access points will be set to the header of the exchange.

The parameter Name, Direction and Data Type should be defined to populate the above two fields.

• Name - Specify name for the new parameter
• Direction - Select direction for the data from the Direction drop-down list. The Camel Application Type automatically determines if the application type is send only/or send and receive. If at least one out mapping is provided then application is considered send/receive. If no out mapping provided the application is considered as send only. Following options are provided:
  • In - For read access
  • Out - For write access
• Data Type - Following data types are supported:
  • Primitive - If you select Primitive data type, you need to provide Primitive Type.
  • Structured Data - If you select structured data, you need to provide Structure Type. It also lists structured types from other models.

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

Consumer Route

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

Figure: Generic Camel Endpoint Application - Consumer Route

Configuration

Figure: Generic Camel Endpoint Application - Configuration

• Camel Context - Specify name of the camel context file
• Invocation Pattern - A Camel application can follow the invocation pattern of the following type:
  • Send - A Camel message is sent to any Camel endpoint. No response is expected. The activity instance is completed after the message is sent and the process moves ahead.
  • Send/Receive - A Camel message is sent to any Camel endpoint. A response is expected either synchronously or asynchronously. After the response is received, the activity instance is completed and the process moves ahead.
  • Receive - No Camel message is sent. The process stops waiting for an incoming Camel message as per Consumer Route definition. Once the response is received, the activity instance is completed and the process moves ahead.
• Invocation Type - Following invocation types are provided:
  • Synchronous - The same thread that sends the Camel message is receiving the response.
  • Asynchronous - A different thread from the one that sent the Camel message is receiving the response.
• Additional Bean Specification - You may use references to Spring Beans in your routes. These Spring Beans are either expected to be defined externally in your runtime environment or can be defined in the Additional Bean Specification Text Area:

  
  Figure: Bean Specification

  Hereby, the byte code of com.siriussuper.order.OrderCache is expected to be available in your runtime deployment, e.g. by adding a Utility JAR file with this byte code.

Invocation Behavior

The following combinations are supported:

• Send/Synchronous
• SendReceive / Synchronous
• SendReceive / Asynchronous
• Receive Asynchronous

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:

• evaluates IN data mappings regarding which process data goes into the body and which process data goes into the header (see: data mapping logic).
• executes the route without evaluating any OUT data mappings.
• completes the activity instance.

Figure: Example - Send/Synchronous

Sample Use Cases

• Sending a JMS (fire and forget).
• Sending a notification E-Mail

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:

• evaluates IN data mappings regarding which process data goes into the body and which process data goes into the header (see: data mapping logic).
• executes the route.
• evaluates OUT data mappings regarding from where process data is taken (body / header) (see: data mapping logic).
• completes activity instance.

Sample Use Cases

• Spring bean integration
• Services Connector integration
• REST Call invocation

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:

• evaluates IN data mappings regarding which process data goes into the body and which process data goes into the header (see: data mapping logic).
• executes the route
• moves activity instance into hibernate state.

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

• receives inbound Camel message
• looks up activity instance by given search parameters.
• evaluates OUT data mapping.
• completes activity instance.

Sample Use Cases

• JMS request/response pattern
• E-Mail request/response pattern

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):

• receives inbound Camel message.
• looks up activity instance by given search parameters
• evaluates OUT data mapping.
• completes activity instance.

Sample Use Cases

• Receiving a REST call
• Receiving a feedback E-Mail.
• Receiving a timer event.
• Receiving a JMS / File, etc.

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:

• bean
• browse
• class
• dataset
• direct
• file
• language
• log
• mock
• properties
• ref
• seda
• test
• timer
• validator
• vm
• xslt
• spring-event

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).