1. Using Integrations in Oracle Integration 3
  2. Create Event Integrations
  3. Define Custom Header Filters to Trigger Integrations

Define Custom Header Filters to Trigger Integrations

You can define custom headers in events, select those events and map request payload elements to the custom headers when creating a publishing integration, and then define filters on those headers when creating a subscribing integration. If the filter condition defined is satisfied at runtime, the subscribing integration is triggered. If the filter condition is not satisfied, the integration is not triggered.

Capabilities

  • You define custom headers when creating an event.
  • You define custom header values in the mapping of a publish event action. You can define the mapping from payload data to a custom header to enable payload data to participate in filtering.
  • You define filters on the custom headers when creating a subscribing integration. Subscribers can filter events based on fields within the payload if those fields are mapped to the custom headers. If the filter condition you define is satisfied during runtime, the subscribing integration is triggered.
  • You define filters in two ways:

    • JQ expressions (through the Code tab):

      For example:

      "filter-def": ".customheader1==\"someValue\""


      The Configure Event Filter panel appears. The Code and Designer tabs appear at the top. Below this is the Event Filter label. Below this is the Upload JSON file field. Below this is a field with a JSON code sample.

      JQ is a lightweight and flexible command line JSON processor primarily used for extracting and manipulating JSON data. JQ takes an input and produces an output. See jq 1.7 Manual and JQ Expression Syntax for Creating Filters.

    • Expression builder (through the Designer tab):

      This option enables you to build an expression by dragging an element or function from the source tree, then defining it further in the designer. For example:


      The Input sources (which is selected) and Functions tabs are shown. The Sources tree is expanded to show the ptname element. This element has been dragged to the design window, which is displayed when you click the Designer tab. There is also a Code tab. The filter is defined with the ptname element set to "John."

Restrictions

  • You can define 10 custom headers per event.
  • If defining a filter in the code editor, enter all functions in lower case.
  • Only JQ expression filters are supported.
  • The following JQ function calls are supported:
    • any
    • all
    • ascii_downcase
    • ascii_upcase
    • tonumber
    • tostring
    • min
    • max
    • contains
    • startswith
    • endswith
    • ltrimstr
    • rtrimstr
    • length
  • The following JQ keywords/filter expressions are not supported:
    • '.' (A single dot alone is not supported for security reasons.)
    • while
    • for
    • repeat
    • input/inputs/stderr
    • debug
    • input_filename
    • input_line_number
    • recurse
    • foreach
    • until
  • JQ-based Lambda function definitions and their executions as part of a filter definition are not supported.

Use Case Overview

The use case in this section walks you through creating an event with custom headers, selecting the event and mapping the custom headers in a publishing integration, and adding different JSON-based filter conditions to the headers in several subscribing integrations. In this use case:

  1. Event MLFilterEvent is created with the following event and custom header content:
    Event Structure Custom Headers 
    {
    "patientIdentifier" : "12345679",
    "illness" : "1",
    "name": "min",
    "age":30,
    "weight":100
  }
    		 
    ptname
ptage
ptweight
  2. Publishing integration MLFilterPub is designed to publish the event MLFilterEvent. This integration consists of the following connection and actions:
    • A REST Adapter trigger is configured with the following JSON-formatted request payload:
      
{
  "patientIdentifier" : "12345679",
  "illness" : "1",
  "name" : "min",
  "age" : 30,
  "weight" : 100
}
    • A mapper is configured to map patient details elements in the source request payload to target patient details elements, target standard header elements, and target custom header elements.
    • A log action is configured to log standard and custom header details in the activity stream.
  3. The following subscribing integrations are designed to subscribe to the MLFilterEvent event:
    1. Subscribing integration MLFilterSubNoFilter is designed without adding any filters.
    2. Subscribing integration MLFilterNameSub is designed to be triggered only if the following custom header filter condition is satisfied. 
      {
    "type": "jq_filter",
    "filter-def": ".ptname==\"John\""
}
    3. Subscribing integration MLFilterAgeSub is designed to be triggered only if the following custom header filter condition is satisfied. 
      {
    "type": "jq_filter",
    "filter-def": ".ptage|length!=0 and tonumber >= 18"
}
  4. The three subscription integrations are activated: MLFilterSubNoFilter, MLFilterNameSub, and MLFilterAgeSub.
  5. When publishing integration MLFilterPub is activated, the request payload body values are specified, and the integration is run, the following occurs:
    • Subscribing integration MLFilterSubNoFilter is always triggered and consumes the event. Because no custom header filters are defined on this subscribing integration, there are no restrictions on it being triggered.
    • Subscribing integration MLFilterNameSub is only triggered if "name": "John" is set in the request payload body.
      {
    "patientIdentifier" : "123456790",
    "illness" : "1",
    "name": "John",
    "age":30,
    "weight":100
  }
    • Subscribing integration MLFilterAgeSub is only triggered if age is greater than or equal to 18. For this example, "age": "30" is set in the request payload body.
      {
    "patientIdentifier" : "123456790",
    "illness" : "1",
    "name": "John",
    "age":30,
    "weight":100
  }

Let's now design and run the use case.

Create an Event with a Custom Header in a Project

  1. In the navigation pane, click Projects.
  2. Create a project.
  3. Scroll down to the Events section.
  4. Click Add if no events currently exist or + if events already exist.
  5. Enter a name (for this example, named MLFilterEvent) and description, and click Continue.
  6. Define the event structure, and click Continue. For this event, the following JSON-formatted event is defined:
    {
    "patientIdentifier" : "12345679",
    "illness" : "1",
    "name": "min",
    "age":10,
    "weight":100
  }
  7. Click + to add a custom header to the event.
  8. Click Edit Edit icon to change the icon to a Check Mark Check mark icon. This action enables the row to be edited.
  9. Enter a name and optional description, then click the Check Mark Check mark icon when complete. Note the following custom header naming conventions:
    • Can be lower-case letters (a-z) and numbers (0-9).
    • Cannot be longer than 20 characters.
    • Cannot be a duplicate of another custom header.
    • Must not be a reserved cloud events attribute (for example, data). If you use a reserved name, it does not pass validation.

    For this example, the following custom headers are added.


    The Configure custom header page shows a + sign to click to add headers. Below this is a table with columns for Custom Header Name, Custom Header Description, and Actions. Actions includes icons for edit and delete.

Create an Integration to Publish the Event in a Project

  1. Return to the project details page.
  2. Go to the Integrations section and add an integration.
  3. Select an application integration.
  4. Add a trigger connection. For this example, a REST Adapter connection is defined to include the following JSON-formatted request payload:
    {
  "patientIdentifier" : "12345679",
  "illness" : "1",
  "name" : "min",
  "age" : 30,
  "weight" : 100
}
  5. Click + below the REST Adapter and drag a Publish event action into the integration.
  6. Select the event in which you defined the custom headers (MLFilterEvent), and click Finish.


    The Choose event panel shows the Search by name field and Define new event button. The MLFilterEvent event is being selected.

  7. Open the mapper for the Publish event action and define the mappings:
    1. Map the Request Wrapper source elements to the Request Wrapper target elements. For this example:
      • Patient Identifier to Patient Identifier
      • Illness to Illness
      • Name to Name
      • Age to Age
      • Weight to Weight
    2. Expand the target Event Headers section to show Standard Event Headers and Custom Event Headers.
    3. Expand the target Standard Event Headers and map the source Patient Identifier to the target Subject.
    4. Expand the target Custom Event Headers and map the following request payload elements to the target custom headers you created:
      • Name to ptname
      • Age to ptage
      • Weight to ptweight

    When complete, the mappings look as follows:


    The Sources, Mapping canvas, and Target sections are shown. The source elements that are mapped to the target elements are described above this image.

  8. Validate the mapper and return to the integration canvas.
  9. Add a log action to log the standard and custom headers.


    The Configure logger panel is shown. On the left are the Input sources (which is selected) and Functions tabs. The Sources tree is expanded to show the EventHeaders section. The StandardEventHeaders and CustomEventHeaders sections are shown. CustomEventHeaders includes elements for ptname, ptage, and ptweight. On the right is the Log section, which includes radio buttons for Always (which is selected) and When tracing level is set to Audit. Below this is the defined logger message. Two icons appear to the right of this message. In the upper right is an Edit icon and four vertical icons.

  10. Save the log action.

    The completed integration looks as follows:


    The integration shows trigger, map, publish, and logger icons.

Let's now create integrations to subscribe to the event and demonstrate how filters work.

Create an Integration with No Filter to Subscribe to the Event in a Project

  1. Create an event integration (for this example, named MLFilterSubNoFilter).
  2. Select the MLFilterEvent event, and click Choose.


    The Choose event panel appears on the right. A search field and Define new event button appear. Below this is the list of events available for selection. On the left is the event integration pattern icon.

  3. Click Finish.
  4. Add a log action to log the standard and custom header details.

    The Configure logger panel is shown. On the left are the Input sources (which is selected) and Functions tabs. The Sources tree is expanded to show the EventHeaders section. The StandardEventHeaders and CustomEventHeaders sections are shown. CustomEventHeaders includes elements for ptname, ptage, and ptweight. On the right is the Log section, which includes radio buttons for Always (which is selected) and When tracing level is set to Audit. Below this is the defined logger message. Two icons appear to the right of this message. In the upper right is an Edit icon and four vertical icons.

    The completed integration looks as follows:


    The integration shows a subscribe to event icon and logger icon.

  5. Activate the integration.

Create an Integration with a Name Filter to Subscribe to the Event

  1. Create an event integration (for this example, named MLFilterNameSub).
  2. Select the MLFilterEvent event, and click Choose.


    The Choose event panel appears on the right. A search field and Define new event button appear. Below this is the list of events available for selection. On the left is the event integration pattern icon.

  3. Click Add Filter.


    The Review subscribe action panel is shown. An edit icon appears to the right. Below this is the name of the specific event, a view details icon, and an Add Filter button.

  4. Manually enter the filter condition in the code editor. The only supported filter type is jq_filter. For this example, ptname (patient name) is set to John. If this filter condition is satisfied at runtime, this integration is triggered.
    {
    "type": "jq_filter",
    "filter-def": ".ptname==\"John\""
}


    The Configure Event Filter panel appears. The Code and Designer tabs appear at the top. Below this is the Event Filter label. Below this is the Upload JSON file field. Below this is a field with a JSON code sample.

  5. Click Validate, then click Finish.
  6. Add a log action with a message.


    The Configure logger panel is shown. On the left are the Input sources (which is selected) and Functions tabs. The Sources tree is expanded. On the right is the Log section, which includes radio buttons for Always (which is selected) and When tracing level is set to Audit. Below this is the defined logger message. Two icons appear to the right of this message. In the upper right is an Edit icon and four vertical icons.

    The completed integration looks as follows:


    The integration shows a subscribe to event icon and logger icon.

  7. Activate the integration.

Create an Integration with an Age Filter to Subscribe to the Event

  1. Create an event integration (for this example, named MLFilterAgeSub).
  2. Select the MLFilterEvent event, and click Choose.


    The Choose event panel appears on the right. A search field and Define new event button appear. Below this is the list of events available for selection. On the left is the event integration pattern icon.

  3. Click Add Filter.


    The Review subscribe action panel is shown. An edit icon appears to the right. Below this is the name of the specific event, a view details icon, and an Add Filter button.

  4. Manually enter the filter in the code editor. For this example, ptage (patient age) is set to 18 or older. If this filter condition is satisfied at runtime, this integration is triggered.
    {
    "type": "jq_filter",
    "filter-def": ".ptage|length!=0 and tonumber >= 18"
}


    The Configure Event Filter panel appears. The Code and Designer tabs appear at the top. Below this is the Event Filter label. Below this is the Upload JSON file field. Below this is a field with a JSON code sample.

  5. Click Validate, then click Finish.
  6. Add a log action to log age details.


    The Configure logger panel is shown. On the left are the Input sources (which is selected) and Functions tabs. The Sources tree is expanded to show the EventHeaders section. The StandardEventHeaders and CustomEventHeaders sections are shown. CustomEventHeaders includes elements for ptname, ptage, and ptweight. On the right is the Log section, which includes radio buttons for Always (which is selected) and When tracing level is set to Audit. Below this is the defined logger message. Two icons appear to the right of this message. In the upper right is an Edit icon and four vertical icons.

    The completed integration looks as follows:


    The Subscribe to event icon and logger icon are shown.

  7. Activate the integration.

Run the Publishing Integration and Track the Created Instances

  1. Activate the publishing integration.
  2. Hover over the publishing integration, then click Actions icon and select Run.

    Under Body, the request payload is displayed.

  3. Change name to John and age to 10, then click Run.
    {
  "patientIdentifier": "12345679",
  "name": "John",
  "weight": 100,
  "age": 10,
  "illness": "1"
}
  4. Expand key milestones in the activity stream for the publishing integration instance to see details.


    The activity stream shows three icons in the upper right. Below is the publish milestone is expanded to show message details. Below this is a logger activity.

  5. Return to the project details page.
  6. Click Observe, then Instances.
    The following integration instances are displayed.
    • MLFilterSubNoFilter: The subscribing integration with no filter. This integration is triggered because no filter is set.
    • MLFilterNameSub: The subscribing integration with the filter of name set to John. This integration was triggered because the filtering condition was satisfied.
    • MLFilterPub: The publishing integration for the event.


    The Instances tab shows search and filter icons. Below this is the configured filter. In the upper right is a timestamp and three icons. Below is a table with columns for Primary Identifier, Instance ID, Business Identifiers, Status, and Duration.

    The subscribing integration MLFilterAgeSub was not triggered because the filtering condition was not satisfied.

  7. Open the activity stream and expand key milestones for MLFilterSubNoFilter.


    The activity stream shows the instance ID at the top. Four icons appear in the upper right. The tracing level is set to Production. Below is the publish milestone is expanded to show message details. Below this, the Message received by Subscribe activity is expanded to show message details. The logger activity is also expanded to show message details..

  8. Open the activity stream and expand key milestones for MLFilterNameSub.


    The activity stream shows the instance ID at the top. Four icons appear in the upper right. The tracing level is set to Production. Below is the publish milestone is expanded to show message details. Below this, the Message received by Subscribe activity is expanded to show message details. The logger activity is also expanded to show message details..

Run the Publishing Integration Again and Track the Created Instances

  1. Return to the project details page.
  2. Hover over the publishing integration, then click Actions icon and select Run.

    Under Body, the request payload is displayed:

  3. Leave name set to John, change age to 30, optionally change the patientIdentifier to another value, and then click Run.
    {
  "patientIdentifier": "123456890",
  "name": "John",
  "weight": 100,
  "age": 30,
  "illness": "1"
}
  4. Expand key milestones in the activity stream for the publishing integration instance to see details.


    The activity stream shows three icons in the upper right. Below is the message publishing activity is expanded to show message details. Below this is a logger activity.

  5. Return to the project details page.
  6. Click Observe, then Instances.
    The following integration instances are displayed.
    • MLFilterSubNoFilter: The subscribing integration with no filter. This integration is triggered because no filter is set.
    • MLFilterAgeSub: The subscribing integration with the filter of age set to 30. This integration was triggered this time because the filtering condition was satisfied.
    • MLFilterNameSub: The subscribing integration with the filter of name set to John. This integration was triggered again because the filtering condition was satisfied.
    • MLFilterPub: The publishing integration for the event.


    The four instances described above the image are shown. A timestamp appears at the upper right, along with three icons. At the upper left are search and filter icons. The configured filter is displayed. Below this is a table with columns for Primary Identifier, Instance ID, Business Identifiers, Status, and Duration.

  7. Open the activity stream and expand key milestones for each instance. For this example, MLFilterAgeSub is expanded.


    The activity stream is shown. The instance ID is shown at the top. The tracing level is production. Four icons are shown at the top right. The key milestones in the activity stream are shown. The message payload is shown for one of the milestones.