Oracle Integration Analytics Cloud: Publishing Metrics with the Insight Event REST API

 

Before You Begin

Purpose

This tutorial shows you how to use the Oracle Real-Time Integration Business Insight Event REST API to publish business metrics. The Event REST API is available with the Oracle Integration Analytics Cloud component of Oracle SOA Cloud Service. 

Time to Complete

1 hour

Background

The Insight Event REST API is:

  • Provided as a resource to publish raw business events, with associated metric data, to Integration Analytics Cloud from heterogeneous cloud and on-premises environments
  • Invoked to publish a business event for a specific milestone defined in an Insight model

You use preconfigured and custom Insight dashboards to visualize business metrics, published from heterogeneous sources through the Insight Event REST API, similar to how you view business metrics from Service Bus and SOA composite applications. For more information refer to Getting Started with Integration Analytics in SOA Cloud Service and Understanding Oracle Real-Time Integration Business Insight.

Scenario

In this tutorial, you download and import a simple Order Processing model into your Integration Analytics environment provisioned under your Oracle SOA Cloud Service. After you import the Insight model, check the API connection, activate the model, and use the cURL command-line tool (or sample scripts provided) to publish business events by using the Insight Event REST API.

What Do You Need?

  • A paid or trial subscription to Oracle SOA Cloud Service with Integration Analytics service type
  • If you have a paid subscription to Oracle SOA Cloud Service, then a subscription to Oracle Storage Cloud Service is needed.
  • Your Oracle Cloud service user name, password, and identity domain (available in the New Account Information email that you received from Oracle Cloud when your user account was set up)
  • REST API Testing tools:
    • cURL command-line tool (or equivalent client-side REST API testing tool for web browsers, such as Postman for Chrome browsers)
    • Windows restapi_scripts.zip or Linux restapi_scripts.tar (contains a simple script that uses the curl command and associated JSON data files to avoid typing or copying and pasting tutorial examples)
 

Accessing Your Integration Analytics Cloud Instance

  1. In a web browser window, sign in to Oracle SOA Cloud Service with your credentials.

  2. On the Oracle SOA Cloud Service home page, click Instances.

    Clicking the Instances tab on the Oracle SOA Cloud Service home page
    Description of this image

  3. On the Instances page, click the instance name of the Integration Analytics instance created in your Oracle SOA Cloud Service. In this example, click the insightwia link.

    Clicking the SOA Cloud Service instance link
    Description of this image

  4. On the instance name page, insightwia (Oracle SOA Cloud Service) in this example, make note of the Load Balancer Content Endpoint address, which is used by your application code to access the Insight Event REST API.

    Determining the Public IP address on the SOA Cloud Instance page
    Description of this image
 

Preparing the Insight Model

 

Importing the Order Processing Model

  1. Download the Order Processing model provided with this tutorial, and save the file to your downloads folder (for example, D:\Downloads).

  2. On the instance name page, the insightwia (Oracle SOA Cloud Service) page in this example, click the View the console pages for this service icon and select Open Insight Composer.

    Selecting the Open Insight Composer menu item
    Description of this image
  3. On the Insight Composer login page, enter the user name weblogic and the weblogic user password, and click Sign In.

  4. On the Insight Composer home page, click the Designer tab.

    Clicking the Designer Tab
    Description of this image

  5. On the Designer page, click Import Model.

    Clicking Import Model on the Designer page
    Description of this image

  6. In the Import Model dialog box, under Archive To Import, click in the Choose File field.

    Clicking Choose File to browse for an archive to import
    Description of this image

  7. In the Open File dialog box, navigate to your downloads folder, select Order Processing Model.zip, and click Open.

  8. In the Import Model dialog box, ensure that Order Processing Model.zip appears under Archive To Import, and click Import Model.

    Clicking Import Model In the Import Model dialog box
    Description of this image
  9. On the Designer page, verify that the imported model named Order Processing (Draft) is visible and that the following confirmation message is displayed: "Model successfully imported. To activate, first configure imported Connections."
 

Checking the Order Processing API Connection

  1. On the Designer page, click the Connections link next to the "Model successfully imported" message.

    Clicking the Connections link on the Designer page
    Description of this image

  2. In the pop-up window, click the OrdersAPIConnection link in the Imported column.

    Clicking the OrdersAPIConnection link to configure it
    Description of this image

  3. On the Administration page, under Data Connections, verify that the OrdersAPIConnection entry shows that it's in the Configured state, and then click the Designer tab.

    Viewing the Configured API connection on the Data Connections page
    Description of this image
 

Activating the Order Processing Model

  1. On the Designer page, in the Order Processing (Draft) model entry under Insight Models, click the List of actions icon, and select Activate.

    Activating the imported Order Processing model
    Description of this image

  2. In the Activate Confirmation dialog box, click Continue.

  3. On the Designer page, wait until the Activate In Progress value reaches 100%. Activation takes at least one minute.

  4. Verify that the model name changed to Order Processing and that Activated is displayed next to the name. Click the Order Processing link to open the model.

    Navigating to the Designer page for the Order Processing model
    Description of this image
 

Publishing Business Metrics

 

Accessing the API Invocation Manifest

In this section, you download a text file containing the API Invocation Manifest. This file provides the JSON data structures that you copy into the code which publishes business events for your Insight model.

  1. If the Order Processing model isn't visible on the Designer page, click the Designer tab, and then click the Order Processing link under the Insight Models heading.

  2. Click the List of actions icon, and select API Invocation Manifest.

    Obtaining the API Invocation Manifest for the Order Processing model
    Description of this image

    The Save As dialog box is displayed.

  3. To save the Order Processing_mapping_manifest.txt file, navigate to your downloads folder, and click Save.

  4. Open Order Processing_mapping_manifest.txt in a text editor and view the contents.

    The following code example shows part of the file's contents, which provide skeleton JavaScript Object Notation (JSON) payload structures that are required to supply the relevant data for each milestone in the Order Processing model. For each milestone in the model, you must specify the same unique modelId value in the JSON data structure used to publish a business event.

    Insight External Application Integration Manifest generated on 7:49:17 PM

Model Name : Order Processing (Id: OrderProces_vcYrMs9z)
========================================================

1. Milestone Name: Order Received (Id: OrderReceived)
-----------------------------------------------------
{
  "modelId" : "OrderProces_vcYrMs9z",
  "identifierValue" : "",
  "correlationValue" : "",
  "measures" : [ {
    "name" : "ItemOrdered",
    "value" : ""
  }, {
    "name" : "Price",
    "value" : ""
  }, {
    "name" : "CustomerName",
    "value" : ""
  } ],
  "eventTime" : "",
  "milestoneId" : "OrderReceived",
  "dimensions" : [ {
    "name" : "Country",
    "value" : ""
  } ]
}

2. Milestone Name: Order Created (Id: OrderCreated)
---------------------------------------------------
{
  "modelId" : "OrderProces_vcYrMs9z",
  "correlationValue" : "",
  "measures" : [ {
 ...

  5. Close the text editor.

 

Copying the REST API and JSON Structures for a Milestone

In the previous section, you downloaded a text file that contains the JSON payload structures for all milestones in your Insight model definition. In this section, you determine the Insight Event REST API endpoint that's needed to publish a business event for the Order Received milestone in the Order Processing Insight model provided with this tutorial.

  1. If the Order Processing model isn't visible on the Designer page, click the Designer tab, and then click the Order Processing link under the Insight Models heading.

  2. Ensure that the Milestones tile is selected, locate the Order Received milestone, and select the Click to expand icon to display the details for the milestone.

    Expanding the Order Received milestone
    Description of this image

  3. In the Implementation Mapping(s) of the Order Received milestone, select the Click to see the details of API integration icon.

    Accessing the API Invocation details for the Order Received milestone
    Description of this image

  4. In the API Invocation Details window, in the Invoke the following REST API from the integrating application field, copy the endpoint URL string for your milestone and save it in a text file named endpoint_url.txt.

    REST API endpoint URL for the Order Received milestone
    Description of this image

    The Insight Event REST API endpoint provides the /event URI to publish a business event for a milestone in an Insight model. For this URI, you must use the POST method to send the business event data formatted with the JSON data structure that you obtained for a milestone. In a subsequent step, you copy this saved URL endpoint in the curl command that you use to publish the Order Received business event.

  5. Open a text editor and create a new (empty) file for the Order Received business event.

  6. In the API Invocation Details window, copy all the JSON text, and click OK to close the window.

    Viewing the API Invocation Details dialog box for the Order Received milestone
    Description of this image

  7. In your text editor, paste the JSON text into the new file. Delete the line of code that starts with eventTime. (It’s preferable to allow the system to determine the event time when you publish business events.) Verify that your JSON text resembles the following code:

    {
      "modelId" : "OrderProces_vcYrMs9z",
      "measures" : [ {
          "name" : "ItemOrdered",
          "value" : "<Provide a value>"
        }, {
          "name" : "Price",
          "value" : "<Provide a value>"
        }, {
          "name" : "CustomerName",
          "value" : "<Provide a value>"
        } ],
      "identifierValue" : "<Provide a value>",
      "correlationValue" : "<Provide a value>",
      "dimensions" : [ {
        "name" : "Country",
        "value" : "<Provide a value>"
      } ],
      "milestoneId" : "OrderReceived"
    }

  8. For each JSON element, replace the <Provide a value> strings with the values listed in the following table. Be sure to enter the values inside the double quotation marks.
    Note: The identifierValue and correlationValue must be the same value in the event published for the initial milestone.

    JSON Element Value Description
    ItemOrdered Digital Alarm Clock A value determined by your application requirements.
    Price 60.00 A value determined by your application requirements.
    CustomerName Dande Lion A value determined by your application requirements.
    identifierValue 10001 Becomes the unique instance identifier value for the event. The data type must match the unique instance identifier definition in your model.
    correlationValue 10001 A unique value for correlating events published for milestones with the same correlationValue and the first milestone event with the same identifierValue. The correlationValue associates metric data with all milestones related to a single business instance.
    Country England A value determined by your application requirements.

  9. Verify that the JSON data matches the following code example, save the modified file as order_rec_evt1.json, and close the editor window:

    {
      "modelId" : "OrderProces_vcYrMs9z",
      "measures" : [ {
          "name" : "ItemOrdered",
          "value" : "Digital Alarm Clock"
        }, {
          "name" : "Price",
          "value" : "60.00"
        }, {
          "name" : "CustomerName",
          "value" : "Dande Lion"
        } ],
      "identifierValue" : "10001",
      "correlationValue" : "10001",
      "dimensions" : [ {
        "name" : "Country",
        "value" : "England"
      } ],
      "milestoneId" : "OrderReceived"
    }

    For this JSON data structure example for the Order Received milestone:

    • modelId (for example, OrderProces_vcYrMs9z) is determined from the API Invocation Manifest for your model. It's unique for your Insight model; don't change it. You must provide the modelId with each business event to ensure that the data is published to the correct Insight model.
    • milestoneId is the milestone name as defined in the Insight model, without spaces.
    • Metric data for measures and dimensions are entered as one or more name and value pairs.
    • Your application code replaces the "<Provide a value>" text strings with metric data appropriate for the business event.
 

Publishing Metrics with Business Events

To publish a business event, you use the Insight Event REST API endpoint URL that you determined from the implementation mappings of any milestone in your Insight model definition. Although you use the curl command line to publish business events in this tutorial, the Insight Event REST API is designed to be used inside your external application code.

In this tutorial, you must first open a terminal or command prompt window to run the curl commands that publish business events for each milestone in the Order Processing model. The term command-line window indicates the context that you use to run the curl commands. Each curl command uses the @ symbol followed by the JSON file name, provided in either the restapi_scripts.zip or restapi_scripts.tar file, to read the business event data that's published. Although each curl command is displayed on more than one line for clarity, you should enter them as one command line.

  1. In a text editor, navigate to the downloads folder where the tutorial business event JSON files are located, and open either the order_rec_evt1.json file that you created or the supplied 10001_01or.json file. Make a note of the values for modelId and correlationValue, because you use these values to compare the same elements in two related JSON files.

    Order Received Event: 10001_01or.json

    The 10001_01or.json file example demonstrates that identifierValue and correlationValue are the same unique value for this first business event, which is uniquely identified by the identifierValue. When subsequent events are published, with the same correlationValue and modelId, they are related to the instance created for the event published for the initial milestone.

  2. For the Order Created milestone event, open the 10001_02oc.json file and confirm that it contains the same model ID and correlation value used in the 10001_01or.json file.

    
  "modelId" : "OrderProces_vcYrMs9z",
  "correlationValue" : "10001",

  3. For the Order Finalized milestone event, open the 10001_03of.json file and confirm that it contains the same model ID and correlation value used in the 10001_01or.json file.

    
  "modelId" : "OrderProces_vcYrMs9z",
  "correlationValue" : "10001",

  4. Close the three JSON files and the text editor.

  5. In a command-line window, publish a business event for the Order Received milestone:

    $ curl -v -k -X POST -u weblogic -H "Content-Type:application/json" http://140.86.14.169/insight-server/api/1.0/event --data @10001_01or.json
    • Replace the URL with the Insight Event REST API endpoint URL for your environment or use the endpoint URL that you saved in the endpoint_url.txt file.
    • If necessary, replace the weblogic user name with a user who is authorized to access your Insight Event REST API endpoint URL.
    • If you want, replace the provided 10001_01or.json file with the order_rec_evt1.json file that you created.
    • If you use the HTTPS protocol, you need to obtain an SSL CA certificate for the cURL command line. You can download an SSL CA certificate bundle from http://curl.haxx.se/docs/caextract.html or provide your own. For information about CA certificate verification using cURL, see: http://curl.haxx.se/docs/sslcerts.html.

    For information about the command-line options used in these examples, see the curl documentation.

  6. At the prompt for the password, enter the password for your weblogic user name and press Enter.

  7. In the command-line window, near the end of the output results displayed for the curl command, verify that the following response text is displayed: {"type":"ok","message":""}. The message indicates that you successfully published the business event.

  8. In the web browser window where you're signed in to the Insight application, click the Consoles tab.

    Accessing the Consoles page
    Description of this image

  9. On the Consoles page next to the Order Processing model name, the Active state bar line indicates that the initial event published has created a new active Insight instance. Click the Order Processing link.

    Accessing the Consoles page for the Order Processing model
    Description of this image

  10. Under Milestone Dashboards, notice that the Order Received milestone is visible in the diagram view. In the Format list, click Table.

    Changing the Milestone Dashboards status diagram to a table format
    Description of this image

    The Milestone Dashboards display changes to a table format, and the Order Received entry is visible.

  11. In the command-line window, repeat steps 5 and 6 twice, entering the following file names after the @ symbol:

    • 10001_02oc.json to publish the Order Created milestone business event

    • 10001_03of.json to publish the Order Finalized milestone business event

 

Viewing Business Events and Messages

  1. On the Consoles page, click Refresh Data.

    Refreshing data on the Consoles page
    Description of this image

  2. Under Milestone Dashboards, confirm that the Order Created (standard) and Order Finalized (terminal) milestones are displayed in the table. In the Format list, click Diagram.

    The published business events are displayed in the Passed Milestones bar chart. You may need refresh the page after a short period for all the milestones to be visible.

    Viewing Milestone Dashboards charts and changing the status from a table format to a diagram format
    Description of this image

  3. In the Passed Milestones and Avg. Instance Completion Time charts, notice the visual information for the instances of the Order Received, Order Created, and Order Finalized business events. In the Avg. Instance Completion Time chart, right-click the bubble, and select Instance List.

    Accessing the order instance list from the bubble chart
    Description of this image

  4. To drill into the business event instance detail, on the orders instance list page, click the 10001 link in the Order ID column.

    Tip: You may have to modify your web browser settings to enable pop-up windows.

    Clicking the Order ID link to access instance details
    Description of this image

  5. To view the metric data published for each milestone, on the Order ID 10001 page, click Expand All in the Indicators section.

    Expanding Indicator information on the instance details page
    Description of this image

    In the Indicators section on the order instance page, you can verify that the indicator values are the same as those published for each business event.

    Validating indicator metric data for milestones on the instance details page
    Description of this image
 

(Optional) Playing with the Insight Event REST API

Now that you have viewed the metrics for one order instance, you can, if you want, play with the Insight Event REST API. The additional sample files are provided for that purpose.

When you extract the restapi_scripts.zip or restapi_scripts.tar files, script files named send_busevent.bat and send_busevent.sh, respectively, are created. These command scripts use the same curl command that you used to send business event data contained in JSON files from the command line.

Note: In the following command-line examples, replace the IP address and port in the first parameter with the IP address and port for your Oracle SOA Cloud Service instance. When prompted, enter the password for the user name specified in the send_busevent.bat or the send_busevent.sh script. The scripts use the HTTP protocol. Therefore, if you want to use the HTTPS protocol, you must update thecurl commands in the send_busevent.bat or send_busevent.bat files to work with the appropriate SSL authentication.

Windows: Run the send_busevent.bat script to send business events for order ID 10002, and enter the password for the weblogic user when prompted:

$ send_busevent.bat 140.86.14.169:80 10002_01or.json
$ send_busevent.bat 140.86.14.169:80 10002_02oc.json
$ send_busevent.bat 140.86.14.169:80 10002_03of.json

Linux (or UNIX platforms): Run the send_busevent.sh script for order ID 10002, and enter the password for the weblogic user when prompted:

$ cd download_folder
$ chmod +x send_busevent.sh
$ sh send_busevent.sh 140.86.14.169:80 10002_01or.json
$ sh send_busevent.sh 140.86.14.169:80 10002_02oc.json
$ sh send_busevent.sh 140.86.14.169:80 10002_03of.json

Additional JSON files are provided in groups of three for order IDs 10003 and 10004, if you want to play more.

 

Want to Learn More?