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.

note

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 global object 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 global object. 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 directly in your scripts, for example:

const result = sapControl.loginWith(...);

See SAPControlHost for the full API.

---

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: out

---

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.

Accessors

• getOut

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(): any

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: allEnvironment

---

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: SAPControlURL

---

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).

note

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.

Accessors

• getSAPControlURL

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();

Accessors

• getAllEnvironment

Type: object

Modifiers: readonly

Since: 24.0

---