This document covers the following topics:
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.
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:
CALLNAT 'USR4217N'
P-Target
P-Event-Type
P-Array-of-Data (*)
P-Time-A
P-Return-Msg
P-Return-Code
P-Return-Soapmsg
P-Return-Soapcode
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.
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.
Note:
See also Configuring KPIs in the
Administering webMethods Optimize guide.
To configure the new KPIs
Go to Navigate > Applications > Administration > Analytics > KPIs > System Data.
The new event type is an element of the "Unmapped Event Types".
Click on the new event type to display the list of fields.
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. |
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".
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 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.
Go to Navigate > Applications > Administration > Analytics > KPIs > System Data and add the KPI definition for each fact field. For each field, click 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.