Defining and Using a Complex Join Feature

Integration Framework allows flows to be designed with join definitions to enrich events with data from relevant tables.

Complex Join Feature

In the Integration Framework, a join definition is a definition that fetches data from a related application.

The Integration Framework allows flows to be designed with complex join definitions to enrich events with data from a significant number of applications, although they are not related. This feature allows the source field value to be modified (only to fetch the value from target application) to match the target application key (@ID) by a hook routine. The current requirement is to allow this hook routine to return multiple value for a single value field passed as input.

For example, below complex join would fetch the value of the field ADDRESS from CUSTOMER application resolving the customer ID inputted in the ACCOUNT application.

The path is ACCOUNT>CUSTOMER>#CUSTOMER>ADDRESS.

The CUSTOMER field in the ACCOUNT application is termed as source field and the application from where the value would be fetched is termed as target application separated by the complex join delimiter ‘#’.

This complex join provides a flexibility of getting data from related applications where the applications does not have a common reference field. The option ‘Get multiple keys’ allows multiple values to be returned for a single value field passed as input.

Defining and Using Complex Joins

The following procedure explains how to define and use a complex join and to return multiple IDs.

1. Create a new Event Designer Project. Add an exit point and a flow to it. In the flow add a join field with the Modify Key selected. This creates a join definition as shown below:

   

2. Create a new Event Designer Project. Add an exit point and a flow to it. In the flow add a join field with the Get Multiple Keys selected. This creates a join definition as shown below:

   

   The example above shows that the exit point is created for the ACCOUNT application.

   Selecting Get Multiple Keys enables the Field to Modify dropdown, which is populated with the complex joins of the join definition it is populated with.

   
3. From the Field to Modify dropdown, choose a complex join, where you intend to change the source application from single to multi. When you define a complex join, remember that:
   • Only one of the source fields can be either multivalue or a subvalue.
   • A complex join is only allowed once in a join definition.
   • The option to get multiple values is allowed on fields with complex joins. However, the complex join field needs to be a single value field.
   The Field to modify dropdown is disabled once a join is selected.

   The following screenshot shows the complex join prefixed with ‘%’ once it is chosen.

   

4. Publish the flow.

   

5. Write subroutines to resolve the transaction ID. The subroutines will be invoked by the Integration Framework APIs, specifically modifyJoinId.

   SUBROUTINE getCustomerId(joinProperty, transactionId, sourceValue, modifiedValue,
   responseDetails)
   $INSERT I_COMMON
   $INSERT I_EQUATE
   $INSERT I_IntegrationFrameworkService_ModifiedValue
   $INSERT I_IntegrationFrameworkService_JoinProperty
   $INSERT I_responseDetails
   sourceApplicationName = joinProperty<JoinProperty.sourceApplication>
   sourceFieldName = joinProperty<JoinProperty.sourceField>
   targetApplication = joinProperty<JoinProperty.targetApplication>
   customerID = sourceValue
   IF( targetApplication NE "CUSTOMER") THEN
   modifiedValue<ModifiedValue.value> = customerID : TODAY
   END
   RETURN
   

   Parameters

   • joinProperty

     An input parameter of the type JoinProperty. It holds the join field details and has the below attributes:

     • sourceApplication. The parent application for which the join is defined.
     • sourceField. The parent field for which the join is defined.
     • targetApplication. The target application for which the join is defined.
   • transactionID

     The string parameter that holds the transaction ID.

   • sourceValue

     The string parameter that holds the original value based on which the join is defined.

   • modifiedValue

     An output parameter of the type ResponseDetails, which has the following attribute:

     • value. Holds the modified ID as string value.
   • responseDetails

     An output parameter of the type ResponseDetails. This type is used to add details about the response and has the following attributes:

     • returnCode. Indicates SUCCESS or FAILURE.
     • serviceName. Holds the name of the service.
     • responses. List of strings that holds the message to be provided to the calling routine
6. Compile the routines and create a PGM.FILE entry for each routine.
7. Create a record in IF.CALLBACK.IMPL.CATALOG to specify the subroutines that are to be invoked by modifyJoinId, either with the record ID as SYSTEM or with the flow name.

   The IF.CALLBACK.IMPL.CATALOG table allows the user to define the join resolution APIs at flow level. When triggering events, the Integration Framework looks first for the record with the flow name and if it is not available, then the IF looks for the SYSTEM record to resolve complex joins.

Returning Multiple and Single Values in Complex Joins

If a transaction involves the application for the complex join that was added to the flow prefixed with ‘%’: T

• The output XML returns multiple values for a single value passed as input.
• The schema for the created flow reflects the modification from single to multi value.

When using a complex join, the routine can return any number of values. If the source field is single, and the returned values are multi, there is a risk that the event XML would contain all the data but not in an understandable format. To avoid this risk, the values returned by a complex join are validated as follows.

• A single value source field can resolve to a key that will not have any value marker and sub value marker.
• A multivalue source field can resolve to keys that can have value marker and not sub value marker.
• A subvalue source field can resolve to keys that can have value marker and also sub value marker.

If any part of the join violates these conditions, a warning is logged and event generation continues.