Marid Integration

Marid is an integration server developed by Opsgenie, designed to resolve challenges faced in the integration of internal and external systems.

150

Using OpsGenie Marid integration, you can manage a two-way bridge between your system and OpsGenie; forwarding OpsGenie alert activity to your system, and updating the alerts on events from your system.

This document explains how to install and use an OpsGenie Marid Integration.

Add Marid integration in Opsgenie

  1. Please create an Opsgenie account if you haven't done already.
  2. Go to Opsgenie Marid Integration page,
  3. Click on "Save Integration" button to save the integration. An "API Key" is generated for the integration. Copy it. This key will be used by Marid to authenticate with Opsgenie.
1187

Install Marid

Install Marid by referring to Overview & Installation document.

Marid Configuration

For Marid configuration, refer to Overview & Installation document.

In order to use Marid integration, you need to set Marid's apiKey configuration:

Setting

Description

Mandatory

Default Value

apiKey

API key used for authenticating Opsgenie API requests executed via "opsgenie" script variable and getting Marid settings from Opsgenie service.
Paste here the API key you've obtained when you saved the Marid integration in Opsgenie.

Yes

Proxy Configuration for Marid Setups Behind a Proxy Server

Direct access to Internet from internal servers is not allowed for most of the enterprise environments. Instead, they set up some proxy servers and all applications are configured to connect Internet through these proxy servers. In order to use Marid on this kind of systems, you need to configure following Marid external proxy settings to interact with Opsgenie or connect Internet from your scripts:

External Proxy Settings

Setting

Description

Mandatory

Default Value

http.proxy.enabled

Enable/disable external proxy configuration. It may be true or false

Yes

false

http.proxy.host

Proxy host

Yes

http.proxy.port

Proxy port

Yes

http.proxy.username

Proxy authentication username

No

http.proxy.password

Proxy authentication password

No

http.proxy.protocol

Proxy connection protocol. It may be http or https depending on your proxy servers.

No

http

http.proxy.authMethod

Proxy authentication mechanism. Should be one of BASIC or NT.

No

NT

📘

Firewall Settings

If your system has firewall, some addresses that are used by Marid, need to be "whitelisted" to outbound rules. There is no need to change your inbound rules. So you should add Opsgenie subdomains dependencies to outbound rules by adding the following as pass-throughs to your firewall:

  • *.opsgenie.com
  • pubsub.pubnub.com

Alert Action Execution

846

Marid can subscribe to Opsgenie user actions, and execute a script for each user action. The connection to Opsgenie is initiated by Marid; therefore Marid server does not have to be accessible from the web. This method does not require any firewall changes, opening ports, etc. since Marid communicates with Opsgenie via HTTPS and initiates the connection from inside out.

Marid executes a groovy or ruby script for each executed alert action. This includes default alert actions, e.g., Create, Acknowledge, etc. as well as user-initiated custom actions. Marid searches <MARID_HOME>/scripts directory for a file whose name is same as action and execute that script with some parameters by default. For example if action "restart" is executed, Marid looks for <MARID_HOME>/scripts/restart.groovy or <MARID_HOME>/scripts/restart.rb and if the script exists, Marid executes the script automatically. In addition, actions to script mapping can be configured in <MARID_HOME>/conf/marid.conf file.

📘

For Linux distributions <MARID_HOME> is /var/opsgenie/marid

For example:

  • If Marid is started with the following configuration actions.restart.script=script1.groovy: for each restart action execution <MARID_HOME>/scripts/script1.groovy will be executed.
  • actions.Create.script=scriptCreate.groovy: for each new alert created in Opsgenie, <MARID_HOME>/scripts/scriptCreate.groovy will be executed.
  • actions.Acknowledge.script=scriptAcknowledge.groovy: each time an alert is acknowledged in Opsgenie, <MARID_HOME>/scripts/scriptAcknowledge.groovy will be executed.
  • actions.AddNote.script=scriptAddNote.groovy: each time a note is added to an alert in Opsgenie, <MARID_HOME>/scripts/scriptAddNote.groovy will be executed.
  • actions.Close.script=scriptClose.groovy: each time an Opsgenie alert is closed, <MARID_HOME>/scripts/scriptClose.groovy will be executed.
  • actions.TakeOwnership.script=scriptTakeOwnership.groovy: each time a user takes ownership of an alert in Opsgenie, <MARID_HOME>/scripts/scriptTakeOwnership.groovy will be executed.
  • actions.AssignOwnership.script=scriptAssignOwnership.groovy: each time someone assigns an alert to a user in Opsgenie, <MARID_HOME>/scripts/scriptAssignOwnership.groovy will be executed.
  • actions.AddRecipient.script=scriptAddRecipient.groovy: each time a user adds a recipient to an alert <MARID_HOME>/scripts/scriptAddRecipient.groovy will be executed.
  • actions.AddTeam.script=scriptAddTeam.groovy: each time a user adds a team to an alert <MARID_HOME>/scripts/scriptAddTeam.groovy will be executed.

Setting

Description

Mandatory

Default Value

actions.<action_name>.script=<script_name>

Alert actions to script mapping configuration. If specified for each execution of alert action configured groovy or ruby script file located in <MARID_HOME>/scripts directory will be called.

No

Alert Action Script Parameters

For your use in these action scripts, Opsgenie sends useful alert-related data to Marid. These parameters are ready to use in any script you put under <MARID_HOME>/scripts directory. These parameters are:

Parameter

Description

alert

The variable to access alert properties which action is executed for. alertId, username and properties like this may be accessed through this variable. You can see samples of alert data that Opsgenie makes available in this document.

action

Name of executed action

source

The variable to access the source of the executed action. It is a map with the following attributes:

  • type: Action execution source. May take one of following web, api, email to alert, chat, integration, voice, sms
  • name: Source property passed to Opsgenie API by the user. If no source is specified, it will be empty string.

Sample source: {"type":"api", "name":"source1"}

conf

A reference to configuration file properties. Every configuration property is accessible via this parameter.

logger

Logging utility. All script logs will be written to <LOGS_DIR>/script.log file.

opsgenie

The variable to execute an operation on Opsgenie server. Please refer to Script Proxy for Marid documentation for a list of available operations.