Using (Monitoring) Parameters

Monitoring parameters are used by built-in Avantra checks and automation actions to customize the behavior of the product. For example, sometimes there is a requirement to setup a system in a non-standard way so the monitoring parameter will be used to change the location to check for specific files. Or there might be a specific feature of Avantra that you want to turn off with a parameter.

Additionally, you can create custom monitoring parameters to have the same functionality in your own extensions to Avantra. These always begin with cust. to separate them from Avantra delivered monitoring parameters.

Code Walkthrough

In this code walkthrough, we will create a custom monitoring parameter to control a specific function of a new JavaScript based custom check.

Creating a new Monitoring Parameter To create a new monitoring parameter, navigate to Administration > Settings and choose the Custom Monitoring Parameters tab.

note

If you don't see this menu, you might need to ask your administrator for more permissions or to perform this task for you.

In the toolbar, click New to create a new monitoring parameter.

Define a name that must start with cust. a system type and a unit/type and click Create. To follow this example, enter cust.SampleMPT, choose Server and String respectively. If you now open the properties for this newly created Monitoring Parameter, you can also set a description to remind you of its' use and a default value should it not be set on a specific system directly.

Using a parameter within a Check

To use a monitoring parameter within a check, you can use the getMoniParam(..) method of the global variable monitoredSystem.

const param = monitoredSystem.getMoniParam("cust.SampleMPT");
console.log(param);

Executing this in the check test functionality outputs the default value above. And if you set a value against the monitored object, it outputs that value instead.

tip

Changes to monitoring parameters require the configuration to be sent to the agent before they are picked up in the script. Otherwise you will just see the original value.

API Reference

Global Variable monitoredSystem

The global variable monitoredSystem provides access to read information and monitoring parameters about the system that this script is run on. This includes custom monitoring parameters.

Use this to make your scripts customisable for your Avantra users to reflect the setup and usage of that system.

// default for AgentConnectTimeCrit is "60"
const critTime = monitoredSystem.getMoniParam("AgentConnectTimeCrit");

// use the critical time in script
// ...

---

doesAgentMeet

doesAgentMeet(aVersion: string): boolean

Check if the current Avantra Agent, that is executing this RUN_JS or automation step, meets or is above a certain minimum version so that we checks/automations can verify if certain features are present or conditionally do different things for different Avantra versions.

Since: 21.11.6

Parameters

• aVersion (string) - the minimum Agent version to check against

Returns: boolean - true if the current Avantra Agent meets this minimum version, false otherwise

---

doesServerMeet

doesServerMeet(aVersion: string): boolean

Check if the Avantra Server, that this agent is connected to, meets or is above a certain minimum version so that we checks/automations can verify if certain features are present or conditionally do different things for different Avantra versions

Since: 21.11.6

Parameters

• aVersion (string) - the minimum Server version to check against

Returns: boolean - true if the Avantra Server meets this minimum version, false otherwise

---

getAgentVersion

getAgentVersion(): string

Retrieve the current agent version which executes this RUN_JS check or workflow step.

Since: 21.11.6

Returns: string - the version of the Avantra agent

See Also: agentVersion

---

getCredential

getCredential(name: string): CredentialProxy

Use this method to find the credential associated with the monitored object which can then be used in calling programs (through the os.exec' methods), performing database SQL queries (through the database.openConnectionmethod), calling web APIs (with theweb.request(..).useCredentialsmethod) or using different users on an SAP system (withsap.loginWith`).

const creds = monitoredSystem.getCredential("namespace.name");
if (creds) {
    // We have credentials, use them for the next request..
    // ...
} else {
    // Show an error for the user
    // ...
}

Since: 21.11.6

Parameters

• name (string) - the namespace . name of the credential to find

Returns: CredentialProxy - the credential object if found

---

getMoniParam

getMoniParam(name: string): any

Retrieve the monitoring parameter by name for this system.

Parameters

• name (string) - the name of the monitored parameter to retrieve

Returns: any - the monitored parameter or null if not found

---

getMoniParam

getMoniParam(name: string, defaultValue: any): any

Retrieve the monitoring parameter by name for this system.

Parameters

• name (string) - the name of the monitored parameter to retrieve
• defaultValue (any) - the default value to return if not found

Returns: any - the monitored parameter or the defaultValue if not found

---

getServerVersion

getServerVersion(): string

Retrieve the version of the Avantra server to which this agent is attached to.

Since: 21.11.6

Returns: string - the version of the Avantra server

See Also: serverVersion

---

getSystemId

getSystemId(): number

Return the system ID of the monitored system. This is the unique ID of the system in the Avantra system.

Returns: number - the system ID of the monitored system

See Also: systemId

---

getSystemName

getSystemName(): string

Return the system name of the monitored system. This is the name of the system as configured in Avantra.

Returns: string - the system name of the monitored system

See Also: systemName

---

agentVersion

readonly agentVersion: string

Retrieve the current agent version which executes this RUN_JS check or workflow step.

Accessors

• getAgentVersion

Type: string

Modifiers: readonly

Since: 21.11.6

---

serverVersion

readonly serverVersion: string

Retrieve the version of the Avantra server to which this agent is attached to.

Accessors

• getServerVersion

Type: string

Modifiers: readonly

Since: 21.11.6

---

systemId

readonly systemId: number

Return the system ID of the monitored system. This is the unique ID of the system in the Avantra system.

Accessors

• getSystemId

Type: number

Modifiers: readonly

---

systemName

readonly systemName: string

Return the system name of the monitored system. This is the name of the system as configured in Avantra.

Accessors

• getSystemName

Type: string

Modifiers: readonly

---

Class BTPCloudFoundryCredential

BTP CloudFoundry credential object, provides access to credential details

origin

origin: string

origin

Type: string

Since: 25.1

---

password

password: string

password

Type: string

Since: 25.1

---

username

username: string

username

Type: string

Since: 25.1

---

Class BasicAuthCredential

Basic authentication credential object, provides access to credential details

password

password: string

password

Type: string

Since: 25.1

---

username

username: string

username

Type: string

Since: 25.1

---

Class Credential

Credential object, provides access to credential details

asBTPCloudFoundryCredential

asBTPCloudFoundryCredential(): BTPCloudFoundryCredential

Cast to BTP Cloud Foundry credential. Returns null if not possible.

Since: 25.1

Returns: BTPCloudFoundryCredential - BTP Cloud Foundry credential

---

asBasicAuthCredential

asBasicAuthCredential(): BasicAuthCredential

Cast to basic auth credential. Returns null if not possible.

Since: 25.1

Returns: BasicAuthCredential - basic auth credential

---

asOAuthAuthorizationCodeProfileCredential

asOAuthAuthorizationCodeProfileCredential(): OAuthAuthorizationCodeProfileCredential

Cast to OAuthAuthorizationCodeProfile credential. Returns null if not possible.

Since: 25.1

Returns: OAuthAuthorizationCodeProfileCredential - OAuthAuthorizationCodeProfile credential

---

asOAuthClientCredentialsProfileCredential

asOAuthClientCredentialsProfileCredential(): OAuthClientCredentialsProfileCredential

Cast to OAuthClientCredentialsProfile credential. Returns null if not possible.

Since: 25.1

Returns: OAuthClientCredentialsProfileCredential - OAuthClientCredentialsProfile credential

---

asRFCCredential

asRFCCredential(): RFCCredential

Cast to RFC credential. Returns null if not possible.

Since: 25.1

Returns: RFCCredential - RFC credential

---

asSAPCONTROLAuthenticationCredential

asSAPCONTROLAuthenticationCredential(): SAPCONTROLAuthenticationCredential

Cast to SAPCONTROLAuthentication credential. Returns null if not possible.

Since: 25.1

Returns: SAPCONTROLAuthenticationCredential - SAPCONTROLAuthentication credential

---

asSAPHostCONTROLAuthenticationCredential

asSAPHostCONTROLAuthenticationCredential(): SAPHostCONTROLAuthenticationCredential

Cast to SAPHostCONTROLAuthentication credential. Returns null if not possible.

Since: 25.1

Returns: SAPHostCONTROLAuthenticationCredential - SAPHostCONTROLAuthentication credential

---

asSSHCredential

asSSHCredential(): SSHCredential

Cast to SSH credential. Returns null if not possible.

Since: 25.1

Returns: SSHCredential - SSH credential

---

Class CredentialProxy

Object representing an Avantra credential which can provide encrypted credentials used in openConnection call. Please note: this object does not provide direct access to decrypted credentials. In case you need decrypted credentials, use the function decrypt() on a credential to get a map with decrpyted credentials. However, decrypting credentials is disabled by default and must be actively enabled.

canDecrypt

canDecrypt(): boolean

Check whether this credential can be decrypted or not

if(cred.canDecrypt()){
}

---

decrypt

decrypt(): Credential

Function to decrypt credentials. This function checks whether permissions can be decrypted or not. In case credentials cannot be decrypted, an error is thrown.

The returned object is a provides direct access to the specific credential settings.

const decryptedCred = cred.decrypt();
var username = decryptedCred.asBasicAuthCredential().getUsername()
var password = decryptedCred.asBasicAuthCredential().getPassword()

---

Class OAuthAuthorizationCodeProfileCredential

OAuthAuthorizationCodeProfile credential object, provides access to credential details

accessToken

accessToken: string

Type: string

Since: 25.1

---

accessTokenUri

accessTokenUri: string

Type: string

Since: 25.1

---

authorizationUri

authorizationUri: string

Type: string

Since: 25.1

---

clientId

clientId: string

Type: string

Since: 25.1

---

clientSecret

clientSecret: string

Type: string

Since: 25.1

---

expirationDateInMillis

expirationDateInMillis: number

Type: number

Since: 25.1

---

name

name: string

Type: string

Since: 25.1

---

redirectUri

redirectUri: string

Type: string

Since: 25.1

---

refreshToken

refreshToken: string

Type: string

Since: 25.1

---

scope

scope: string

Type: string

Since: 25.1

---

Class OAuthClientCredentialsProfileCredential

OAuthClientCredentialsProfile credential object, provides access to credential details

accessToken

accessToken: string

Type: string

Since: 25.1

---

accessTokenUri

accessTokenUri: string

Type: string

Since: 25.1

---

clientId

clientId: string

Type: string

Since: 25.1

---

clientSecret

clientSecret: string

Type: string

Since: 25.1

---

name

name: string

Type: string

Since: 25.1

---

scope

scope: string

Type: string

Since: 25.1

---

Class RFCCredential

RFC authentication credential object, provides access to credential details

client

client: string

client

Type: string

Since: 25.1

---

password

password: string

password

Type: string

Since: 25.1

---

username

username: string

username

Type: string

Since: 25.1

---

Class SAPCONTROLAuthenticationCredential

SAP Control authentication credential object, provides access to credential details

certChain

certChain: string

Type: string

Since: 25.1

---

name

name: string

Type: string

Since: 25.1

---

passphrase

passphrase: string

Type: string

Since: 25.1

---

password

password: string

Type: string

Since: 25.1

---

pk

pk: string

Type: string

Since: 25.1

---

username

username: string

Type: string

Since: 25.1

---

Class SAPHostCONTROLAuthenticationCredential

SAP Host Control authentication credential object, provides access to credential details

certChain

certChain: string

Type: string

Since: 25.1

---

name

name: string

Type: string

Since: 25.1

---

passphrase

passphrase: string

Type: string

Since: 25.1

---

password

password: string

Type: string

Since: 25.1

---

pk

pk: string

Type: string

Since: 25.1

---

username

username: string

Type: string

Since: 25.1

---

Class SSHCredential

SSH credential object, provides access to credential details

hostName

hostName: string

Type: string

Since: 25.1

---

passphrase

passphrase: string

Type: string

Since: 25.1

---

password

password: string

Type: string

Since: 25.1

---

rsaPrivateKey

rsaPrivateKey: string

Type: string

Since: 25.1

---

sshPort

sshPort: number

Type: number

Since: 25.1

---

timeoutInMillis

timeoutInMillis: number

Type: number

Since: 25.1

---

userName

userName: string

Type: string

Since: 25.1

---