1. Home
  2. Integrations
  3. PowerShell Management API
Searching...

PowerShell Management API

Contents

Introduction

Exoprise exposes management functionality via a secure HTTPS based API. Authentication is provided via an apikey unique to each user. Access to Exoprise resources is subject to the same authorization checks as the Exoprise web interface. Currently the API supports:

  • Creating sensors
  • Modifying sensors
  • Querying sensors
  • Deleting sensors
  • Querying sites
  • Modifying sites
  • Deleting sites
  • Setting, modifying, and canceling site maintenance mode settings
  • Querying alarms
  • Querying for sites, sensors and alarms currently in the alarm state

A PowerShell wrapper for the raw API has been created as an open source PowerShell module implementing a set of cmdlets documented here.

Installation

  1. Works with PowerShell 5.1 and above.
  2. Download the sample Exoprise PowerShell client script module from the Exoprie API Settings page.
  3. Place the ExopriseApiModule folder (from the downloaded zip) in any one of the module auto-load paths specified by the PowerShell $env:psmodulepath variable
  4. The module is a script so the PowerShell execution policy must allow scripts to run.
  5. You will also need to unblock the file after its downloaded. You can do this through Windows Explorer (right-click and unblock through the properties) or use Unblock-File cmdlet with a path to the module file. For example: 
    Unblock-File "C:\Users\sample\Documents\WindowsPowerShell\Modules\ExopriseApiModule\ExopriseApiModule.psm1"
  6. Now the API cmdlets should be available.

Cmdlet Documentation

Set-ExoApiKey

Description

Sets the API key that will be used by subsequent cmdlets to authenticate the API request. Must be called for the other cmdlets to work.

Syntax

Set-ExoApiKey [-ApiKey] <String>

Get-ExoSensor

Description

Retrieves sensors that the user has access to.

Syntax
  1. Get-ExoSensor -Id <uint64[]>Get the sensors with the specified integer Ids (-Id 1 or -Id 1,2,3).
  2. Get-ExoSensor [-Site <String[]>] [-Type <String[]>] [-WithUnresolvedAlarms]
    • Without params gets all permitted sensors.
    • -Site param restricts to any of the specified site location names.
    • -Type param restricts to any of the specified sensor types.
    • -WithUnresolvedAlarms switch restricts to sensors with unresolved alarms. For each sensor lists the unresolved alarms with the ring information and timestamp (alarm_ring_info, alarm_rang_at). If it’s a aggregate alarm (% sensors affected), also shows when and why the sensor entered the alarm state (sensor_alert_info, sensor_alerted_at)
Details

The following sensor types are available:

ActiveDirectorySensor, AdfsSensor, EmailSensor:Gmail, EmailSensor:IMAP, EmailSensor:MAPI, EmailSensor:Hosted, EmailSensor:O365, EmailSensor:OWA, EmailSensor:EAS, SharePointSensor, DnsSensor, PingSensor, WGetSensor, WebLoginSensor, WebMonitorSensor, DropboxWebLoginSensor, SalesforceWebLoginSensor, BoxWebLoginSensor, GitHubWebLoginSensor, AssemblaWebLoginSensor, O365PortalWebLoginSensor, OktaWebLoginSensor, OneloginWebLoginSensor, ConcurWebLoginSensor, MarketoWebLoginSensor, DocuSignWebLoginSensor, PingOneWebLoginSensor, ServiceNowWebLoginSensor, WorkdayWebLoginSensor, VoIPSensor, BandwidthSensor, AWSBandwidthSensor, AzureBandwidthSensor,  VoIPReceiver, BandwidthReceiver

Add-ExoSensor

Description

Deploys a sensor to one or more sites. Returns the sensors deployed in the same format as Get-ExoSensor.

Syntax

Add-ExoSensor [-Spec] <Hashtable>

Details

Example:

Add-ExoSensor @{
  type = 'WGetSensor'
  interval = 1
  nickname = 'api3'
  sites = @{location = @('LOCATION_NAME')}
  config = @{
    targets = @(
      @{target = 'http://www.example.org/'}
    )
  }
}

-Spec hashtable keys are required unless they have a default value.

Available keys:

  • type – [string]. See Get-ExoSensor Details for values.
  • error_disable – [int], default: 6, unit: hour, choices: 3, 6, 12, 24. Hours of consecutive errors after which the sensor is disabled.
  • auto_alarm – [int], default: 4, unit: hour, choices: 0, 4, 8, 12, 14, disable: 0. Setup default alarms after this number of hours.
  • public – [bool], optional: $false. Specify $true when deploying to public sites.
  • sites – [hashtable]. Specifies the sites to which to deploy the sensor. Can contain only one of the following keys:
    • id – [int[]] (array of site ids)
    • location – [string[]] (array of site location names)
    • nickname – [string[]] (array of site nicknames). Public sites can only be specified by nickname: 'PUB-VIRGINIA', 'PUB-TOKYO', 'PUB-SYDNEY', PUB-IRELAND', 'PUB-NCALI', 'PUB-OREGON'
  • interval – [int], unit: minute, choices: 1, 2, 5, 10, 15, 20. Interval at which to runs the sensor. Required for sensors. Forbidden for receivers. Some sensor types will reject some intervals.
  • nickname – [string], default: ''. Custom display name of the sensor
  • notes – [string], default: ''. Notes text for the sensor.
  • peered_receiver_id – [int]. Only for sensors that must be paired with a receiver: BandWidthSensor, VoIPSensor.
  • oauth – [string]. Label of a Exoprise OAuth registration to link with the sensor. For some sensors it’s optional (EwsCalSensor, EmailSensor:O365, EmailSensor:OWA). For some required (AzureAdSensor, OnedriveGraphSensor, SharepointGraphSensor, TeamsAVSensor). For the rest, forbidden.
  • config – [hashtable]. Configuration specific to the sensor type. Has the following Keys for different types:
    • ActiveDirectorySensor
      • server – [string]
      • username – [string]
      • password – [string]
    • AdfsSensor
      • config_perf_enabled – [bool], default: $true
      • config_trans_enabled – [bool], default: $true
      • config_perf_server – [string]
      • config_perf_user – [string]
      • config_perf_password – [string]
      • config_trans_server – [string]
      • config_trans_user – [string]
      • config_trans_password – [string]
      • config_trans_certIssuer – [string]
      • config_trans_endpointURL – [string]
      • config_trans_adfsURL – [string]
      • config_trans_spnIdentity – [string]
      • server – [string]
    • EmailSensor:*
      • username – [string]
      • email_address – [string]
      • password – [string]
      • incoming_server_name – [string]
      • impersonation_enabled – [bool], default: $false
      • impersonated_user – [string]
      • shared_mailbox – [string]
      • incoming_server_ssl – [bool]
      • incoming_server_port – [int]
      • outgoing_server_name – [string]
      • outgoing_server_port – [int]
      • outgoing_server_ssl – [string]
      • domain_controller – [string]
      • mta_tests – [bool], default: $true
    • SharePointSensor
      • email – [string]
      • password – [string]
      • url – [string]
      • document_library – [string], default: ''
      • run_file_routines – [bool], default: $true
      • sp_upload_url – [string], default: ''
    • WebLoginSensor
      • username – [string]
      • password – [string]
      • targets – [hashtable[]], an array of target hashtables. Only one target is allowed. Target hashtable has one key:
        • target – [string]. The starting url.
    • *WebLoginSensor – customized WebLoginSensors (e.g. BoxWebLoginSensor) take the same keys as WebLoginSensor with some difference in the targets array.
      • The following sensors do not take a targets array at all:DropboxWebLoginSensor, SalesforceWebLoginSensor, GitHubWebLoginSensor, AssemblaWebLoginSensor, O365PortalWebLoginSensor, ConcurWebLoginSensor, MarketoWebLoginSensor, DocuSignWebLoginSensor
      • For the following sensors the target hash must have a subdomain [string] key (instead of target)BoxWebLoginSensor, OktaWebLoginSensor, OneloginWebLoginSensor, ServiceNowWebLoginSensor, WorkdayWebLoginSensor
      • PingOneWebLoginSensor – the target hash must have an identity [string] key (instead of target)
    • WebMonitorSensor
      • targets – [hashtable[]], an array of target hashtables. Up to 4 targets are allowed. Target hashtable has one key:
        • target – [string]. The starting url.
    • WGetSensor
      • targets – [hashtable[]], an array of target hashtables. Up to 4 targets are allowed. Target hashtable has one key:
        • target – [string]. The starting url.
    • DnsSensor
      • targets – [hashtable[]], an array of target hashtables. Up to 4 targets are allowed. Target hashtable has one key:
        • target – [string]. Hostname to look up.
    • PingSensor
      • targets – [hashtable[]], an array of target hashtables. Up to 4 targets are allowed. Target hashtable has one key:
        • target – [string]. Hostname or IP to ping.
    • BandwidthReceiver
      • host – string, default: $null. Hostname used by peered bandwidth sensors to connect to the receiver. Auto-detected ip will be used if unspecified
      • port – [int], default: auto generated.
    • BandWidthSensor
      • payload_size – [int], unit: MB, default: 4, choices: 1, 2, 4, 10, 20
      • force_http – [bool], default: $false
      • non_unique_payload – [bool], default: $false
      • non_unique – [bool], default: $false
      • ignore_proxy – [bool], default: $false
    • VoIPReceiver
      • host – string, default: $null. Hostname used by peered bandwidth sensors to connect to the receiver. Auto-detected ip will be used if unspecified
      • port – [int], default: auto generated.
    • VoIPSensor
      • receiver_port – [int], optional. If the receiver is configured with multiple ports this lets you choose one. If omitted, the sensor will use the first configured receiver port.

Set-ExoSensor

Description

Update an existing sensor.

Syntax

Set-ExoSensor [-Spec] <Hashtable>

Details

Other than id, the other top level -Spec hashtable keys are optional, but something must be present. Returns the updated sensor.

Available keys:

  • id – [int], required. ID of the sensor to update.
  • interval – [int], unit: minute, choices: 1, 2, 5, 10, 15, 20. Interval at which to runs the sensor. Required for sensors. Forbidden for receivers. Some sensor types will reject some periods.
  • nickname – [string]
  • notes – [string]
  • enabled – [bool]. Enable/disable the sensor.
  • oauth – [string|bool]. See Add-ExoSensor for details. When optional, $false or $null can be passed to disable the use of OAuth.
  • config – [hashtable]. For config keys see Add-ExoSensor details. Unlike Add-ExoSensor all config keys are optional.

Remove-ExoSensor

Description

Delete an existing sensor.

Syntax

Remove-ExoSensor [-Id] <Int>

Details

Returns the deleted sensor with the destroyed property set to $true

Get-ExoSite

Description

Query for sites the user has access to.

Syntax

Get-ExoSite [-WithUnresolvedAlarms]

  • Without params returns a list of sites with sensors
  • -WithUnresolvedAlarms switch restrict to sites with sensors with unresolved alarms. The sensors list for each site is also restricted to to those with unresolved alarms. Each sensor will contain a list its unresolved alarms (unresolved_alarms).

Set-ExoSite

Description

Update an existing site.

Syntax
  1. Set-ExoSite [-Id] <int> [-Spec] <hashtable>
  2. Set-ExoSite -Location <string> [-Spec] <hashtable>
  3. Set-ExoSite -Nickname <string> [-Spec] <hashtable>
  • -Id, -Location, or -Nickname may be used to specify a site to update.
  • Available keys for -Spec:
    • nickname – [string]
    • street_address – [string]
    • receives_alarms – [bool], site logs alarms in it’s own log
    • logs_alarms – [bool], logs alarms to Windows log

Remove-ExoSite

Description

Deletes an existing site.

Syntax
  1. Remove-ExoSite [-Id] <int>
  2. Remove-ExoSite -Location <string>
  3. Remove-ExoSite -Nickname <string>
  • -Id, -Location, or -Nickname may be used to specify a site to delete.

Add-ExoSiteMaintenance

Description

Put a site in maintenance mode.

Syntax
  1. Add-ExoSiteMaintenance [-Id] <int[]> [-Spec] <hashtable>
  2. Add-ExoSiteMaintenance -Location <string[]> [-Spec] <hashtable>
  3. Add-ExoSiteMaintenance -Nickname <string[]> [-Spec] <hashtable>
  • -Id, -Location, or -Nickname may be used to specify one or more sites and put them in maintenance mode.
  • -Spec sets attributes for maintenance mode.
  • Available keys for -Spec:
    • duration – [int]
    • auto_deactivate – [bool], if true maintenance mode will end as soon as the site successfully makes a connection

Set-ExoSiteMaintenance

Description

Update an existing site maintenance mode.

Syntax
  1. Set-ExoSiteMaintenance [-Id] <int[]> [-Spec] <hashtable>
  2. Set-ExoSiteMaintenance -Location <string[]> [-Spec] <hashtable>
  3. Set-ExoSiteMaintenance -Nickname <string[]> [-Spec] <hashtable>
  • -Id, -Location, or -Nickname may be used to specify one or more sites and update their maintenance mode attributes.
  • -Spec sets attributes for maintenance mode.
  • Available keys for -Spec:
    • duration – [int], duration extends the maintenance mode duration, it does not overwrite it
    • auto_deactivate – [bool], if true maintenance mode will end as soon as the site successfully makes a connection

Remove-ExoSiteMaintenance

Description

Remove an a site from maintenance mode.

Syntax
  1. Remove-ExoSiteMaintenance [-Id] <uint64[]>
  2. Remove-ExoSiteMaintenance -Location <string[]>
  3. Remove-ExoSiteMaintenance -Nickname <string[]>
  • -Id, -Location, or -Nickname may be used to specify one or more sites to take out of maintenance mode.

Get-ExoAlarm

Description

Query for alarms the user has access to. Retrieve alarm history.

Syntax
  1. Get-ExoAlarm -Id <uint64[]> [-VerboseOutput]Get the alarms with the specified integer Ids (-Id 1 or -Id 1,2,3).
    • -VerboseOutput outputs in the same format as Add/Set-ExoAlarm
  2. Get-ExoAlarm [-SensorId <uint64[]>] [-Site <String[]>] [-SiteId <String[]>] [-SensorType <String[]>] [-Unresolved] [-VerboseOutput]
    • Without params gets all permitted alarms
    • -SensorId restricts to alarms for any of the specified sensor ids
    • -Site restricts to alarms for sensors on any of the specified site location or display names
    • -SiteId restricts to alarms for sensors on any of the specified site ids
    • -SensorType restricts to any of the specified sensor type
    • -Unresolved restricts to currently unresolved alarms
    • -VerboseOutput outputs in the same format as Add/Set-ExoAlarm
  3. Get-ExoAlarm -History [-Period <String>] [-From <DateTime>] [-To <DateTime>] [-Id <uint64[]>] [-SensorId <uint64[]>] [-Site <String[]>] [-SiteId <String[]>] [-SensorType <String[]>] [-Unresolved] [-VerboseOutput]Get alarm history (up to 90 days of alarm rings are kept). Either -Period or -From must be specified.
    • -Period – specifies how far back in time to look. Can be one of the following strings: 3h, 6h, 12h, 1d, 7d, 30d, 90d.
    • -From – starting DateTime. A string (e.g. 2017-04-24T12:00:00Z) is automatically converted to a DateTime.
    • -To – optional end DateTime.
    • -Id – restricts to rings of any of the specified by id alarms
    • -SensorId – restricts to rings for any of the specified sensor ids
    • -Site – restricts to rings for sensors on any of the specified site location or display names
    • -SiteId – restricts to rings for sensors on any of the specified site ids
    • -SensorType – restricts to rings on sensors of any of the specified sensor types
Details

Returns:

  • alarm meta-data (id, name, type, ring_condition, etc)
  • sensors attached to the alarm (array of sensor meta-data objects)
  • alarm resolved state: resolved
    • for aggregate alarms (% sensors affected)
      • returns alarm_ring_info and alarm_rang_at in the alarm object, since the ring state is global across all sensors
      • returns sensor_alert_info and sensor_alerted_at in the sensor objects. This shows when and why a specific sensor that contributed to the ringing of the alarm entered alarmed state.
    • for per sensor alarms
      • returns alarm_ring_info and alarm_rang_at in the sensor object, since the ring state is specific to each sensor.

Add-ExoAlarm

Description

Adds an alarm to a sensor. Returns the same information as Get-ExoAlarm plus the alarm’s specification.

Syntax
  1. Add-ExoAlarm -SensorId <uint64[]> -SensorType <string> -Lag <uint64> [-Element <string>] [-Disable] [-SensorsAffectedThreshold <int>] [-RecipientGroup <string>] [-EmailHook <string[]>] [-WebHook <string[]>] [-Name <string>] [-EmailSubjectTemplate <string>] [-Notes <string>]
  2. Add-ExoAlarm -SensorId <uint64[]> -SensorType <string> -Element <string> -ConsecutiveErrors <uint64> [-Disable] [-SensorsAffectedThreshold <int>] [-RecipientGroup <string>] [-EmailHook <string[]>] [-WebHook <string[]>] [-Name <string>] [-EmailSubjectTemplate <string>] [-Notes <string>]
  3. Add-ExoAlarm -SensorId <uint64[]> -SensorType <string> -Element <string> -ThresholdOperator <string> -ThresholdValue <decimal> [-SensorIntervals <uint64>] [-TimeSpan <uint64>] [-Disable] [-SensorsAffectedThreshold <int>] [-RecipientGroup <string>] [-EmailHook <string[]>] [-WebHook <string[]>] [-Name <string>] [-EmailSubjectTemplate <string>] [-Notes <string>]
Details
  • SensorIds – [uint64[]], required. Numeric ids of the sensors to alarm on.
  • SensorType – [string], required. See Get-ExoSensor Details for the list of possible values.
  • Disable – [switch], disables the alarm when set.
  • SensorsAffectedThreshold – [int], default: 0. The percentage of sensors that must be in an alarm state before the alarm is triggered. When this is 0, the alarm is triggered when any sensor enters the alarm state. Must be a multiple of 10 between 0 and 100.
  • recipient_group – [string], optional. The name of the group of users that is contacted when the alarm is triggered. If this is not provided the default recipient group is selected.
  • EmailHook – [string[]], optional. The name(s) of any email hooks to contact when the alarm is triggered.
  • WebHook – [string[]], optional. The name(s) of any web hooks to contact when the alarm is triggered.
  • name – [string], optional. A nickname for the alarm. If this is not provided one will be automatically generated from the sensor type and alarm element.
  • email_subject_template – [string], default: $element$ for: $sensor_title$. See https://help.exoprise.com/kb/how-to-create-an-alarm/#email-subject-template for more information
  • notes – [string], optional. Notes or comments associated with the alarm.

Additionally, certain parameters are required depending on the type of alarm.

Off-Schedule Alarm (alarm with the element “operations.SensorOffSchedule”)
  • Lag – [uint64], required. How many minutes the sensor is off schedule when the alarm triggers.
  • Element – [string], optional. Must be set to “operations.SensorOffSchedule” if supplied.
Error Alarm (alarm whose element contains the word “error”)
  • Element – [string], required. See the element selector at https://secure.exoprise.com/alarms/new or download “Metric Documentation” from the sensor details page for the list of possible values (only those which contain the word “error”).
  • ConsecutiveErrors – [uint64], required. The number of consecutive sensor runs where the error is raised that triggers the alarm.
Data Alarm (all other alarms)

One, but not both, of:

  • SensorIntervals – [uint64], the number of sensor intervals that pass before the alarm condition is checked.
  • TimeSpan – [uint64], the number of minutes that pass before the alarm condition is checked.

As well as:

  • Element – [string], required. See the element selector at https://secure.exoprise.com/alarms/new or download “Metric Documentation” from the sensor details page for the list of possible values (except “operations.SensorOffSchedule” and those which contain the word “error”).
  • ThresholdValue – [decimal], required. The number to compare to the sensors’ readings when the alarm condition is checked.
  • ThresholdOperator – [string], required. The type of comparison to perform. Must be one of “>”, “<“, “>=”, “<=”, “==” or “!=”. Note that “>” and “<” must be quoted in PowerShell.

Set-ExoAlarm

Description

Alter the properties of an existing alarm. Returns the same information as Add-ExoAlarm.

Syntax
  1. -Id <uint64> [-SensorId <uint64[]>] [-ConsecutiveErrors] [-Enabled <bool>] [-SensorsAffectedThreshold <int>] [-RecipientGroup <string>] [-EmailHook <string[]>] [-WebHook <string[]>] [-Name <string>] [-EmailSubjectTemplate <string>] [-Notes <string>]
  2. -Id <uint64> [-SensorId <uint64[]>] [-Lag <uint64>] [-Enabled <bool>] [-SensorsAffectedThreshold <int>] [-RecipientGroup <string>] [-EmailHook <string[]>] [-WebHook <string[]>] [-Name <string>] [-EmailSubjectTemplate <string>] [-Notes <string>]
  3. -Id <uint64> [-SensorId <uint64[]>] [-SensorIntervals <uint64>] [-TimeSpan <uint64>] [-ThresholdOperator <string>] [-ThresholdValue <decimal>] [-Enabled <bool>] [-SensorsAffectedThreshold <int>] [-RecipientGroup <string>] [-EmailHook <string[]>] [-WebHook <string[]>] [-Name <string>] [-EmailSubjectTemplate <string>] [-Notes <string>]
Details
  • Id – [uint64], required. The numeric id of the alarm to be updated.
  • SensorIds – [uint64[]], optional. Numeric ids of the sensors to alarm on.
  • Enabled – [bool], optional. Enables or disables the alarm.
  • SensorsAffectedThreshold – [int], optional. The percentage of sensors that must be in an alarm state before the alarm is triggered. When this is 0, the alarm is triggered when any sensor enters the alarm state. Must be a multiple of 10 between 0 and 100.
  • recipient_group – [string], optional. The name of the group of users that is contacted when the alarm is triggered.
  • EmailHook – [string[]], optional. The name(s) of any email hooks to contact when the alarm is triggered.
  • WebHook – [string[]], optional. The name(s) of any web hooks to contact when the alarm is triggered.
  • name – [string], optional. A nickname for the alarm.
  • email_subject_template – [string], optional. See https://help.exoprise.com/kb/how-to-create-an-alarm/#email-subject-template for more information
  • notes – [string], optional. Notes or comments associated with the alarm.

Additionally, certain parameters are allowed depending on the type of alarm.

Off-Schedule Alarm (alarm with the element “operations.SensorOffSchedule”)
  • Lag – [uint64], optional. How many minutes the sensor is off schedule when the alarm triggers.
Error Alarm (alarm whose element contains the word “error”)
  • ConsecutiveErrors – [uint64], optional. The number of consecutive sensor runs where the error is raised that triggers the alarm.
Data Alarm (all other alarms)

Zero or one, but not both, of:

  • SensorIntervals – [uint64], the number of sensor intervals that pass before the alarm condition is checked.
  • TimeSpan – [uint64], the number of minutes that pass before the alarm condition is checked.

As well as:

  • ThresholdValue – [decimal], optional. The number to compare to the sensors’ readings when the alarm condition is checked.
  • ThresholdOperator – [string], optional. The type of comparison to perform. Must be one of “>”, “<“, “>=”, “<=”, “==” or “!=”. Note that “>” and “<” must be quoted in PowerShell.

Remove-ExoAlarm

Description

Deletes an alarm. Returns the same information as Get-ExoAlarm.

Syntax

-Id <uint64> [-VerboseOutput]

Details
  • Id – [uint64], required. The numeric id of the alarm to be deleted.
  • VerboseOutput – [switch], outputs in the same format as Add/Set-ExoAlarm when set.
Tagged:

Related Articles