Modifying analytics API event data

How to modify API event data before it is stored.

Before you begin

Ensure you are familiar with the API Manager UI, creating REST APIs, and viewing Analytics data.

About this task

The analytics subsystem stores analytics data as individual API event records. One record represents one API event that is logged by the gateway. The API event record fields are defined here: API event record fields. It is possible to customize the API event records for specific APIs. You can modify the contents of existing API event fields, and add new custom fields by using a gateway script or the set-variable operation.

Note: If you want to make updates to all incoming API event data, rather than specific APIs, you can use filters as described here:

Procedure

In the API Manager UI, click the Develop APIs and products tile, select the APIs tab, click Add, select API (from REST, GraphQL or SOAP).
Select New OpenAPI, give the API the title of Hello World and click Next. Click Next again to accept the security defaults, and then click Edit API.

Select the OpenAPI YAML source view OpenAPI Source icon

, replace the generated YAML with the following YAML and click Save:

swagger: '2.0'
info:
  title: Hello World
  x-ibm-name: hello-world-rest
  version: 1.0.0
schemes:
  - https
basePath: /hello-world
security:
  - {}
securityDefinitions:
  clientID:
    type: apiKey
    in: header
    name: X-IBM-Client-Id
x-ibm-configuration:
  phase: realized
  testable: true
  enforced: true
  properties:
    target-url:
      value: http://example.com/operation-name
      description: The URL of the target service
      encoded: false
  cors:
    enabled: true
  activity-log:
    enabled: true
    error-content: header
    success-content: activity
  application-authentication:
    certificate: false
  assembly:
    execute:
      - map:
          version: 2.0.0
          title: map
          inputs:
            name:
              schema:
                type: string
              variable: request.parameters.name
          outputs:
            response:
              schema:
                $ref: '#/definitions/Result'
              variable: message.body
          actions:
            - set: response.hello
              from: name
              value: '''Hello '' +$(name)'     
    catch: []
    finally: []
  gateway: datapower-api-gateway
  categories:
    - /tests
  type: rest
definitions:
  Result:
    type: object
    additionalProperties: false
    properties:
      hello:
        type: string
paths:
  /hello:
    get:
      parameters:
        - name: name
          in: query
          required: false
          type: string
      responses:
        '200':
          description: OK Response
          schema:
            $ref: '#/definitions/Result'
    parameters: []

Click the Form icon to switch to the Form view and select the Gateway tab.
From the palette, select the Log policy element and drag it onto the canvas, placing it at the last position in the flow. Set the log policy to Gather-only. This step is so that the log context variable is populated, for use in the next step.
Modify API event data or add custom data either with a gateway script or by using the set-variable operation.
Gateway script method
Add a Gateway script policy to the assembly flow and paste in the following script code:
```
var logs = context.get('log');
  if (logs) {
    if (!logs.custom_data) {  
      logs.custom_data = {};
    }
    logs.custom_data.newAPIEventDataField = 'newData';
    logs.product_title = 'newProductTitle';
    context.set('log', logs);
  }
```
In this example, the new field that is added to the API event record is called newAPIEventDataField and its value is set to newData. The value of the existing field product_title is changed to newProductTitle.
Set-variable method

If you cannot or do not want to use a gateway script, then you can use a set-variable policy instead. Add a set-variable policy to the assembly flow, and set it as follows:. In this example, the new field that is added to the API event record is called newAPIEventDataField and its value is set to newData.
The YAML code for set-variable is:
```
      - set-variable:
          version: 2.0.0
          title: set-variable
          actions:
            - set: log.custom_data.newAPIEventDataField
              value: newData
              type: string
            - set: log.product_title
              value: newProductTitle
              type: string
```
Note: context.log.custom_data supports the addition of primitive typed values such as strings and integers, and there is no enforced limit on how many you can add. Add data only to the context.log.custom_data object. Do not add data to context.log.
The type of existing fields cannot be changed. For example, product_title is a string and cannot be changed to an integer. Do not attempt to assign a different type to an API event field.
Publish your Hello World API to a catalog.
Make a test call to the API and verify that the new custom data is set.
1. From the Analytics view, select Discover and click the API event record corresponding to your test call:
2. Scroll down the page to view the API event record payload. Your custom data field should be present:
You can use filters to view only analytics data that has your new custom field set.
To use new data with REST API calls, use the custom_data query parameter:
```
 /cloud/events?custom_data[newAPIEventDataField]=newData
```