RESTfulAPIPOST

The RESTfulAPIPOST function sends resources to a RESTful API.

You can use the RESTfulAPIPOST function to issue HTTP POST requests to RESTful APIs.

You can connect through a proxy server if the data source has enabled it. To enable SSL connections between Netcool/Impact servers and external servers, refer to the Enabling SSL connections with external servers topic within the Security chapter of the Netcool/Impact Administration Guide.

Syntax

The following is the syntax for RESTfulAPIPOST:

RESTfulAPIPOST(DataSource, Path, Config)

Parameters

The RESTfulAPIPOST function has the following parameters.

Table 1. RESTfulAPIPOST function parameters
Parameter	Format	Description
`DataSource`	String	Name of the data source defined in the data model.
`Path`	String	URL path after the hostname to the resource to which you want to post.
`Config`	String \| Object	Object containing any extra request information that you want to add to the request. The object must contain name-value pairs. Valid variables are: `Params`: Any extra HTTP parameters to be added to, or overridden from, the data model. `Headers`: Any extra HTTP headers to be added to, or overridden from, the data model. `ConnectionTimeout`: Sets the timeout until a connection is established. The default value is 0, which means that timeout is not used. `ResponseTimeout`: Sets the default socket timeout (`SO_TIMEOUT`) in milliseconds. This is the timeout for waiting for data. If you set the timeout to `0`, the function waits indefinitely for a response from the socket. `Data`: Content that you want to send to the API. `File`: File that you want to send to the API. `TrustCertificate`: If set to true, the function will try to connect without verifying the SSL connection and checking whether the required SSL certificates exist in the truststore. `AlwaysSendAuth`: If set to true, always send the `Authorization` header. Normally, authorization credentials are only sent in response to a challenge from the server.¹ `FollowRedirect`: The function will follow redirects by default. Set this to `NEVER` to ignore the redirect and return immediately. If using a `POST` request, set this to `KEEP_POST` to preserve the `POST` method and body when traversing redirects. `ResponseParser`: The function will automatically attempt to convert JSON responses into an Impact policy object. The conversion of JSON payloads can be disabled by setting this property to `off`.²

¹ Starting in Fix Pack 7.1.0.27, the default value for AlwaysSendAuth was changed to true.

² Starting in Fix Pack 7.1.0.32, the off option will also turn off validation of the incoming JSON payload.

Return Values

When you call the RESTfulAPIPOST function, it outputs the following variables:

status: The status code associated with the HTTP call.
data: The body of the HTTP response. If the body contains a payload with the application/json content type, the payload will be automatically converted into a Impact policy object.
config: The configuration object sent to the data source.
statusTextThe status text associated with the latest response.
headers: The HTTP response headers.
dataText: The body of the HTTP response in plain text format.

Example 1

A RESTfulAPIPOST request to send data through the parameters property:


var config = {};
config['params'] = { channel: '#general', text: 'Hello Slack!' };
var result  = RESTfulAPIPOST("Slack", "chat.postMessage", config);
Log("Result:" + result);

Example 2

A RESTfulAPIPOST request to send an event to the IBM Alert Notification Service:


data = {};
config = {};
data[’What’] = ’Disk Space Full’;
data[’Where’] = ’SiteABC’;
data[’Severity’] = ’Major’;
config[’data’] = data;
var result = RESTfulAPIPOST("IBMAlertNotification", "", config);
Log("Result:"+result);

Example 3

A RESTfulAPIPOST request to post a new row to the ObjectServer:


var coldescArr = '[{ "type":"string", "name":"Identifier"}]';
                
var data = '[{"Identifier":"ImpactEventInstance0000" }]';
		  
var osdata = '{"rowset": { "coldesc":' + coldescArr +
             ' ,"rows": ' + data +
             '} }';
Config = {};
Config['data'] = osdata;
Log(osdata);
var osResponse = RESTfulAPIPOST("ObjectServerRest","", Config);
Log("OS Response:" + osResponse);

Example 4

A Javascript policy that sends a POST request with JSON content and checks the response code before parsing the JSON response.

var postresponse;

function postJSON(DS, POSTBODY) {

  Config = NewObject();
 
  // Set the config object
  Config.TrustCertificate = true;
  Config.AlwaysSendAuth = true;
  Config.ConnectionTimeout = Int(60000);
  Config.ResponseTimeout = Int(60000);

  // Add the header
  Config.Headers = NewObject();
  Config.Headers['Content-Type'] = 'application/json; charset=UTF-8';

  // Set the request body
  Config.Data=''+POSTBODY;

  // Send the POST request
  postresponse= RESTfulAPIPOST(DS, '/rest/db', Config);

  // Check the response code
  if (postresponse.status != 200) {
    throw("POST failed with status " + postresponse.statusText);
  } else {
    var jsonObj = ParseJSON(postresponse.data);
    return jsonObj;
  }

}

var result= postJSON('restdatasource', '{"node":"manager", "id":"45612"}');
Log(result);

Example 5

version 7.1.0.28+ A RESTfulAPIPOST request that uploads a form. The content-type should be set to application/x-www-form-urlencoded. The form entries should be added to the data attribute of the Config parameter as a set of key/value string pairs:

var Config = {};

// Create a NewObject to hold the form values
// and add it to the data attribute
var formObj = {};
formObj['grant_type']='client_credentials';
formObj['resource']='example';
formObj['client_id']='test';
Config['data'] = formObj;

// Set the Content-Type
var headers = NewObject();
headers['Content-Type']='application/x-www-form-urlencoded';
Config.headers = headers;     

var osResponse = RESTfulAPIPOST("test","/post/form",Config);
Log("OS Response:" + osResponse);

Example 6

version 7.1.0.28+ A RESTfulAPIPOST request that uploads files to the endpoint. In the Config parameter, create a file attribute. The file attribute should be an object which contains the key/value pairs of each file you want to upload:

var Config = {};

// Declare the file attribute object
// In the file object, the key can be any arbitrary name. The value should be the file path
Config['file'] = {"file1":"/opt/IBM/tivoli/impact/test.xml", "file2":"/opt/IBM/tivoli/impact/patch.csv"};

var osResponse = RESTfulAPIPOST("test","/post/file",Config);
Log("OS Response:" + osResponse);