PowerShell Management API

It sets the API key that will be used by subsequent cmdlets to authenticate the API request. It must be called for the other cmdlets to work. To learn how to generate your API key parameter, refer to Generating API keys for integrations.

Syntax

Set-ExoApiKey [-ApiKey] <String>

It retrieves sensors that the user has access to.

Syntax

1. Copy

   Get-ExoSensor -Id <uint64[]>

   • It gets the sensors with the specified integer Ids (-Id 1 or -Id 1,2,3).

2. Copy

   Get-ExoSensor [-Site <String[]>] [-Type <String[]>] [-WithUnresolvedAlarms]

   • Without parameters, it gets all permitted sensors.

   • The -Site parameter restricts to any of the specified site location names.

   • The -Type parameter restricts to any of the specified sensor types.

   • The -WithUnresolvedAlarms switch restricts to sensors with unresolved alarms. For each sensor, it lists the unresolved alarms with the ring information and timestamp (alarm_ring_info, alarm_rang_at). If it's an aggregate alarm (% sensors affected), it also shows when and why the sensor entered the alarm state (sensor_alert_info, sensor_alerted_at).

Sensor types

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

It deploys a sensor to one or more sites. It 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]. For values, refer to Sensor types in Get-ExoSensor.

• 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. Set up 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 run 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 an Exoprise OAuth registration to link with the sensor. For some sensors, it's optional (EwsCalSensor, EmailSensor:O365, EmailSensor:OWA). For others, it's required (AzureAdSensor, OnedriveGraphSensor, SharepointGraphSensor, TeamsAVSensor). For the rest, it's forbidden.

• config - [hashtable]. Configuration specific to the sensor type. It 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 (for example, 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 four targets are allowed. Target hashtable has one key:

      • target - [string]. The starting URL.

  • WGetSensor

    • targets - [hashtable[]], an array of target hashtables. Up to four targets are allowed. Target hashtable has one key:

      • target - [string]. The starting URL.

  • DnsSensor

    • targets - [hashtable[]], an array of target hashtables. Up to four targets are allowed. Target hashtable has one key:

      • target - [string]. Hostname to look up.

  • PingSensor

    • targets - [hashtable[]], an array of target hashtables. Up to four 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.

It updates 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. It 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 run the sensor. Required for sensors. Forbidden for receivers. Some sensor types will reject some periods.

• nickname - [string]

• notes - [string]

• enabled - [bool]. Enables/disables the sensor.

• oauth - [string|bool]. For details, refer to Add-ExoSensor. When optional, $false or $null can be passed to disable the use of OAuth.

• config - [hashtable]. For details on config keys, refer to Add-ExoSensor. Unlike Add-ExoSensor, all config keys are optional.

It deletes an existing sensor.

Syntax

Remove-ExoSensor [-Id] <Int>

Details

It returns the deleted sensor with the destroyed property set to $true.

It queries for sites the user has access to.

Syntax

Get-ExoSite [-WithUnresolvedAlarms]

• Without parameters, it returns a list of sites with sensors.

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

It updates an existing site.

Syntax

1. Copy

   Set-ExoSite [-Id] <int> [-Spec] <hashtable>

2. Copy

   Set-ExoSite -Location <string> [-Spec] <hashtable>

3. Copy

   Set-ExoSite -Nickname <string> [-Spec] <hashtable>

Details

• -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 its own log.

  • logs_alarms - [bool], logs alarms to Windows log.

It deletes an existing site.

Syntax

1. Copy

   Remove-ExoSite [-Id] <int>

2. Copy

   Remove-ExoSite -Location <string>

3. Copy

   Remove-ExoSite -Nickname <string>

Details

• -Id, -Location, or -Nickname may be used to specify a site to delete.

It puts a site in maintenance mode.

Syntax

1. Copy

   Add-ExoSiteMaintenance [-Id] <int[]> [-Spec] <hashtable>

2. Copy

   Add-ExoSiteMaintenance -Location <string[]> [-Spec] <hashtable>

3. Copy

   Add-ExoSiteMaintenance -Nickname <string[]> [-Spec] <hashtable>

Details

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

It updates an existing site maintenance mode.

Syntax

1. Copy

   Set-ExoSiteMaintenance [-Id] <int[]> [-Spec] <hashtable>

2. Copy

   Set-ExoSiteMaintenance -Location <string[]> [-Spec] <hashtable>

3. Copy

   Set-ExoSiteMaintenance -Nickname <string[]> [-Spec] <hashtable>

Details

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

It removes a site from maintenance mode.

Syntax

1. Copy

   Remove-ExoSiteMaintenance [-Id] <uint64[]>

2. Copy

   Remove-ExoSiteMaintenance -Location <string[]>

3. Copy

   Remove-ExoSiteMaintenance -Nickname <string[]>

Details

• -Id, -Location, or -Nickname may be used to specify one or more sites to take out of maintenance mode.

It queries for alarms the user has access to. It retrieves alarm history.

Syntax

1. Copy

   Get-ExoAlarm -Id <uint64[]> [-VerboseOutput]

   • It gets 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. Copy

   Get-ExoAlarm [-SensorId <uint64[]>] [-Site <String[]>] [-SiteId <String[]>] [-SensorType <String[]>] [-Unresolved] [-VerboseOutput]

   • Without parameters, it 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. Copy

   Get-ExoAlarm -History [-Period <String>] [-From <DateTime>] [-To <DateTime>] [-Id <uint64[]>] [-SensorId <uint64[]>] [-Site <String[]>] [-SiteId <String[]>] [-SensorType <String[]>] [-Unresolved] [-VerboseOutput]

   • It gets 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. It can be one of the following strings: 3h, 6h, 12h, 1d, 7d, 30d, 90d.

   • -From: Starting DateTime. A string (for example, 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

It returns the following:

• Alarm meta-data (id, name, type, ring_condition, and so on)

• Sensors attached to the alarm (array of sensor meta-data objects)

• Alarm resolved state: resolved.

  • For aggregate alarms (% sensors affected):

    • It returns alarm_ring_info and alarm_rang_at in the alarm object since the ring state is global across all sensors.

    • It 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:

    • It returns alarm_ring_info and alarm_rang_at in the sensor object since the ring state is specific to each sensor.

It adds an alarm to a sensor. It returns the same information as Get-ExoAlarm plus the alarm's specification.

Syntax

1. Copy

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

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

   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. For values, refer to Sensor types in Get-ExoSensor.

• 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. It 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 or names of any email hooks to contact when the alarm is triggered.

• WebHook - [string[]], optional. The name or names 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$. For more information, refer to Email subject template.

• notes - [string], optional. Notes or comments associated with the alarm.

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

Off-schedule alarm

An 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

An alarm whose element contains the word error.

• Element - [string], required. Refer to the element selector or download Metric Documentation from the sensor details page for the list of possible values (only those that 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 the following:

• 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 the following:

• Element - [string], required. Refer to the element selector or download Metric Documentation from the sensor details page for the list of possible values (except for operations.SensorOffSchedule and those that 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.

It alters the properties of an existing alarm. It returns the same information as Add-ExoAlarm.

Syntax

1. Copy

   -Id <uint64> [-SensorId <uint64[]>] [-ConsecutiveErrors] [-Enabled <bool>] [-SensorsAffectedThreshold <int>] [-RecipientGroup <string>] [-EmailHook <string[]>] [-WebHook <string[]>] [-Name <string>] [-EmailSubjectTemplate <string>] [-Notes <string>]

2. Copy

   -Id <uint64> [-SensorId <uint64[]>] [-Lag <uint64>] [-Enabled <bool>] [-SensorsAffectedThreshold <int>] [-RecipientGroup <string>] [-EmailHook <string[]>] [-WebHook <string[]>] [-Name <string>] [-EmailSubjectTemplate <string>] [-Notes <string>]

3. Copy

   -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. It 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 or names of any email hooks to contact when the alarm is triggered.

• WebHook - [string[]], optional. The name or names of any web hooks to contact when the alarm is triggered.

• name - [string], optional. A nickname for the alarm.

• email_subject_template - [string], optional. For more information, refer to Email subject template.

• notes - [string], optional. Notes or comments associated with the alarm.

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

Off-schedule alarm

An alarm with the element operations.SensorOffSchedule.

• Lag - [uint64], optional. How many minutes the sensor is off schedule when the alarm triggers.

Error alarm

An 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 the following:

• 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 the following:

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

It deletes an alarm. It 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.