Exoprise CloudReady® Help
Search:     Advanced search

Exoprise Management API

Article ID: 103
Last updated: 25 Apr, 2017

Introduction

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

  • Creating sensors
  • Modifying sensors
  • Querying sensors
  • Deleting sensors
  • Querying sites
  • 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 3 and above.
  2. Download the sample Exoprise PowerShell client script module from the CloudReady 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 <Int[]>

    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, SkypeAudioSensor, SkypeMessageSensor, AWSBandwidthSensor, AzureBandwidthSensor, SkypeReceiver, 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.
  • 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
      • peered_receiver_id - [int]. ID of the receiver with which the sensor communicates.
      • 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
    • SkypeReceiver
      • username - [string]
      • password - [string]
      • sip_address - [string]
      • internal_server_name - [string], default: $null
      • external_server_name - [string], default: $null
    • SkypeMessageSensor, SkypeAudioSensor
      • all keys from SkypeReceiver
      • peered_receiver_id - [int]. ID of the receiver with which the sensor communicates.
    • 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
      • peered_receiver_id - [int]. ID of the receiver with which the sensor communicates.

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]
  • 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 parms 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).

Get-ExoAlarm

Description

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

Syntax
  1. Get-ExoAlarm -Id <Int[]>

    Get the alarms with the specified integer Ids (-Id 1 or -Id 1,2,3).

  2. Get-ExoAlarm [-SensorId <Int[]>] [-Site <String[]>] [-SiteId <String[]>] [-SensorType <String[]>] [-Unresolved]

    • 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
  3. Get-ExoAlarm -History [-Period <String>] [-From <DateTime>] [-To <DateTime>] [-Id <Int[]>] [-SensorId <Int[]>] [-Site <String[]>] [-SiteId <String[]>] [-SensorType <String[]>] [-Unresolved]

    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.
Prev   Next
Access Control in an Organization Account     Sensor - ADFS