Example ZSA API Requests

Introduction

This article describes using some of the APIs related to the ZSA module. The examples below assume you have already done the following:

• Obtained your user token (according to Obtaining the Token Parameter).
• Have opened the ZSA API page (by clicking the Data API () icon and clicking Show APIs in the ZSA panel).

Listing Existing ZSA Messaging Agents

You can list the existing ZSA messaging agents as follows:

1. Within the MvsServer functional group, expand the API GET method /zsa/api/v1/servers and click Try it out.
2. In the ZHB Security Token field, specify your user token and click Execute.
   

The Response body area returns a JSON for every messaging agent that has been created. In the example above we see how two of the visible JSONs correspond to two messaging agents that are displayed in the messaging panels of the ZSA Configuration - Messaging page.
It is interesting to observe the JSON for a messaging agent, and how it corresponds to the messaging agent's configuration.
Four types of messaging agent can be created and edited via the ZSA Configuration - Messaging page (see this article) as well as via the API POST method /zsa/api/v1/servers/ (see Creating ZSA Messaging Agents below). The table below summarizes the four messaging types and the properties used by the JSON to define a messaging agent.

Creating ZSA Messaging Agents

To create a messaging agent that connects to a mainframe's LPAR you must know the following details:

• hostname or IP address of the LPAR
• port (typically 9999)
• LPAR name
• System name
• SID used by all the mainframe's SMF records

:::
In the example below we use the API POST method /zsa/api/v1/servers to create three different messaging agents as summarized in the table below.

To create messaging agents based on the example above, do the following:

1. Within the MvsServer functional group, expand the API POST method /zsa/api/v1/servers and click Try it out.
2. In the ZHB Security Token specify your user token.
3. In the Request body area, specify the following JSON for the messaging agent CSV 1.

{
    "name": "CSV 1",
    "description": "CSV data on LPAR 1",
    "hostName": "17.105.9.56",
    "portNumber": 9999,
    "type": 0,
    "instanceQuantity": 3
  }

5. Click Execute.
   
6. In the Response body area verify that the lparName, systemName, and sid properties provided by the mainframe correspond to the values you expect.
7. In the Request body area, specify the following JSON for the messaging agent RAW 1.

{
    "name": "RAW 1",
    "description": "CSV data on LPAR 1",
    "hostName": "17.105.9.56",
    "portNumber": 9999,
    "type": 1,
    "keepUnknownRecord": true,
    "instanceQuantity": 2
  }

5. Click Execute.
   
6. In the Response body area verify that the lparName, systemName, and sid properties provided by the mainframe correspond to the values you expect.
7. In the Request body area, specify the following JSON for the messaging agent Connection 1.

{
    "name": "Datasource 1",
    "description": "Datasource on LPAR 1",
    "hostName": "17.105.9.56",
    "portNumber": 9999,
    "type": 2,
    "instanceQuantity": 2
  }

8. Click Execute.
   

Updating Messaging Agents

You can use the API PUT method /zsa/api/v1/servers/{mvsName} to update the connection configuration of an existing messaging agent. You need to know the name of the messaging agent that you want to update.

For example, the RAW 1 messaging agent created in Creating ZSA Messaging Agents was configured to keep unknown records and have two connection instances. If you want to change the RAW 1 messaging agent to not keep unknown records and have three connection instances you would do the following:

1. Within the MvsServer functional group, expand the API POST method /zsa/api/v1/servers/{mvsName} and click Try it out.

2. In the mvsName field type the name of the messaging agent you want to update (e.g. RAW 1).

3. In the ZHB Security Token specify your user token.

4. In the Request body area, specify a JSON with the all of the properties for the messaging agent that you want to update (i.e. the properties that you do not want to update and the properties that you do want to update).

{
    "name": "RAW 1",
    "description": "CSV data on LPAR 1",
    "hostName": "17.105.9.56",
    "portNumber": 9999,
    "lparName": "IBMSYS1",
    "systemName": "S0W1",
    "sid": "S0W1",
    "type": 1,
    "keepUnknownRecord": false,
    "instanceQuantity": 3
  }

5. Click Execute.
   

Deleting Messaging Agents

You can use the API DELETE method /zsa/api/v1/servers/{mvsName} to delete an existing messaging agent. You need to know the name of the messaging agent that you want to delete.

For example, if you want to delete the RAW 1 messaging agent created in Creating ZSA Messaging Agents you would do the following:

1. Within the MvsServer functional group, expand the API DELETE method /zsa/api/v1/servers/{mvsName} and click Try it out.
2. In the mvsName field type the name of the messaging agent you want to delete (e.g. RAW 1).
3. In the ZHB Security Token specify your user token.
4. Click Execute.
   

Duplicating Messaging Agents

You can use the API POST method /zsa/api/v1/servers/{mvsName} to duplicate an existing messaging agent. You need to know the name of the messaging agent that you want to duplicate.

For example, if you want to duplicate the CSV 1 messaging agent created in Creating ZSA Messaging Agents you would do the following:

1. Within the MvsServer functional group, expand the API POST method /zsa/api/v1/servers/{mvsName} and click Try it out.
2. In the mvsName field type the name of the messaging agent you want to duplicate (e.g. CSV 1).
3. In the duplicateName field type the name of the duplicate messaging agent that will be created (e.g. CSV 2).
4. In the ZHB Security Token specify your user token.
5. Click Execute.
   
6. Once the duplicated messaging agent is created you can optionally modify it according to Updating Messaging Agents.

Starting a Messaging Agent

You can use the API POST method /zsa/api/v1/servers/{mvsName}/messaging/start to start an existing messaging agent. You need to know the name of the messaging agent that you want to start.

For example, if you want to start the CSV 1 messaging agent created in Creating ZSA Messaging Agents you would do the following:

1. Within the MvsServer functional group, expand the API POST method /zsa/api/v1/servers/{mvsName}/messaging/start and click Try it out.
2. In the mvsName field type the name of the messaging agent you want to start (e.g. CSV 1).
3. In the ZHB Security Token specify your user token.
4. Click Execute.
   

Stopping a Messaging Agent

You can use the API POST method /zsa/api/v1/servers/{mvsName}/messaging/stop to stop an existing messaging agent. You need to know the name of the messaging agent that you want to stop.

For example, if you want to stop the CSV 1 messaging agent created in Creating ZSA Messaging Agents you would do the following:

1. Within the MvsServer functional group, expand the API POST method /zsa/api/v1/servers/{mvsName}/messaging/stop and click Try it out.
2. In the mvsName field type the name of the messaging agent you want to stop (e.g. CSV 1).
3. In the ZHB Security Token specify your user token.
4. Click Execute.
   

Getting the Current Messaging Configuration of a Messaging Agent

You can use the API GET method /zsa/api/v1/servers/{mvsName}/messaging/configuration to obtain the current messaging configuration of an existing messaging agent. You need to know the name of the messaging agent whose messaging configuration you want to obtain.

For example, if you want to obtain the configuration of the CSV 1 messaging agent created in Creating ZSA Messaging Agents you would do the following:

1. Within the MvsServer functional group, expand the API GET method /zsa/api/v1/servers/{mvsName}/messaging/configuration and click Try it out.
2. In the mvsName field type the name of the messaging agent whose configuration that you want to obtain (e.g. CSV 1).
3. In the ZHB Security Token specify your user token.
4. Click Execute.
   

The Response body area returns the messaging configuration properties of the messaging agent that you specified, which vary according to the messaging agent type as summarized in Table 1, Table 2 and Table 3 located in the Updating the Current Configuration of a Messaging Agent section.

Updating the Current Messaging Configuration of a Messaging Agent

You can use the API POST method /zsa/api/v1/servers/{mvsName}/messaging/configuration to update the current messaging configuration of an existing messaging agent. You need to know the name of the messaging agent whose messaging configuration you want to update.

The properties that you can use to update messaging agent's configuration vary according to the messaging agent type as summarized in Table 1, Table 2 and Table 3.

Table 1: Properties for a CSV (type 0) messaging agent

Table 2: Properties for a Connection (type 2) messaging agent

Table 3: Properties for a CSV Parser (type 3) messaging agent

In our example below we update the configuration of the CSV 1 messaging agent (type 0) according to the table 4.

Table 4: Example of updating properties for a CSV (type 0) messaging agent

To update the messaging configuration of the CSV 1 according to Table 4, you would do the following:

1. Within the MvsServer functional group, expand the API POST method /zsa/api/v1/servers/{mvsName}/messaging/configuration and click Try it out.
2. In the mvsName field type the name of the messaging agent whose configuration that you want to update (e.g. CSV 1).
3. In the ZHB Security Token specify your user token.
4. In the Request body area, specify one of the following JSONs:
   JSON example 1: with only the necessary properties (i.e. the ones you are changing).

{
  "configurationProperties": [
    {
      "name": "MsgSize",
      "value": "125"
    },
    {
      "name": "MsgSizeWaiting",
      "value": "125"
    },
    {
      "name": "PollTime",
      "value": "35"
    },
    {
      "name": "ThreadPriority",
      "value": "1"
    },
    {
      "name": "ParserWorkerThreads",
      "value": "2"
    },
    {
      "name": "ConnectionThreads",
      "value": "2"
    }
  ]
}

JSON example 2: includes all the properties (i.e. the ones you are changing and the ones you are not changing).

{
  "configurationProperties": [
    {
      "name": "MsgSize",
      "value": "125"
    },
    {
      "name": "MsgSizeWaiting",
      "value": "125"
    },
    {
      "name": "PollTime",
      "value": "35"
    },
    {
      "name": "FlushTime",
      "value": "180"
    },
    {
      "name": "MaxBulkInsertRows",
      "value": "1000"
    },
    {
      "name": "StatisticsTime",
      "value": "5000"
    },
    {
      "name": "ThreadPriority",
      "value": "1"
    },
    {
      "name": "ParserWorkerThreads",
      "value": "2"
    },
    {
      "name": "ConnectionThreads",
      "value": "2"
    }
  ]
}

5. Click Execute.
   

Obtaining the Default Messaging Configuration for Messaging Agents

You can use the API GET method /zsa/api/v1/servers/messaging/configuration to obtain the default messaging configuration that can then be used to reset your messaging agents back to their defult values.
To do this, proceed as follows:

1. Within the MvsServer functional group, expand the API GET method /zsa/api/v1/servers/{mvsName}/messaging/configuration and click Try it out.
2. In the ZHB Security Token specify your user token.
3. Click Execute.
   The Response body updates with an output similar to the following.
   
   The Response body area returns the default messaging configuration properties for all the types of messaging agent, as summarized in Table 1, Table 2 and Table 3 located in the Updating the Current Configuration of a Messaging Agent section.
4. You can use the copy to clipboard icon to copy the JSON defining the default messaging configuration and paste it into the Request body area of the API POST method /zsa/api/v1/servers/{mvsName}/messaging/configuration in order to reset a messaging agent back to its default values.

Starting All Messaging Agents of a Certain Type

You can use the API POST method /zsa/api/v1/servers/{type}/start to start all messaging agents of a certain type.
To start all messaging agents of a certain type do the following:

1. Within the MvsServer functional group, expand the API POST method /zsa/api/v1/servers/{type}/start and click Try it out.
2. In the Agent Type drop-down field select the type (0, 1, 2, or 3) corresponding to the messaging agent types that you want to start.
   • 0 - all messaging agents of the type RAW will be started
   • 1 - all messaging agents of the type CSV will be started
   • 2 - all messaging agents of the type Connector will be started
   • 3 - all messaging agents of the type CSV Parser will be started
3. In the ZHB Security Token specify your user token.
4. Click Execute.
   

Stopping All Messaging Agents of a Certain Type

You can use the API POST method /zsa/api/v1/servers/{type}/stop to stop all messaging agents of a certain type.
To stop all messaging agents of a certain type do the following:

1. Within the MvsServer functional group, expand the API POST method /zsa/api/v1/servers/{type}/stop and click Try it out.
2. In the Agent Type drop-down field select the type (0, 1, 2, or 3) corresponding to the messaging agent types that you want to stop.
   • 0 - all messaging agents of the type RAW will be stopped
   • 1 - all messaging agents of the type CSV will be stopped
   • 2 - all messaging agents of the type Connector will be stopped
   • 3 - all messaging agents of the type CSV Parser will be stopped
3. In the ZHB Security Token specify your user token.
4. Click Execute.