# 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

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

See Also

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

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

| 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

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

See Also

  - getAllEnvironment()

Type

  object

Modifiers

  Readonly

Since

  24.0