Optimize API for Natural

This document covers the following topics:

What is the Optimize API for Natural?

The Natural application programming interface (API) USR4217N enables Natural applications to send business and event data to Optimize via the Web Service Data Collector. In order to use this API, the Web Service Data Collector of Optimize must be installed.

The following API-related objects are contained in the Natural system library SYSEXT (they are available on mainframe, UNIX and Windows platforms):

Object Name Description
USR4217N API subprogram (cataloged object) that can be used to send data to Optimize.
USR4217P Example program (source object) that can be used to test the effect of the API.
USR4217T Text object that contains a description of the API. The description comprises purpose, function and calling conventions of the API and relevant keywords.

For further information on the SYSEXT utility, see Utilities in the Natural documentation for the appropriate platform.

Using the Optimize API for Natural

If you want to use the Optimize API for Natural, you have to copy the API subprogram USR4217N to one of the following: the library SYSTEM, the steplib library, or to any application.

The calling program has to contain a CALLNAT statement with the following parameters:

        P-Array-of-Data (*)

In structured mode, the parameters must be defined using the DEFINE DATA statement. In reporting mode, they must be defined using the RESET statement. For detailed information on the parameters, see the Natural text object USR4217T.

Configuring the New KPIs in Optimize

When the Optimize API for Natural is called for the first time with a new event type specified in P-Event-Type, Optimize allocates a rough event map for the supplied structure. Before you can monitor the new KPIs, additional configuration is required.

See also Configuring KPIs in the Administering webMethods Optimize guide.

Start of instruction setTo configure the new KPIs

  1. Go to Navigate > Applications > Administration > Analytics > KPIs > System Data.

    The new event type is an element of the "Unmapped Event Types".

  2. Click on the new event type to display the list of fields.

  3. Click on each field to edit the field mapping. Use the Field name as Display Name. Select the type of the field:

    Type Description
    Dimension The first entries sent in P-Array-of-Data-Name supply the dimensions as part of the hierarchy which will be displayed in the Optimize Analytics Overview. Specify whether it is an existing dimension or a new dimension. For a new dimension, you may use the field name as Dimension and as Attribute.
    Transaction Use this for generic fields containing alphanumeric text.
    Fact Use this for KPIs containing numeric values. Select the calculation type and specify the unit of measurement (UOM), for example "count", "ms" (milliseconds), "percent", "seconds", or "state".
    Date Use this for date fields.
  4. When all fields are configured, specify the name of the event information (use the Event Type name) and save the event map. The event map is now an element of "Event Maps not categorized".

  5. If the event map does not use an existing hierarchy, you must add a new hierarchy. Go to Navigate > Applications > Administration > Analytics > KPIs > KPI Hierarchies. Click Add Hierarchy and proceed as follows:

    • Specify any unique name for the hierarchy.

    • Select the root dimension of your hierarchy, that is, the one sent in P-Array-of-Data-Name(1).

    • Add a child (dimension) for each further dimension of your hierarchy.

    • Save the hierarchy.

  6. Go to Navigate > Applications > Administration > Analytics > KPIs > System Data and add the KPI definition for each fact field. For each field, click Add KPI and proceed as follows.

    In the KPI Definition (lower part of the screen):

    • As the definition type, select Individual.

    • As the event mapping, select the event map name sent in P-Event-Type.

    • Select the fact associated to the KPI.

    • Select the hierarchy created in the previous step.

    • Select the dimension which was added as the last child to the hierarchy.

    In the KPI Information (upper part of the screen):

    • Specify a name. You can use the fact name.

    • Specify a naming template. The naming template is used in the Analytics Overview. You can insert the dimension variables as a prefix of the naming template by clicking on the button behind the Naming Template text box.

    When all information has been specified, save the KPI.

If desired, you can add "composite" KPIs which are derived from the new KPIs and rules for the new KPIs.