Calling the SAP Control API

The SAP Control API provides basic management services for system, instances and single server processes. This API is offered by SAP and can be called by a SOAP web request call however since Avantra 23.0, we supply a built in object to simplify this.

Calling the SAP Control API and access to the sapControl global object in particular is only available if the script is running for a system type of SAP System or SAP Instance.

Code Walkthrough

The object sapControl is the key object that allows access to the SAP Control API. By default it is logged in with the SAP Control credentials provided to Avantra, however you can replace these credentials at runtime if required.

Calling a program through the API

Calling programs using the SAP Control API is easy. The SAP API takes the given program and executes returning the results or, optionally, running this in the background. This API provides an alternative to SSH where this is not possible.

All API calls are performed from the global variable sapControl. In this example we use the default credentials for SAP control provided to Avantra.

const lsResult = sapControl.osExecute("/bin/ls")

Dealing with results of this API is easy as the returned object has methods to access the command’s exit code (exitcode) and the standard output (out) that can be processed in your script.

const lsResult = sapControl.osExecute("/bin/ls")
if (lsResult.exitcode === 0) {
    // Handle directory listings
    if (lsResult.out.includes("theBadFile.txt")) {
        check.status = CRITICAL
        check.message = "The bad file was found on this system"
    } else {
        check.status = OK
        check.message = "File not found"
    }
} else {
    check.status = CRITICAL
    check.message = "Could not read the SAP directory. Error: " + lsResult.out
}

In this example, we create a simple check that detects the presence of a file on the SAP system. If this file is present then we cause the check to be critical otherwise the check is OK.

If we wanted to process each of the files returned we can separate by the line ending (always \n) and check these individually.

Handling different platforms

In this example we use the command '/bin/ls' which will not work on Windows based SAP systems. There are a couple of different ways we can make this more generic.

The first approach is to use the os global object we can determine the underlying operating system for locally monitored systems using the osName property.

Alternatively, for remotely monitored systems (agentless) we can use the SAP Control API to try platform dependent commands to determine the underlying operating system.

Lastly, we could design separate platform dependent checks that work on a specific platform and assign these to systems using a well crafted system selector. This approach may keep the development complexity lower.

API Reference

Global Variable sapControl

Global variable sapControl is an instance of SAPControlHost. Use this variable to call methods of this class directly in your code, e.g

const myValue = sapControl.loginWith(..);

See SAPControlHost for further documentation on these methods.

Class OSExecuteResponse

Represents the result of an osExecute operation containing a return code exitcode and the output out.

getOut( )

getOut(): string

The result of the executed command as text.

If multiple lines are returned, the line ending is \n.

Since

23.0

See Also

exitcode

exitcode: number

The return code of the executed command

Type

number

Since

23.0

out

readonly out: string

The result of the executed command as text.

If multiple lines are returned, the line ending is \n.

See Also
Type

string

Modifiers

Readonly

Since

23.0

Class ParameterValueResponse

This is returned as the result of the sapControl.parameterValue(..) method and contains the parameter value.

value

value: string

The value of the SAP profile parameter

Type

string

Since

23.0

Class SAPControlHost

The global variable sapControl provides easy access to the SOAP based SAP Control API that SAP offers to control SAP systems. Use this API with SAP Control credentials (or the default credentials) to enhance automations.

getAllEnvironment( )

getAllEnvironment(): object

Utility method to read all environment variables of the SAP system.

// Read all SAP environment variables
const values = sapControl.getAllEnvironment();
Since

24.0

Returns

object

all environment variables

See Also

getEnvironment(..)

getEnvironment(name: string): string

Utility method to read the environment variable value of the SAP system.

// Read the SAP environment variable `OS`
const value = sapControl.getEnvironment("OS");
Since

24.0

Parameters

  • name: string

    the environment variable name to read

Returns

string

the value of the environment variable

getSAPControlURL( )

getSAPControlURL(): string

The URL of the SAP Control API web service. Useful if you want to construct your own queries or debug this API.

Since

23.0

Returns

string

the SAP Control API web service URL

See Also

loginWith(..)

loginWith(credentials: any): SAPControlHost

Create an SAPControlHost object using specific credentials in case default Avantra monitoring SAP control credentials are not appropriate. The returned object has the same methods available as the global object sapControl.

If wrong credentials are used there will be exceptions when using the sapControl API. This method does not validate the credentials.

Use the monitoredSystem global object to read credentials for use with this method.

For example:

const creds = monitoredSystem.getCredential("namespace.name")
const sapControlAPI = creds != null ? sapControl.loginWith(creds) : sapControl

// use sapControlAPI in the same way you would use sapControl, e.g.
const lsResult = sapControlAPI.osExecute("/bin/ls -la")
// Process directory listing...
Since

23.0

Parameters

  • credentials: any

    SAP Control type credentials to connect to the SAP Control API with

Returns

SAPControlHost

an SAPControlHost object that will call the API with the specified credentials

osExecute(..)

osExecute(command: string): OSExecuteResponse

Executes a command using the SAP Control API with default settings (synchronous execution and a timeout of 30 seconds).

Commands may need to be passed using their full path, for example /bin/ls instead of just ls and of course need to respect the platform tha SAP is hosted on.

 
const lsResult = sapControl.osExecute("/bin/ls -la")
if (lsResult.exitCode === 0) {
    // Process output
    const availableFiles = lsResult.out;
    // ... parse file list
}
Since

23.0

Parameters

  • command: string

    the command to run

Returns

OSExecuteResponse

a response from the command

osExecute(..)

osExecute(command: string, async: number): OSExecuteResponse

Executes a command using the SAP Control API with the ability to run commands asynchronously. This method uses the default timeout of 30 seconds.

Since

23.0

Parameters

  • command: string

    the command to run

  • async: number

    0 for synchronous, 1 for asynchronous

Returns

OSExecuteResponse

a response from the command

osExecute(..)

osExecute(command: string, async: number, timeout: number): OSExecuteResponse

Execute a command using the SAP Control API with the ability to run commands asynchronously and specify a timeout.

Since

23.0

Parameters

  • command: string

    the command to run

  • async: number

    0 for synchronous, 1 for asynchronous

  • timeout: number

    timeout value in seconds

Returns

OSExecuteResponse

a response from the command

osExecute(..)

osExecute(command: string, async: number, timeout: number, protocolfile: string): OSExecuteResponse

Execute a command using the SAP Control API with full options available.

This variant of the method allows specification of a protocol file that, for asynchronous commands, will contain the output of the command and can be read and used in subsequent steps.

Since

23.0

Parameters

  • command: string

    the command to run

  • async: number

    0 for synchronous, 1 for asynchronous

  • timeout: number

    timeout value in seconds

  • protocolfile: string

    the location of a file to redirect the console output to

Returns

OSExecuteResponse

a response from the command

parameterValue(..)

parameterValue(parameterName: string): ParameterValueResponse

Utility method to read the value of an SAP profile parameter directly from the SAP system.

// Read the SAP Profile Parameter `SAPSYSTEMNAME`
const { value: sid } = sapControl.parameterValue("SAPSYSTEMNAME");

// JavaScript syntax above is equivalent to the following 2 lines:
const result = sapControl.parameterValue("SAPSYSTEMNAME");
const sid2 = result.value;

action.message = sid;
Since

23.0

Parameters

  • parameterName: string

    the parameter to read

Returns

ParameterValueResponse

the value of the parameter

SAPControlURL

readonly SAPControlURL: string

The URL of the SAP Control API web service. Useful if you want to construct your own queries or debug this API.

See Also
Type

string

Modifiers

Readonly

Since

23.0

allEnvironment

readonly allEnvironment: object

Utility method to read all environment variables of the SAP system.

// Read all SAP environment variables
const values = sapControl.getAllEnvironment();
See Also
Type

object

Modifiers

Readonly

Since

24.0