# 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

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

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

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

Parameters

  - `checkName`: string

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

Returns

  JSCheckResult

  the new check result.

#### result(..)

    result(check: NotifierRunJSCheck): JSCheckResult

Get the check result from a check.

Since

  23.3

Parameters

  - `check`: NotifierRunJSCheck

    the check to get the check result from.

Returns

  JSCheckResult

  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 JSCheckResult

The check result

#### copy( )

    copy(): JSCheckResult

Produce a copy of this check result.

Since

  25.0

Returns

  JSCheckResult

  the copy

#### getMessage( )

    getMessage(): string

The message property

Since

  25.0

Returns

  string

  the message

See Also

  - message

#### getName( )

    getName(): string

The name property

Since

  25.0

Returns

  string

  the name

See Also

  - name

#### getStatus( )

    getStatus(): Status

The status property

Since

  25.0

Returns

  Status

  the status

See Also

  - status

#### getSubResults( )

    getSubResults(): JSCheckSubResult[]

The subResults property

Since

  25.0

Returns

  JSCheckSubResult[]

  the subResults

See Also

  - subResults

#### resultType( )

    resultType(): JSCheckResultType

Get the type of the check result.

Since

  25.0

Returns

  JSCheckResultType

  the type of the result (PLAIN,XHTML,DATA)

#### setMessage(..)

    setMessage(message: string): void

Since

  25.0

Parameters

  - `message`: string

    the message

See Also

  - message

#### setName(..)

    setName(name: string): void

Since

  25.0

Parameters

  - `name`: string

    the name

See Also

  - name

#### setStatus(..)

    setStatus(status: Status): void

Since

  25.0

Parameters

  - `status`: Status

    the status

See Also

  - status

#### setSubResults(..)

    setSubResults(subResults: JSCheckSubResult[]): void

Since

  25.0

Parameters

  - `subResults`: JSCheckSubResult[]

    the subResults

See Also

  - subResults

#### message

    message: string

The message property

See Also

  - getMessage()

  - setMessage(message: string)

Type

  string

Since

  25.0

#### name

    name: string

The name property

See Also

  - getName()

  - setName(name: string)

Type

  string

Since

  25.0

#### status

    status: Status

The status property

See Also

  - getStatus()

  - setStatus(status: Status)

Type

  Status

Since

  25.0

#### subResults

    subResults: JSCheckSubResult[]

The subResults property

See Also

  - getSubResults()

  - setSubResults(subResults: JSCheckSubResult[)]

Type

  JSCheckSubResult[]

Since

  25.0

### Class JSCheckResultTable

The check result table

#### copy( )

    copy(): JSCheckResultTable

Produce a copy of this table.

Since

  25.0

Returns

  JSCheckResultTable

  the copy

#### getColumns( )

    getColumns(): JSCheckResultTableColumn[]

The columns property

Since

  25.0

Returns

  JSCheckResultTableColumn[]

  the columns

See Also

  - columns

#### getRows( )

    getRows(): JSCheckResultTableRow[]

The rows property

Since

  25.0

Returns

  JSCheckResultTableRow[]

  the rows

See Also

  - rows

#### removeMatchingRow(..)

    removeMatchingRow(predicate: Predicate<JSCheckResultTableRow>): void

Remove all rows from this table that match the predicate.

Since

  25.0

Parameters

  - `predicate`: Predicate<JSCheckResultTableRow>

    the predicate

#### setColumns(..)

    setColumns(columns: JSCheckResultTableColumn[]): void

Since

  25.0

Parameters

  - `columns`: JSCheckResultTableColumn[]

    the columns

See Also

  - columns

#### setRows(..)

    setRows(rows: JSCheckResultTableRow[]): void

Since

  25.0

Parameters

  - `rows`: JSCheckResultTableRow[]

    the rows

See Also

  - rows

#### columns

    columns: JSCheckResultTableColumn[]

The columns property

See Also

  - getColumns()

  - setColumns(columns: JSCheckResultTableColumn[)]

Type

  JSCheckResultTableColumn[]

Since

  25.0

#### rows

    rows: JSCheckResultTableRow[]

The rows property

See Also

  - getRows()

  - setRows(rows: JSCheckResultTableRow[)]

Type

  JSCheckResultTableRow[]

Since

  25.0

### Class JSCheckResultTableCell

The check result table cell

#### copy( )

    copy(): JSCheckResultTableCell

Produce a copy of this table cell.

Since

  25.0

Returns

  JSCheckResultTableCell

  the copy

#### getIcon( )

    getIcon(): string

The icon property

Since

  25.0

Returns

  string

  the icon

See Also

  - icon

#### getStatus( )

    getStatus(): Status

The status property

Since

  25.0

Returns

  Status

  the status

See Also

  - status

#### getTooltip( )

    getTooltip(): string

The tooltip property

Since

  25.0

Returns

  string

  the tooltip

See Also

  - tooltip

#### getValue( )

    getValue(): string

The value property

Since

  25.0

Returns

  string

  the value

See Also

  - value

#### setIcon(..)

    setIcon(icon: string): void

Since

  25.0

Parameters

  - `icon`: string

    the icon

See Also

  - icon

#### setStatus(..)

    setStatus(status: Status): void

Since

  25.0

Parameters

  - `status`: Status

    the status

See Also

  - status

#### setTooltip(..)

    setTooltip(tooltip: string): void

Since

  25.0

Parameters

  - `tooltip`: string

    the tooltip

See Also

  - tooltip

#### setValue(..)

    setValue(value: string): void

Since

  25.0

Parameters

  - `value`: string

    the value

See Also

  - value

#### icon

    icon: string

The icon property

See Also

  - getIcon()

  - setIcon(icon: string)

Type

  string

Since

  25.0

#### status

    status: Status

The status property

See Also

  - getStatus()

  - setStatus(status: Status)

Type

  Status

Since

  25.0

#### tooltip

    tooltip: string

The tooltip property

See Also

  - getTooltip()

  - setTooltip(tooltip: string)

Type

  string

Since

  25.0

#### value

    value: string

The value property

See Also

  - getValue()

  - setValue(value: string)

Type

  string

Since

  25.0

### Class JSCheckResultTableColumn

The check result table cell

#### copy( )

    copy(): JSCheckResultTableColumn

Produce a copy of this table column.

Since

  25.0

Returns

  JSCheckResultTableColumn

  the copy

#### getName( )

    getName(): string

The name property

Since

  25.0

Returns

  string

  the name

See Also

  - name

#### getType( )

    getType(): string

The type property

Since

  25.0

Returns

  string

  the type

See Also

  - type

#### setName(..)

    setName(name: string): void

Since

  25.0

Parameters

  - `name`: string

    the name

See Also

  - name

#### setType(..)

    setType(type: string): void

Since

  25.0

Parameters

  - `type`: string

    the type

See Also

  - type

#### name

    name: string

The name property

See Also

  - getName()

  - setName(name: string)

Type

  string

Since

  25.0

#### type

    type: string

The type property

See Also

  - getType()

  - setType(type: string)

Type

  string

Since

  25.0

### Class JSCheckResultTableRow

The check result table row

#### copy( )

    copy(): JSCheckResultTableRow

Produce a copy of this table row.

Since

  25.0

Returns

  JSCheckResultTableRow

  the copy

#### findCellByName(..)

    findCellByName(name: string): JSCheckResultTableCell

Try to find a table cell in this row by name.

Since

  25.0

Parameters

  - `name`: string

    the name

Returns

  JSCheckResultTableCell

  the cell if found

#### getCells( )

    getCells(): JSCheckResultTableCell[]

The cells property

Since

  25.0

Returns

  JSCheckResultTableCell[]

  the cells

See Also

  - cells

#### getStatus( )

    getStatus(): Status

The status property

Since

  25.0

Returns

  Status

  the status

See Also

  - status

#### setCells(..)

    setCells(cells: JSCheckResultTableCell[]): void

Since

  25.0

Parameters

  - `cells`: JSCheckResultTableCell[]

    the cells

See Also

  - cells

#### setStatus(..)

    setStatus(status: Status): void

Since

  25.0

Parameters

  - `status`: Status

    the status

See Also

  - status

#### cells

    cells: JSCheckResultTableCell[]

The cells property

See Also

  - getCells()

  - setCells(cells: JSCheckResultTableCell[)]

Type

  JSCheckResultTableCell[]

Since

  25.0

#### status

    status: Status

The status property

See Also

  - getStatus()

  - setStatus(status: Status)

Type

  Status

Since

  25.0

### Class JSCheckSubResult

The check sub-result

#### copy( )

    copy(): JSCheckSubResult

Produce a copy of this check sub-result.

Since

  25.0

Returns

  JSCheckSubResult

  the copy

#### getMessage( )

    getMessage(): string

The message property

Since

  25.0

Returns

  string

  the message

See Also

  - message

#### getName( )

    getName(): string

The name property

Since

  25.0

Returns

  string

  the name

See Also

  - name

#### getStatus( )

    getStatus(): Status

The status property

Since

  25.0

Returns

  Status

  the status

See Also

  - status

#### getTable( )

    getTable(): JSCheckResultTable

The subresult’s table

Since

  25.0

Returns

  JSCheckResultTable

  the subResults

See Also

  - table

#### setMessage(..)

    setMessage(message: string): void

Since

  25.0

Parameters

  - `message`: string

    the message

See Also

  - message

#### setName(..)

    setName(name: string): void

Since

  25.0

Parameters

  - `name`: string

    the name

See Also

  - name

#### setStatus(..)

    setStatus(status: Status): void

Since

  25.0

Parameters

  - `status`: Status

    the status

See Also

  - status

#### setTable(..)

    setTable(table: JSCheckResultTable): void

Since

  25.0

Parameters

  - `table`: JSCheckResultTable

    the table

See Also

  - table

#### message

    message: string

The message property

See Also

  - getMessage()

  - setMessage(message: string)

Type

  string

Since

  25.0

#### name

    name: string

The name property

See Also

  - getName()

  - setName(name: string)

Type

  string

Since

  25.0

#### status

    status: Status

The status property

See Also

  - getStatus()

  - setStatus(status: Status)

Type

  Status

Since

  25.0

#### table

    table: JSCheckResultTable

The subresult’s table

See Also

  - getTable()

  - setTable(table: JSCheckResultTable)

Type

  JSCheckResultTable

Since

  25.0

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

#### category

    readonly category: string

The SAP note category.

Type

  string

Modifiers

  Readonly

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