Server Automation REST APIs

The Server Automation REST API lets you execute, schedule, and monitor Automation Plans over HTTPS using a standard, OS-independent interface; first-time connections may require trusting a self-signed certificate.

It offers Java- and NodeJS-based deployments (with new features on the NodeJS service) and a simple workflow where a GET returns plan XML to complete, and a POST executes the plan, with a predictable URL structure and Swagger documentation.

Interacting with Server Automation via the REST API

You can execute and monitor Automation Plans through the REST API. Using the REST API allows you to perform these tasks in a standardized, operating system-independent method.

Note: All REST API requests require the use of the HTTPS protocol.

The REST API implements SSL (HTTPS) using a self-signed certificate, so the first time a client attempts to connect to it, they may be required to first accept/trust the certificate. This is especially true if the client is a web browser (or browser plugin, such as Firefox's Poster). The confirmation request would occur only the very first time a connection attempt is made. The same would be true of the demo application.

Deployment environment

Server Automation supports two versions of the REST API to utilize the service as follows:

Java-based web application deployed within a WebSphere Application Server with Liberty Profile
NodeJS-based web application

Note: New functionality will be made available only on the Node-based application, and hence, the Java-based version (Fixlets 108 and 109 of SA REST API) will be phased out shortly.

Java-based web application

This REST API is a Java-based web application deployed within an IBM WebSphere Application Server (WAS) with Liberty Profile. This application is installed/uninstalled by means of two tasks that can be found on the "Server Automation" site, namely:

(ID: 108) Deploy Server Automation REST API
(ID: 109) Remove Server Automation REST API

Starting and stopping this server are controlled by means of a Windows service called "WASLibertyService". This service is automatically started after installation but requires manual starting after a host machine restart. The server logs can be found at:

<INSTALL ROOT>\wlp\usr\servers\defaultServer\logs

NodeJS-based web application

The NodeJS-based REST API is installed/uninstalled by means of two tasks that can be found on the "Server Automation" site, namely:

(ID: 157) Deploy Server Automation REST API
(ID: 158) Remove Server Automation REST API

The starting and stopping of this service are controlled by means of a Windows service called "SARESTService". The server logs can be found at:

<INSTALL ROOT>\sa_rest_node\Logs

Note:

In Fixlet (ID: 157), both HTTP and HTTPS ports are configurable. The default HTTP port is 8080 and the HTTPS port is 8443. The user needs to update the default HTTP and HTTPS ports before installation. If the computer already runs the legacy WAS Liberty-based service, the user can still install Fixlet 157 on any available ports.
The application runs only on Windows computers.

How it works

Using the REST API, you submit the ID of an existing plan (Fixlet) via a URL (a GET operation). This retrieves a simplified XML structure representing all of the data required to run that plan. The client must then complete this XML and return it to the REST API to execute the automation plan (a POST operation).

Note: Server Automation REST API is also available in Swagger UI-compatible format at https://localhost:8443/serverautomation/api-docs/.

Between the time the XML is received from REST and sent back for execution, clients can modify this XML to:

Schedule a plan action
Specify a custom name for new plan actions created via REST
Enable/disable pre-fetching

When executing the plan, the client must specify the following for each plan step before execution:

any required parameters for a plan step
any required parameters for the corresponding failure step (if a failure step has been defined)
one or more target computers (by name and/or ID) or one or more target groups (by name)

The REST API response to on successful execution of an automation plan is the ID of the new plan action. If the client supplies invalid XML, the REST API will return an HTTP Error 400 "Bad Request". If the client supplies the ID of a plan that does not exist, the REST API will return an HTTP Error 404 "Not Found". If an internal or unexpected error occurs, the REST API will return a HTTP Error 500 "Internal Server Error". The API is not responsible for authenticating the client login details. The underlying BigFix API authenticates when it is first invoked. The Server Automation REST API requires the HTTPS protocol (as does the demo application).

Demonstration application

Server Automation provides a demo application that shows how you can use the REST API to complete the following functions:

Run an Automation Plan
Schedule an automation plan action
Specify a custom name for a plan action before creating it
Enable pre-fetching
Monitor a running Automation Plan

Functionality

You can use the REST API to complete the following:

Run an Automation Plan
Schedule an automation plan action
Specify a custom name for an automation plan action when creating it
Enable pre-fetching
Monitor a running Automation Plan
Use a plan containing Fixlets requiring parameter encryption
Use a plan containing Fixlets with advanced parameters

General URL format

Requests must conform to this basic format:

/serverautomation/{resource}/{site type}/{site name}/{object id}

Table 1. REST APIs Path Attributes
Path attribute	Description
{resource}	The desired resource: plan planaction
{site type}	The type of site: master custom operator external
{site name}	The name of the site, for example, Server Automation. This is not required for the master action site. The operator name is the site name for operator sites.
{object id}	The ID of the object that you are requesting; this varies by context but is generally the integer value ID of an object in the database. If the OBJECT_ID is not supplied, the request might display a description of objects in this site for this resource.

Scheduling settings

After the 9.5.72 release, SA REST API uses the following format for scheduling settings to enable scheduling:

Set <HasStartTime> to 'true' and use "StartDateTime" to set dd-MMM-yyyy, HH:mm:ss, for example, 01-May-2025,06:20:39.
Set <HasEndTime> to 'true' and use "EndDateTime" to set dd-MMM-yyyy, HH:mm:ss, for example, 01-May-2025,06:20:39.

Note:

The end time setting only controls when the resulting plan action expires.
By default, the SA REST API considers the client local time only.

Sample response content

<?xml version="1.0" encoding="UTF-8"?>
     <sa-rest xmlns="http://iemfsa.tivoli.ibm.com/REST" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
          <execute-plan action-name="MEPPRD-Z372-Plan BigFix Plan for Verify BigFix Services" prefetch="false">
               <step sequence="101" name="Run Plan MEPPRD-Z372-Plan BigFix Plan for Verify BigFix Services">
                    <target-set>
                         <computer name="WINBIGFIX95" id="6215959"></computer>
                    </target-set>
               </step>
     <schedule>
          <HasStartTime>false</HasStartTime>
          <StartDateTime>01-May-2025,06:20:39</StartDateTime>
          <HasEndTime>false</HasEndTime>
          <EndDateTime>03-May-2025,06:20:39</EndDateTime>
     </schedule>
    <execution-order>
          <step id="101" depends="">
               <on-failure action="StopPlan" targets="IncludeFailed" threshold="0"></on-failure>
          </step>
     </execution-order>
  </execute-plan>
</sa-rest>