# Using (Monitoring) Parameters

Monitoring parameters are used by built-in Avantra checks and automation actions to customise the behaviour 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.

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

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

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.openConnection` method), calling web APIs (with the `web.request(..).useCredentials` method) or using different users on an SAP system (with `sap.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

  any

  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

#### agentVersion

    readonly agentVersion: string

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

See Also

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

See Also

  - getServerVersion()

Type

  string

Modifiers

  Readonly

Since

  21.11.6