IBM Tivoli Netcool Connector

The Netcool connector interfaces with the Tivoli Netcool/OMNIbus ObjectServer API. This API allows table data access via HTTP requests.

IBM Tivoli Netcool Connector Configuration

The HTTP API requests are made using basic authentication. The authentication data is stored in an XML format. An example is shown below.

<connector>
    <scenarios>
        <scenario name="_scenario_name_" baseurl="http://host:port/objectserver/restapi/" username="_username_" password="_method_3_encrypted_password_" tls="true_or_false" tls11="true_or_false" tls12="true_or_false" ssl3="true_or_false"></scenario>
    </scenarios>
</connector>

Like most connector actions, each Netcool action has a scenario property which needs to be given a value that matches the name attribute of a scenario defined in this XML. Multiple scenario nodes can be added to this XML configuration to allow the connector access to multiple Netcool environments if needed.

The transport layer security settings can be set using a scenario. Each TLS version can be enabled by setting the attribute equal to "true" and disabled by setting the attribute equal to "false."

For example to only enable TLS 1.2 the TLS attributes would be configured as such:

tls=\"false\" tls11=\"false\" tls12=\"true \" ssl3=\"false\"

Note that the attribute "tls" corresponds with TLS 1.0, "tls11" corresponds with TLS 1.1, etc.

Connector Actions

Create Alert Status

Action Function

The "Create Alert Status" action sends a POST request to the endpoint:

http://host:port/objectserver/restapi/alerts/status (opens new window)

This endpoint allows users to create a row in the Netcool status table in its alerts database.

Action Outputs:

Success

Failure

Action Properties:

The action has a number of properties, most of which match the row columns to be inserted into the status table.

This action, as well as the other Netcool actions, have several generic properties which are properties of the action itself and aren't sent to the API interface.

The first of these properties is the scenario property, whose value will tell the action to use a specific authentication scenario when authenticating to the HTTP endpoint.

There is a web timeout property which specifies the number of seconds the request will be given before a timeout occurs. If this property is left blank, the action will use the default timeout of the Netcool API.

There is a response variable and an error variable property. If the endpoint returns a response to the request, the variable defined in the response property will be populated. If the action has an error, the error variable will be set to the error message returned.

Scenario: The name of the scenario defined in the connector configuration.

Identifier: Refers to the identifier column in the in the alerts.status table.

Node: Refers to the node column in the in the alerts.status table.

Type: Refers to the type column in the in the alerts.status table.

Manager: Refers to the manager column in the in the alerts.status table.

Acknowledged: Refers to the identifier column (integer) in the in the alerts.status table.

Agent: Refers to the agent column in the in the alerts.status table.

Web Timeout: How long in seconds the HTTP request is given before timing out. Leave blank to use the default timeout setting.

Response Variable: A workflow variable which will hold the response of the request. The data format is JSON

Error Message Variable: A workflow variable which will hold the error message (if any)

Delete Alert Status

Action Function

The "Delete Alert Status" action deletes a row in the status table found in the alerts database. The endpoint it sends its DELETE request is dependent upon how its properties are set.

Action Outputs:

Success

Failure

Action Properties:

This action has 3 properties to determine which row or rows will be deleted from the status table. Only one of these 3 properties should be defined at a time.

The first is the Filter property which defines the conditions that a row in the table must satisfy. It is the WHERE clause of a SQL SELECT statement.

The second is the Row Serial property. Each table row has an integer value (the RowSerial value) that uniquely identifies that row in that particular table. Pass in the row's RowSerial value to delete the corresponding row.

The last is the Keyfield property. The Keyfield is also a unique identifier for a given row.

If the Filter property is used, the endpoint is:

http://host:port/objectserver/restapi/alerts/status (opens new window)

If the Row Serial property is defined, the endpoint is:

http://host:port/objectserver/restapi/alerts/status/rowserial/ (opens new window)

If the Keyfield property is used, the endpoint is:

http://host:port/objectserver/restapi/alerts/status/kf/keyfield/ (opens new window)

Scenario: The name of the scenario defined in the connector configuration.

Filter: Defines the conditions that a row in the table must satisfy. It is the WHERE clause of a SQL SELECT statement.

Row Serial: Each table row has an integer value (the RowSerial value) that uniquely identifies that row in that particular table.

Keyfield: A unique identifier for a specific row.

Web Timeout: How long in seconds the HTTP request is given before timing out. Leave blank to use the default timeout setting.

Response Variable: A workflow variable which will hold the response of the request. The data format is JSON

Error Message Variable: A workflow variable which will hold the error message (if any)

An example of the "Delete Alert Status" action setup is show below.

Get Alert Status

Action Function

The "Get Alert Status" action sends a GET request to the following endpoint:

http://host:port/objectserver/restapi/alerts/status (opens new window)

Action Outputs:

Success

Failure

Action Properties:

There are 3 properties which can be used separately or in combination to get specific rows or details from the status table in the alerts database.

The first is the Filter property which is the WHERE clause of a SQL SELECT statement.

The second is the Collist property whose value specifies which columns of the table to return.

The last is the Order By property which defines the sort order of the response.

Scenario: The name of the scenario defined in the connector configuration.

Filter: Defines the conditions that a row in the table must satisfy. It is the WHERE clause of a SQL SELECT statement.

Collist: Specifies the columns of the table to return.

Order By: Defines how to sort the order of the response.

Web Timeout: How long in seconds the HTTP request is given before timing out. Leave blank to use the default timeout setting.

Response Variable: A workflow variable which will hold the response of the request. The data format is JSON

Error Message Variable: A workflow variable which will hold the error message (if any)

Netcool Get

Action Function

The "Netcool Get" action is a generic action which will access the endpoint:

http://host:port/objectserver/restapi/database/table (opens new window)

Action Outputs:

Success

Failure

Action Properties:

Where the database and table values in the URI are defined in the action properties. It has the Filter, Collist, and Order By properties which are described in the "Get Alert Status" action section of this document.

Scenario: The name of the scenario defined in the connector configuration.

Database Name: The name of the database to perform the Get.

Table Name: The name of the table to perform the Get.

Filter: Defines the conditions that a row in the table must satisfy. It is the WHERE clause of a SQL SELECT statement.

Collist: Specifies the columns of the table to return.

Order By: Defines how to sort the order of the response.

Web Timeout: How long in seconds the HTTP request is given before timing out. Leave blank to use the default timeout setting.

Response Variable: A workflow variable which will hold the response of the request. The data format is JSON

Error Message Variable: A workflow variable which will hold the error message (if any)

SQL Command

Action Function

The "SQL Command" action sends a POST request to the endpoint:

http://host:port/objectserver/restapi/sql/factory (opens new window)

This action sends a SQL command which will be executed on the Netcool ObjectServer.

Action Outputs:

Success

Failure

Action Properties:

To use this action, the authentication scenario user needs the permission "AllowISQL" for read SQL commands and the "AllowISQLWrite" permission for write SQL commands.

Scenario: The name of the scenario defined in the connector configuration.

SQL Command: A SQL statement to return a particular set of data.

Web Timeout: How long in seconds the HTTP request is given before timing out. Leave blank to use the default timeout setting.

Response Variable: A workflow variable which will hold the response of the request. The data format is JSON

Error Message Variable: A workflow variable which will hold the error message (if any)

Update Alert Journal

Action Function

The "Update Alert Journal" action issues a PATCH request to the endpoint:

http://host:port/objectserver/restapi/alerts/journal/rowserial/ (opens new window)

Or

http://host:port/objectserver/restapi/alerts/journal/kf/keyfield/ (opens new window)

Dependent upon if the Row Serial property value or the Keyfield property value is populated. The action updates the Text1 column in the Journal table.

Action Outputs:

Success

Failure

Action Properties:

Scenario: The name of the scenario defined in the connector configuration.

Row Serial: Each table row has an integer value (the RowSerial value) that uniquely identifies that row in that particular table.

Keyfield: A unique identifier for a specific row.

Text1: The column to be updated in the Journal table.

Web Timeout: How long in seconds the HTTP request is given before timing out. Leave blank to use the default timeout setting.

Response Variable: A workflow variable which will hold the response of the request. The data format is JSON

Error Message Variable: A workflow variable which will hold the error message (if any)

Update Alert Status

Action Function

The "Update Alert Status" action sends a PATCH request to one of three endpoints:

If the Filter property is used, the endpoint is:

http://host:port/objectserver/restapi/alerts/status (opens new window)

If the Row Serial property is defined, the endpoint is:

http://host:port/objectserver/restapi/alerts/status/rowserial/ (opens new window)

If the Keyfield property is used, the endpoint is:

http://host:port/objectserver/restapi/alerts/status/kf/keyfield/ (opens new window)

This action updates the alerts database status table.

Action Outputs:

Success

Failure

Action Properties:

This action updates the alerts database status table. Multiple rows can be updated by using the filter property or a single row can be updated using the Keyfield or Row Serial property.

Scenario: The name of the scenario defined in the connector configuration.

Filter: Defines the conditions that a row in the table must satisfy. It is the WHERE clause of a SQL SELECT statement.

Row Serial: Each table row has an integer value (the RowSerial value) that uniquely identifies that row in that particular table.

Keyfield: A unique identifier for a specific row.

Acknowledged: A Boolean value. 1 is true. 0 is false.

Location:

OwnerUID:

OwnerGID:

LastOccurrence:

Web Timeout: How long in seconds the HTTP request is given before timing out. Leave blank to use the default timeout setting.

Response Variable: A workflow variable which will hold the response of the request. The data format is JSON

Error Message Variable: A workflow variable which will hold the error message (if any)