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 API Studio.
Click New API project > Create blank project on the home page.
The New API project screen appears.
Choose the storage location for the project.
- From repository. Configure the repository separately. For more information, see Configuring version control system.
- From local folder. Configure the local directory and allow access. For more information, see Configuring projects folder.
  Note: Google Chrome and Microsoft Edge support the Local directory option. Other browsers disable this option and restrict file or folder selection, limiting access to existing APIs and projects.
- From native storage. No configuration required.
  Note: This option is not available in the desktop app.
Provide the project details.
- Repository. Choose the repository. This applies only to the repository storage.
- Branch. Choose the branch. This applies only to the repository storage.
- Local directory. Choose the local folder. This applies only to the local storage.
- Project name. Enter a name for your project.
- Description. Add a brief summary or purpose of the project.
- Tags. Add relevant tags to categorize or identify the project easily.
Click Create.

The API project is created and displayed on the home page. You can start working on your APIs and policies within the project.
After you create the new project, select the project to open it.
To create new API, click Add an API > Create. For more information, see Creating APIs.
After you add the API to the project, click plus icon next to Policy sequences.
Select the gateway. Available options are DataPower Nano Gateway, DataPower Gateway (v5c) DataPower API Gateway, and webMethods API Gateway.
Provide the policy sequence details.
- Policy sequence name
- Namespace
- Version
- Tags
Select the API and click Add.

The policy sequence is created under Policy sequences section.
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.
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
```