Customizing data with a gateway script or set-variable operation

Customize your API event records on the gateway before they are sent to your analytics subsystem.

Before you begin

Ensure that you are familiar with the API Manager UI, and working with API definitions.

Note: The GatewayScript policy is available only with the Premium subscription. For more details about the Premium subscription and how to upgrade, see FAQ: Premium subscription .

About this task

During API execution, the activity data is stored in the log context variable, which populates the API event record on completion of the API execution. For more information about log context variables, see API activity logging context variables.

The analytics subsystem stores analytics data as individual API event records. The API event record fields are documented here: API event record field reference. 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.

Procedure

In the navigation pane, click Develop, then click Add > API.
The Select API type screen is displayed.
Select OpenAPI 2.0 or OpenAPI 3.0 according to which version of the OpenAPI specification your API is to be based on.
Select New OpenAPI .
Click Next. Specify the API summary in the Info section. You can fine-tune the API after it is created.
- The Title can include special characters but should be kept short so that it can be easily displayed in the user interface.
- The Name is entered automatically. The value in the Name field is a single string that is used to identify the API in developer toolkit CLI commands. To view the CLI commands to manage draft APIs, see the toolkit CLI reference documentation.
- The Version corresponds to the value of the info.version property of the API's OpenAPI definition. The version.release.modification version numbering scheme is recommended; for example 1.0.0.
- The Base path is the URL segment of the API and does not include the host name or any additional segments for paths or operations. The base path cannot include special characters and must begin with a / character even if it is otherwise empty.
- The optional Description helps to identify the API.
Click Next. In the Secure section, configure the API security that you require.
- Secure using Client ID - Select this option to require an Application to provide a Client ID (API Key). This causes the X-IBM-Client-Id parameter to be included in the request header for the API. If selected, you can then select whether to limit the API calls on a per key (per Client ID) basis:
  - Limit API calls on a per key basis - If selected, you must configure the rate limit that you require. Rate limits control the maximum number of calls allowed within a time period (hour, minute, month or day). For example, 100 calls per hour.
- CORS - Select this option to enable cross-origin resource sharing (CORS) support for your API. This allows your API to be accessed from another domain.
  Note:
  - CORS support is available only on the DataPower® API Gateway.
  - When CORS is enabled, the API Gateway runs the cors preflow policy to handle all CORS requests that are made to the API.
  - When CORS is enabled and a preflight request is received, only the following API actions are performed:
    
    The cors preflow policy configures the appropriate response headers.
    
    The response headers are set.
  - When a preflight request is received, the request.attributes.isCORSPreflight flag is set to true.
  - For all preflight requests, the security and client-identification preflow policies are always skipped, whether CORS is enabled or not enabled.
Click Next to create your API definition.

The Summary panel displays messages as the definition is created, and the selected security options and rate limits are enforced.
To further configure your API, click Edit API. For details, see Editing an API definition.

Select the 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
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.
Ensure that Policies is selected.
On the canvas, click the plus icon at the last position in the flow. The palette listing the available elements to build the assembly flow appears.
From the palette, add the Log policy element onto the canvas by clicking it. Set the log policy Mode drop-down to Gather-only. This step is so that the log context variable is populated, for use in the next step.
Draft comment: iainsoed@uk.ibm.com
I looked into getting an explanation from gateway team of the different options here, but it's all too complex to go into here.
Modify API event data or add custom data either with a gateway script or by using the set-variable operation.
Gateway script method
Note: The GatewayScript policy is available only with the Premium subscription. For more details about the Premium subscription and how to upgrade, see FAQ: Premium subscription .
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
```
Warning: context.log.custom_data supports the addition of primitive typed values such as strings and integers, no limit is enforced on how many you can add, but adding too many does impact performance. Add data only to the context.log.custom_data object. Do not add data to context.log.
The field types cannot be changed. If you attempt to assign a value of the wrong type to a field, then the event record is lost. For example, if you define a custom field as an integer, and a particular API call results in a string being assigned to this variable, then the analytics database does not store the event record for that API call. If your APIs might return different types, then define the new custom_data type as a string and ensure that everything you assign to it is converted to a string before it is assigned.
Publish your new API to a catalog.
Make a test call to the API and verify that the new custom data is set. For more information see, Using the Test tab to debug your API.
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. Verify that your custom data field is present:
Alternatively, 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
```