Script Based Notification Channels

Introduced in Avantra 21.11, Script Based Notification Channels are a powerful method of extending the Notification System in Avantra with custom business logic. Customers can decide, based on the message to be sent, or information about the underlying check, system, or Avantra customer what information to send.

We provide a rich API API to access information about the message that is due to be sent, the system or action that is linked to the message to be sent and the trigger of that message (a critical check, alert etc.). In addition, with a custom notification channel script, we have access to the following building blocks:

Saving State

Save calculated values to a local storage for use in subsequent messages sent for this notification action/check/system combination.
Calling Web Services

Access to a simple HTTP client to call web services to validate operations or perform actions.

Code Walkthrough

The global variable message allows access to information about the message that this output channel is going to send. Depending on the message type, one of several properties will be available with additional information about that object.

Action type CCMS Alert

Use property message.ccmsAlert with is an object of type NotifierRunJSCcmsAlert.
Action type Change

Use property message.change which is an object of type NotifierRunJSChange.
Action type Check (RTM, Daily Check Details, Daily Checks)

Use property message.check which is an object of type NotifierRunJSCheck.
Action type Server Event (license expiry)

Use property message.serverEvent which is an object of type NotifierRunJSServerEvent.
Action type Ticket

Use property message.ticket which is an object of type NotifierRunJSTicket.
Action type #SAPNote

Use property message.sapNote which is an object of type NotifierRunJSSapNote.

To quickly ascertain what information is availble in that specific object, most action types support a test mode for the Output Channel Action. This code walkthrough will use such a test mode with the check action type as it’s the most commonly used.

Creating a new Output Channel

We first need to create an output channel. From the Configuration menu, choose Notifications then Notifications [Global]. On the tab Channels, choose New and then select JavaScript Based.

In the wizard, provde a name for the output channel and choose the relevant customers (or leave alone to enable this channel for use in all customers). We are going to write this for the action type of Checks so mark this checkbox. These settings can be changed later.

Enter the following sample code into the and click Save:

console.log("Sending message from JavaScript!");
console.log(JSON.stringify(message.check));

This code will simply output the content of the message object to the log file.

Now we will create a Notification Action to call this output channel. From the tab Actions, choose New then Action for Checks….

In the wizard, give the action a memorable name and click Next. In the next part of the wizard we can define which checks this action will run on. For our purposes, select Define specific 'Ad-Hoc' Custom Selection and click Create.

In the pop-up select RTM Checks and click Next. In the next window simply click Save and close to not restrict the check selector to any specific checks. Click Next on the wizard.

In real scenarios, typically you restrict the checks that are selected at this point to reduce messages sent and improve performance.

On the next page, ensure OK, WARNING and CRITICAL checks are selected and click Next.

On the final step, select the Output Channel created above to link it to the Action and click Finish.

By default a newly created Notification Action is deactivated which is perfect for testing. When we’ve dialed in all the settings and written the script as we like, we can activate to respond to live check status changes.

Testing our Output Channel

On the Test tab of the newly created Action, choose a Monitored System to borrow a check from and then the specific Check to fake a message from. Un-tick the Suppress Delivery checkbox and click Test. A log output should display with a Script output section with our message Sending message from JavaScript! and the check object information.

If this doesn’t appear, ensure the Suppress Delivery checkbox is NOT ticked as this prevents any Output Channel from running!

You can see the JSON representation of the check information in the log. See NotifierRunJSCheck for details of more methods available.

Reading System Information

A check runs on a specific system, this information is available with the message.system object (NotifierRunJSMonitoredSystem) which is also available for other Action Types that refer to a system.

From this object we can get more information about the sytem which has that check status or query monitoring parameters:

// The system's assigned SLA might impact ticket resolution:
console.log(message.system.slaName);

// Issues with different systems might need to be resolved by
// different teams in your external ticketing system:
const resolverTeam = message.system.getMonitoringParameter("cust.TicketResolverTeam");

// For this example, we just log this out
// - but we could use the WEB API to log a ticket:
console.log(resolverTeam);

Create a custom monitoring parameter cust.TicketResolverTeam to follow this example.

Reading Customer Information

The customer assigned to a system may impact how a notification is sent / who is notified. Use the message.customer property for information about the customer assigned (NotifierRunJSCustomer) including email addresses and custom fields as defined in customer maintenance.

Example

Example 1. Update a ticket with new status within 30 minutes

This complex example uses the web and localStorage APIs to create tickets and if a previous ticket has been created within 30 mins, we update that ticket rather than creating our own.

We also perform two requests, one to login to the custom ticketing system (myticketsystem) to retrieve their API token before creating a ticket.

const host = "https://myticketsystem.com/api/v2"

const MS_PER_MINUTE = 60000;
const threshold = 30; // minutes ago that we check for last message sent
const thresholdDate = new Date(new Date().valueOf() - threshold * MS_PER_MINUTE);


// 1. Create a payload of data to send to the ticket system
let action = "create";
const payload = {
    ticketID: null,
    name: message.check?.name,
    system: message.system.name,
    status: message.check?.status,
    addInfo: message.customer.cust1,
    url: message.check?.url
};

// 1b. If we have a status saved, use it to influence the payload
if (localStorage.lastReported) {
    const lastMsg = new Date(localStorage.lastReported);
    const lastStatus = localStorage.lastStatus;
    const oldTicket = localStorage.lastTicket;

    // Check if the last message sent was less than 30 mins ago
    if (lastMsg.valueOf() > thresholdDate.valueOf()
        // It wasn't an OK status
        && lastStatus !== "OK"
        // And we got a ticket number for it
        && !!oldTicket) {

        action = "update";
        payload.ticketID = oldTicket;
    }
}

// 2. Login
const token = login();

// 3. Sent the query to create/update the ticket
const newTicket = queryTicket(token, payload);

// 4. Save the state for next message
localStorage.lastReported = new Date().valueOf();
localStorage.lastStatus = message.check?.status;
localStorage.lastTicket = newTicket;



// Utility functions:

function login() {
    console.log("\nLogging in...");

    const res = web.request(host + "/login")
                .method(web.POST)
                .json({
                    user: "MYUSER",
                    password: "MYSECRETPASSWORD"
                })
                .fetch();

    if (res.status !== 200 || !res.json.accesstoken) {
        throw new Error("Unable to login " + res.body);
    }
    return res.json.accesstoken;
}

function queryTicket(accessToken, action, abody) {
    console.log("\nPerforming " + action + " on ticket " + abody.ticketID);

    const res = web.request(host + "/ticket/" + action)
                .method(web.POST)
                .header("X-Auth-Token", "" + accessToken)
                .json(abody)
                .fetch();

    if (res.status !== 200 || !res.json.success) {
        throw new Error("Unable to " + action + "ticket " + res.body);
    }
    return res.json.ticketID;
}

API Reference

Global Variable message

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

const myValue = message.getSystem( );

See NotifierRunJSMessage for further documentation on these methods.

Global Variable notifier

The notifier namespace. Offers general functionality concerning the notifier itself like forwarding a notifier message to another channel.

forwardMessage(..)

forwardMessage(channelId: string, message: NotifierRunJSMessage, overwrite: object, errorBehaviour: string, timeoutMillis: number): void

Forward a notification message to another channel given its Unique ID or name (unique ID is preferred as the name of another channel can change easily).

Example: Overwrite the check result for the forward:

let newResult = notifier.newCheckResult('Custom Check Result')

// configure the check result

notifier.forwardMessage('5d09397e-acf3-4c46-97bb-564f40628a85', message, {
    'check.result': newResult
    // or: 'check': {'result': newResult }
})

Since

23.3

Parameters

channelId: string

the channel ID to which the message should be forwarded
message: NotifierRunJSMessage

the notifier message to forward
overwrite: object

overwritten interpolations
errorBehaviour: string

either 'forward' or 'ignore' (default: 'forward'). If forward is selected and the channel blocks/fails the original channel blocks/fails as well.
timeoutMillis: number

the timeout in milliseconds for the forward operation (default: 30000ms)

forwardMessage(..)

forwardMessage(channelId: string, message: NotifierRunJSMessage, overwrite: object, errorBehaviour: string): void

Forward a notification message to another channel given its Unique ID or name (unique ID is preferred as the name of another channel can change easily).

Example: Overwrite the check result for the forward:

let newResult = notifier.newCheckResult('Custom Check Result')

// configure the check result

notifier.forwardMessage('5d09397e-acf3-4c46-97bb-564f40628a85', message, {
    'check.result': newResult
    // or: 'check': {'result': newResult }
})

Since

23.3

Parameters

channelId: string

the channel ID to which the message should be forwarded
message: NotifierRunJSMessage

the notifier message to forward
overwrite: object

overwritten interpolations. To overwrite the check result the <code>notifier.newCheckResult('…')</code> could be used like {'check.result': notifier.newCheckResult('…')}.
errorBehaviour: string

either 'forward' or 'ignore' (default: 'forward'). If forward is selected and the channel blocks/fails the original channel blocks/fails as well.

forwardMessage(..)

forwardMessage(channelId: string, message: NotifierRunJSMessage, overwrite: object): void

Forward a notification message to another channel given its Unique ID or name (unique ID is preferred as the name of another channel can change easily).

Example: Overwrite the check result for the forward:

let newResult = notifier.newCheckResult('Custom Check Result')

// configure the check result

notifier.forwardMessage('5d09397e-acf3-4c46-97bb-564f40628a85', message, {
    'check.result': newResult
    // or: 'check': {'result': newResult }
})

Since

23.3.0

Parameters

channelId: string

the channel ID to which the message should be forwarded
message: NotifierRunJSMessage

the notifier message to forward
overwrite: object

overwritten interpolations

forwardMessage(..)

forwardMessage(channelId: string, message: NotifierRunJSMessage): void

Forward a notification message to another channel given its Unique ID or name (unique ID is preferred as the name of another channel can change easily).

Example: Forward the message to another channel

notifier.forwardMessage('5d09397e-acf3-4c46-97bb-564f40628a85', message)

Since

23.3.0

Parameters

channelId: string

the channel ID to which the message should be forwarded
message: NotifierRunJSMessage

the notifier message to forward

interpolation(..)

interpolation(message: NotifierRunJSMessage, interpolation: any): any

This method can be used to resolve an interpolation.

Example: Resolve an interpolation against the notifier message.

let value = notifier.interpolation(message, 'check.name')

Since

23.3

Parameters

message: NotifierRunJSMessage
interpolation: any

the interpolation to resolve

Returns

any

the vale of the resolution (can be null).

newCheckResult(..)

newCheckResult(checkName: string): SimpleCheckResult

Creates a new check result. The new check result can be used to overwrite an existing check result when forwarding the Example: Create a new check result:

let newResult = notifier.newCheckResult('Custom Check Result')
let newSubResult = newResult.subResult()
newSubResult.name = "Sub Check #1"
newSubResult.status = Status.CRITICAL
newSubResult.table((table) => {
-
    table.column('Column 1')
    table.column('Column 2', 'string')
    table.column('Column 3', 'integer')

    table.row((row) => {
        row.cell('ROW 1', Status.CRITICAL)
        row.cell('Without Status')
        row.cell(42)
    })

    for (let step = 0; step < 5; step++) {
        table.row((row) => {
            row.cell('ROW: ' + step)
            row.cell('Step: ' + step)
            row.cell(step)
        })
    }
})

Since

23.3.0

Parameters

checkName: string

the (pseudo) check name to be used for the new check result (must not be <code>null</code>).

Returns

SimpleCheckResult

the new check result.

result(..)

result(check: NotifierRunJSCheck): any

Get the check result from a check.

Since

23.3.0

Parameters

check: NotifierRunJSCheck

the check to get the check result from.

Returns

any

the check result object. If the check result is only plain text the returned value will be of type 'string'. If there are sub-results in the check result the value returned will be of type 'object' .

Class NotifierRunJSCcmsAlert

This object holds the information about a CCMS alert that has triggered the script based output channel.

message

readonly message: string

The message attached to a CCMS Alert (plain text).

Type: string
Modifiers: Readonly

name

readonly name: string

The name of the check the CCMS Alert is attached to.

Type: string
Modifiers: Readonly

priority

readonly priority: string

The ticket priority corresponding to the check status attached to the CCMS Alert where CRITICAL maps to HIGH, WARNING maps to MEDIUM and everything else maps to LOW.

Type: string
Modifiers: Readonly

status

readonly status: string

The string representation of the check status attached to the CCMS Alert. i.e. one of CRITICAL, WARNING, OK, UNKNOWN, DISABLED.

Type: string
Modifiers: Readonly

statusChangeDate

readonly statusChangeDate: string

The point in time the check attached to the Ccms Alert changed to its current status.

To use in your scripts, you can convert to a JavaScript date object like so:

const date = new Date(message.ccmsAlert.statusChangeDate);

Type: string
Modifiers: Readonly

Class NotifierRunJSChange

This object holds the information about a change that has triggered the script based output channel.

date

readonly date: string

The point in time the change record was created.

To use in your scripts, you can convert to a JavaScript date object like so:

const date = new Date(message.change.date);

Type: string
Modifiers: Readonly

doneDate

readonly doneDate: string

The done date of the change.

To use in your scripts, you can convert to a JavaScript date object like so:

const doneDate = new Date(message.change.doneDate);

Type: string
Modifiers: Readonly

fallbackText

readonly fallbackText: string

The fallback plan of the change.

Type: string
Modifiers: Readonly

id

readonly id: number

Change ID

Type: number
Modifiers: Readonly

impact

readonly impact: string

The impact assigned to the change.

Type: string
Modifiers: Readonly

implementedDate

readonly implementedDate: string

The implementation date of the change.

To use in your scripts, you can convert to a JavaScript date object like so:

const implementedDate = new Date(message.change.implementedDate);

Type: string
Modifiers: Readonly

logText

readonly logText: string

The implementation log of the change.

Type: string
Modifiers: Readonly

plannedDate

readonly plannedDate: string

The planned date of the change.

To use in your scripts, you can convert to a JavaScript date object like so:

const plannedDate = new Date(message.change.plannedDate);

Type: string
Modifiers: Readonly

shortDesc

readonly shortDesc: string

Short description of the change.

Type: string
Modifiers: Readonly

status

readonly status: string

The string representation of the change status i.e. one of Planned, Processing, Implemented, Done.

Type: string
Modifiers: Readonly

statusAge

readonly statusAge: string

The period of time the change has been in its current status (in format h:mm:ss).

Type: string
Modifiers: Readonly

statusAgeInSeconds

readonly statusAgeInSeconds: number

The period of time the change has been in its current status (in seconds).

Type: number
Modifiers: Readonly

user

readonly user: string

The username assigned to the change.

Type: string
Modifiers: Readonly

Class NotifierRunJSCheck

This object represents the check performed that triggered the output channel and is only present if Daily Check, Daily Check Details or Real Time Monitoring action type is selected.

getResult( )

getResult(): string

The long text result of a check (if it exists).

Returns

string

the text result of the check

See Also

result

getResultHTML( )

getResultHTML(): string

The HTML version of the long text result of a check (if it exists).

Since

21.11.4

Returns

string

the HTML formatted result of the check

See Also

resultHTML

confirmDate

readonly confirmDate: string

The point in time the check was last confirmed or unconfirmed.

To use in your scripts, you can convert to a JavaScript date object like so:

const statusChange = new Date(message.check.statusChangeDate);

Type: string
Modifiers: Readonly

confirmMessage

readonly confirmMessage: string

The confirmation message of the check, if any.

Type: string
Modifiers: Readonly

date

readonly date: string

The point in time the check was performed.

To use in your scripts, you can convert to a JavaScript date object like so:

const checkDate = new Date(message.check.date);

Type: string
Modifiers: Readonly

name

readonly name: string

The name of the check. For a Daily Check the value is DAILYCHECK.

Type: string
Modifiers: Readonly

result

readonly result: string

The long text result of a check (if it exists).

See Also

getResult()

Type

string

Modifiers

Readonly

resultHTML

readonly resultHTML: string

The HTML version of the long text result of a check (if it exists).

See Also

getResultHTML()

Type

string

Modifiers

Readonly

Since

21.11.4

status

readonly status: string

The string representation of the check status i.e. one of CRITICAL, WARNING, OK, UNKNOWN, DISABLED.

Type: string
Modifiers: Readonly

statusChangeDate

readonly statusChangeDate: string

The point in time the check changed to its current status.

To use in your scripts, you can convert to a JavaScript date object like so:

const statusChange = new Date(message.check.statusChangeDate);

Type: string
Modifiers: Readonly

typeDescription

readonly typeDescription: string

The description of the check type (for built-in checks only).

Type: string
Modifiers: Readonly

typeName

readonly typeName: string

The name of the Check Type.

For built-in checks, this could be the same as name.

Type: string
Modifiers: Readonly

url

readonly url: string

A URL pointing to the check in Avantra to allow users to see more detail of the check.

Note: Needs the Avantra UI setting 'url-replacement' to be defined.

Type: string
Modifiers: Readonly

Class NotifierRunJSCustomer

This object represents the customer assigned to the monitored system that triggered the notification message.

address

readonly address: string

The address of the customer defined in Avantra Administration

Type: string
Modifiers: Readonly

city

readonly city: string

The city of the customer defined in Avantra Administration

Type: string
Modifiers: Readonly

countryCode

readonly countryCode: string

The country code of the customer defined in Avantra Administration

Type: string
Modifiers: Readonly

cust1

readonly cust1: string

Custom field cust1

Type: string
Modifiers: Readonly

cust2

readonly cust2: string

Custom field cust2

Type: string
Modifiers: Readonly

cust3

readonly cust3: string

Custom field cust3

Type: string
Modifiers: Readonly

cust4

readonly cust4: string

Custom field cust4

Type: string
Modifiers: Readonly

cust5

readonly cust5: string

Custom field cust5

Type: string
Modifiers: Readonly

description

readonly description: string

The description of the customer defined in Avantra Administration

Type: string
Modifiers: Readonly

email

readonly email: string

The email address of the customer defined in Avantra Administration

Type: string
Modifiers: Readonly

fax

readonly fax: string

The fax number of the customer defined in Avantra Administration

Type: string
Modifiers: Readonly

id

readonly id: number

The customer ID of this customer in Avantra

Type: number
Modifiers: Readonly

mobilePhone

readonly mobilePhone: string

The mobile phone of the customer defined in Avantra Administration

Type: string
Modifiers: Readonly

name

readonly name: string

The customer name of the customer in Avantra

Type: string
Modifiers: Readonly

notes

readonly notes: string

The contents of the customer’s notes field defined in Avantra Administration

Type: string
Modifiers: Readonly

phone

readonly phone: string

The phone number of the customer defined in Avantra Administration

Type: string
Modifiers: Readonly

poBox

readonly poBox: string

The PO Box of the customer defined in Avantra Administration

Type: string
Modifiers: Readonly

postalCode

readonly postalCode: string

The postal code of the customer defined in Avantra Administration

Type: string
Modifiers: Readonly

sapCustNo

readonly sapCustNo: string

The SAP Customer Number of the customer defined in Avantra Administration

Type: string
Modifiers: Readonly

timezone

readonly timezone: string

The timezone of the customer defined in Avantra Administration

Type: string
Modifiers: Readonly

url

readonly url: string

The URL of the customer defined in Avantra Administration

Type: string
Modifiers: Readonly

Class NotifierRunJSMessage

This object represents the message that Avantra has generated from a trigger and is due to be sent through the notification channel.

Use the properties and methods available on this object to control the logic of your custom notification channel.

abort(..)

abort(abortMessage: any): void

To abort this notifier message call this method. Statements following this method call won’t get executed. Example: Abort notifier message:

message.abort('with message')
message.abort() // without abort message

Since

23.3

Parameters

abortMessage: any

an optional abort message

abort( )

abort(): void

To abort this notifier message call this method. Statements following this method call won’t get executed. Example: Abort notifier message:

message.abort('with message')
message.abort() // without abort message

Since: 23.3

block(..)

block(blockMessage: any): void

To block this notifier message call this method. Statements following this method call won’t get executed. Example: Block notifier message:

message.block('with message')
message.block() // without block message

Since

23.3

Parameters

blockMessage: any

an optional block message

block( )

block(): void

To block this notifier message call this method. Statements following this method call won’t get executed. Example: Block notifier message:

message.block('with message')
message.block() // without block message

Since: 23.3

getCcmsAlert( )

getCcmsAlert(): NotifierRunJSCcmsAlert

If the trigger of this message was a CCMS alert then this object will be non-null and contain information about the check and its status

Returns

NotifierRunJSCcmsAlert

an object representing the CCMS alert check

See Also

ccmsAlert

getChange( )

getChange(): NotifierRunJSChange

If the trigger of this message was a change then this object will be non-null and contain information about the change that was made.

Returns

NotifierRunJSChange

an object representing the change

See Also

change

getCheck( )

getCheck(): NotifierRunJSCheck

If the trigger of this message was a check (daily check, daily details, or real time monitoring check) then this object will be non-null and contain information about that check.

Returns

NotifierRunJSCheck

an object representing a check or null

See Also

check

getCustomer( )

getCustomer(): NotifierRunJSCustomer

Access information about the customer that the event that triggered this message belonged to.

Returns

NotifierRunJSCustomer

an object containing information on the customer belonging to this message

See Also

customer

getSapNote( )

getSapNote(): NotifierRunJSSapNote

If the trigger of this message was a SAP note alert then this object will be non-null and contain information about the sap note

Since

21.11.4

Returns

NotifierRunJSSapNote

an object representing the SAP Note object

See Also

sapNote

getServerEvent( )

getServerEvent(): NotifierRunJSServerEvent

If the trigger of this message was a server event (license expiry) then this object will be non-null and contain information about the expiry of the license.

Returns

NotifierRunJSServerEvent

an object representing the license or null

See Also

serverEvent

getSystem( )

getSystem(): NotifierRunJSMonitoredSystem

Use this method to return information about the system that triggered this message to be sent to the notifier.

Returns

NotifierRunJSMonitoredSystem

the monitored system that triggered this message

See Also

system

getTicket( )

getTicket(): NotifierRunJSTicket

If the trigger of this message was a ticket then this object will be non-null and contain information about the ticket update that was made.

Returns

NotifierRunJSTicket

an object representing the ticket

See Also

ticket

ccmsAlert

readonly ccmsAlert: NotifierRunJSCcmsAlert

If the trigger of this message was a CCMS alert then this object will be non-null and contain information about the check and its status

See Also

getCcmsAlert()

Type

NotifierRunJSCcmsAlert

Modifiers

Readonly

change

readonly change: NotifierRunJSChange

If the trigger of this message was a change then this object will be non-null and contain information about the change that was made.

See Also

getChange()

Type

NotifierRunJSChange

Modifiers

Readonly

check

readonly check: NotifierRunJSCheck

If the trigger of this message was a check (daily check, daily details, or real time monitoring check) then this object will be non-null and contain information about that check.

See Also

getCheck()

Type

NotifierRunJSCheck

Modifiers

Readonly

customer

readonly customer: NotifierRunJSCustomer

Access information about the customer that the event that triggered this message belonged to.

See Also

getCustomer()

Type

NotifierRunJSCustomer

Modifiers

Readonly

isResending

readonly isResending: boolean

True iff this is a resend of a previous notification.

Type: boolean
Modifiers: Readonly

last

readonly last: NotifierRunJSMessage

A link to the previous message sent.

Note that it might not be available with full information (especially in testing scenarios).

Type: NotifierRunJSMessage
Modifiers: Readonly

notificationNumber

readonly notificationNumber: number

Notification number that is used for resend scenarios.

Type: number
Modifiers: Readonly

reason

readonly reason: string

Reason for the message being sent.

Type: string
Modifiers: Readonly

sapNote

readonly sapNote: NotifierRunJSSapNote

If the trigger of this message was a SAP note alert then this object will be non-null and contain information about the sap note

See Also

getSapNote()

Type

NotifierRunJSSapNote

Modifiers

Readonly

Since

21.11.4

serverEvent

readonly serverEvent: NotifierRunJSServerEvent

If the trigger of this message was a server event (license expiry) then this object will be non-null and contain information about the expiry of the license.

See Also

getServerEvent()

Type

NotifierRunJSServerEvent

Modifiers

Readonly

status

readonly status: string

Status description for the trigger of the message. For example it could contain CRITICAL if the trigger was a check turning critical.

Type: string
Modifiers: Readonly

system

readonly system: NotifierRunJSMonitoredSystem

Use this method to return information about the system that triggered this message to be sent to the notifier.

See Also

getSystem()

Type

NotifierRunJSMonitoredSystem

Modifiers

Readonly

ticket

readonly ticket: NotifierRunJSTicket

If the trigger of this message was a ticket then this object will be non-null and contain information about the ticket update that was made.

See Also

getTicket()

Type

NotifierRunJSTicket

Modifiers

Readonly

type

readonly type: string

The type of the trigger for this message.

It could be one of the following possible values:

RTM
Daily-Check Detail
Daily Check
Change
CCMS Alert
Ticket
Server Event

Type

string

Modifiers

Readonly

Class NotifierRunJSMonitoredSystem

This object represents the monitored system that triggered the notification message.

credentials(..)

credentials(idOrFullKey: any): CredentialProxy

Retrieve a credential from the monitored system’s credentials list using a credential purpose key, or it’s ID.

The key can belong to a built-in or a custom credential purpose that belongs to the monitored object type. A credential must be assigned to this system for this method to return a value.

The credentials can then be used to authenticate to services on the monitored object.

const idOrKey = "custom.credential1";
const c = message.system.credentials(idOrKey);
if(c) {
    console.log("FOUND credentials for " + idOrKey);
} else {
    console.log("DID NOT find credentials for " + idOrKey);
}

// Use this credential
// ...

Since

23.1

Parameters

idOrFullKey: any

the key or id of a system credential

Returns

CredentialProxy

the credentials from a system

getMonitoringParameter(..)

getMonitoringParameter(moniParamName: string): string

Get the value of a monitoring parameter for the monitored system that triggered the notification.

This method support standard monitoring parameters and custom (begins with "cust.") for use in scripts.

// default for AgentConnectTimeCrit is "60"
const critTime = message.system.getMonitoringParameter("AgentConnectTimeCrit");

Parameters

moniParamName: string

the name of the monitoring parameter to retrieve

Returns

string

the value of the monitoring parameter or null if the parameter doesn’t exist

applicationType

readonly applicationType: string

The application type name of the system in Avantra

e.g. "Utilities", "SAP R/3", etc.

Note: this is configurable in Avantra and may not match your role types.

Type: string
Modifiers: Readonly

custom

readonly custom: any

An object of customer parameters on the monitored system.

Type: any
Modifiers: Readonly

name

readonly name: string

Name of the monitored system in Avantra

Type: string
Modifiers: Readonly

slaName

readonly slaName: string

The name of the assigned SLA in Avantra

Type: string
Modifiers: Readonly

systemId

readonly systemId: number

The system ID of the system in Avantra

Type: number
Modifiers: Readonly

systemRole

readonly systemRole: string

The role type of the system in Avantra

e.g. "Development", "Production", etc.

Note: this is configurable in Avantra and may not match your role types.

Type: string
Modifiers: Readonly

systemType

readonly systemType: string

The name of the type of system this is.

e.g. "Database", "Server", etc.

Type: string
Modifiers: Readonly

Class NotifierRunJSSapNote

This object holds the information about a sap note that has triggered the script based output channel.

component

readonly component: string

The SAP note component.

Type: string
Modifiers: Readonly

description

readonly description: string

The SAP note description.

Type: string
Modifiers: Readonly

isIndep

readonly isIndep: string

The SAP note note indep setting.

Type: string
Modifiers: Readonly

lang

readonly lang: string

The SAP note language.

Type: string
Modifiers: Readonly

noteId

readonly noteId: number

The SAP note note id.

Type: number
Modifiers: Readonly

noteStatus

readonly noteStatus: number

The SAP note status.

Type: number
Modifiers: Readonly

noteStatusMessage

readonly noteStatusMessage: string

The SAP note status text.

Type: string
Modifiers: Readonly

noteTypes

readonly noteTypes: string

The SAP note types.

Type: string
Modifiers: Readonly

noteVers

readonly noteVers: number

The SAP note version.

Type: number
Modifiers: Readonly

priority

readonly priority: string

The SAP note priority.

Type: string
Modifiers: Readonly

releaseDate

readonly releaseDate: Date

The SAP note release date.

Type: Date
Modifiers: Readonly

secCategory

readonly secCategory: string

The SAP note security category.

Type: string
Modifiers: Readonly

snId

readonly snId: number

The Avantra primary key of the SAP note database entity.

Type: number
Modifiers: Readonly

Class NotifierRunJSServerEvent

This object holds the information about a server event that has triggered the script based output channel.

crmId

readonly crmId: string

The CRM ID of the license

Type: string
Modifiers: Readonly

daysLeft

readonly daysLeft: number

Number of days left on the license. Will go negative if expired.

Type: number
Modifiers: Readonly

description

readonly description: string

The license description

Type: string
Modifiers: Readonly

expiryDate

readonly expiryDate: string

Formatted expiry date

Type: string
Modifiers: Readonly

id

readonly id: number

The license ID

Type: number
Modifiers: Readonly

startDate

readonly startDate: string

Formatted start date (if present)

Type: string
Modifiers: Readonly

status

readonly status: string

The status of the license

Type: string
Modifiers: Readonly

Class NotifierRunJSTicket

This object holds the information about a ticket that has triggered the script based output channel.

getLastLog( )

getLastLog(): NotifierRunJSTicketLog

Returns the last log entry from the ticket history. Most likely the entry that triggered this message.

This is the same as getting the first entry from the array returned from getLogs.

Returns

NotifierRunJSTicketLog

the last log entry of this ticket

See Also

lastLog

getLogs( )

getLogs(): NotifierRunJSTicketLog[]

Returns an array of NotifierRunJSTicketLog representing the ticket log and history of this ticket.

Returns

NotifierRunJSTicketLog[]

an array of log output

See Also

logs

callerName

readonly callerName: string

The name of the ticket caller.

Type: string
Modifiers: Readonly

description

readonly description: string

The ticket description.

Type: string
Modifiers: Readonly

id

readonly id: number

The internal ticket identifier.

Type: number
Modifiers: Readonly

lastLog

readonly lastLog: NotifierRunJSTicketLog

Returns the last log entry from the ticket history. Most likely the entry that triggered this message.

This is the same as getting the first entry from the array returned from getLogs.

See Also

getLastLog()

Type

NotifierRunJSTicketLog

Modifiers

Readonly

logs

readonly logs: NotifierRunJSTicketLog[]

Returns an array of NotifierRunJSTicketLog representing the ticket log and history of this ticket.

See Also

getLogs()

Type

NotifierRunJSTicketLog[]

Modifiers

Readonly

ownerName

readonly ownerName: string

The name of the ticket owner.

Type: string
Modifiers: Readonly

priority

readonly priority: string

The ticket priority.

Type: string
Modifiers: Readonly

status

readonly status: string

The ticket status, i.e. one of Open, Processing, Fixed, and Done.

Type: string
Modifiers: Readonly

timestamp

readonly timestamp: string

The point in time the ticket was created.

To use in your scripts, you can convert to a JavaScript date object like so:

const date = new Date(message.ticket.timestamp);

Type: string
Modifiers: Readonly

type

readonly type: string

The ticket type, i.e. one of Question, Request, Problem, Idea, and Praise.

Type: string
Modifiers: Readonly

url

readonly url: string

The URL to access the ticket in the UI. Needs the Avantra UI setting 'url-replacement' to be defined.

Type: string
Modifiers: Readonly

Class NotifierRunJSTicketLog

This object holds the information about a log entry for a ticket.

authorName

readonly authorName: string

The name of the author of a ticket log entry.

Type: string
Modifiers: Readonly

hidden

readonly hidden: boolean

The value of the hidden flag of a ticket log entry.

Type: boolean
Modifiers: Readonly

logType

readonly logType: string

The type of the log entry.

Type: string
Modifiers: Readonly

text

readonly text: string

The text of a ticket log entry.

Type: string
Modifiers: Readonly

timeSpent

readonly timeSpent: number

The amount of time spent on this ticket with this log entry.

Type: number
Modifiers: Readonly

timestamp

readonly timestamp: string

The point in time a ticket log entry was created.

const date = new Date(message.ticket.logs[0].timestamp);

Type: string
Modifiers: Readonly

Global Variable threadId

Global variable threadId is a string that contains an identifier that is a unique combination of the notification action and element. This can be used to associate to unique events in the notification system.

Use this variable directly in your code, e.g

const myUniqueId = threadId;

Since: 21.11.4
Type: string
Modifiers: Readonly

Global Function serviceNow(..)

serviceNow(snowIntegration: String): CredentialProxy

Global function serviceNow provides access to the specified ServiceNow configuration from within a JavaScript notification channel.

You can use this to retrieve the instance name and credentials to authenticate against this ServiceNow instance.

For example, reading from the "My SNOW" configured ServiceNow:

const snow = serviceNow("My SNOW");
if (!snow) {
    throw new Error("Could not find ServiceNow integration")
}

// Create an incident with data from the message:
const res = web.request("https://" + snow.instanceName() + ".service-now.com/api/now/v1/table/incident?sysparm_fields=number%2Csys_id%2Cshort_description")
    .method(web.POST)
    .useCredentials(snow.credentials())
    .json({
        short_description: message.check.name + " on " + message.system.name + " is " + message.check.status,
        comments: "[code]" + message.check.getResultHTML() + "[/code]",
        urgency: "2",
        service: "ServiceNow Event Management",
        u_contact_type: "",
    })
    .fetch();

// SN sends back 201 if the object was created
if (res.status !== 201) {
    throw new Error("Unable to create incident " + res.body);
}

// We can save back the incident data to localStorage so next time we update
// the ticket (code missing from this example):
localStorage.incidentData = res.json;

A more detailed example with downloadable code can be found on our support site Integrate ServiceNow API in Avantra Notifications.

Since

23.1

Parameters

idOrFullKey: Value

the key or id of a system credential

Returns

CredentialProxy

the credentials from a system

Global Function sharedCredentials(..)

credentials(idOrFullKey: String): CredentialProxy

Global function sharedCredentials provides access to global credentials configured in Avantra under the Configuration → Integrations → Credentials menu.

This provides access to configured secrets in a secure way that can be used to access external services including being used in the web API to make web requests.

For example:

const c = sharedCredentials("SNOW");
if(c) {
    console.log("FOUND credentials for service");

    // Use this credential to authenticate..


} else {
    console.log("Error! no credentials defined");
}

Since

23.1

Parameters

idOrName: String

the name or id of a shared credential

Returns

CredentialProxy

the credentials read or null if not found