RepositoryAPI

The RepositoryAPI performs all communication with the mPulse Repository. You use it first to authenticate, and then to create, modify, query, and delete objects from the mPulse Repository.

Connecting to the Repository

If using an alternate mPulse endpoint (for example, your dev system), you will first need to tell this module about your endpoint:

mPulseAPI.setEndpoints — Function

Change the mPulse API endpoint that we connect to. The default is https://mpulse.soasta.com/concerto

Example

mPulseAPI.setEndpoints("https://mpulse-alt.soasta.com/concerto")

source

Authenticate with the Repository

To authenticate with the Repository, you will first need an API Token from mPulse. Once you have the API Token, you will call out to getRepositoryToken to authenticate and get a session token. This session token will be used for all subsequent calls to the Repository and Query APIs. The session token is valid until you sign out of mPulse.

mPulseAPI.getRepositoryToken — Function

Logs in to the mPulse repository and fetches an Authorization token that can be used for other calls

The token will be cached in memory for 5 hours, so subsequent calls using the same tenant will return quickly without calling out to the API. This can be a problem if the account has signed in from a different location or is logged out of mPulse. You can clear the cache for this token using mPulseAPI.clearTokenCache

Arguments

tenant::AbstractString : The name of the tenant to log in to. The token will be bound to this tenant.

apiToken::AbstractString : The apiToken issued by mPulse that allows authenticating with the API. If you've previously authenticated with this tenant, the apiToken will be cached and does not need to be passed in again

Returns

{ASCIIString} The mPulse Repository Auth token which may be used in the X-Auth-Token header for subsequent API calls

Throws

ArgumentError : if the tenant or apiToken are empty

mPulseAPIAuthException : if authentication failed for some reason

source

Communicating with the Repository

This module provides wrappers for the tenant, domain, alert and statisticalmodel object types. While you can only fetch Tenant & Domain (aka Application) details using this API, you can do more with Alerts.

Tenants, Domains & Applications

mPulseAPI.getRepositoryTenant — Method

Fetches a Tenant object from the mPulse repository

At least one of tenantID or name must be passed in to identify the tenant.

The tenant will be cached in memory for 1 hour, so subsequent calls using a matching tenantID, or name return quickly without calling out to the API. This can be a problem if the tenant changes in the repository. You can clear the cache for this tenant using mPulseAPI.clearTenantCache and passing in one of tenantID or name.

Arguments

token::AbstractString : The Repository authentication token fetched by calling getRepositoryToken

Keyword Arguments

tenantID::Int64 : The ID of the tenant to fetch. This is the fastest method, but it can be hard to figure out a tenant's ID

name::AbstractString : The Tenant name in mPulse. This is available from the mPulse tenant list.

Returns

{Dict} The tenant object with the following fields:

name::AbstractString : The tenant's name

id::Int64 : The tenant's ID

body::XMLElement : An XML object representing the tenant's XML definition or an empty node if you do not have permission to see the full tenant

parentID::Int64 : The ID of the parent folder that this tenant is in

parentType::AbstractString : The type of parent object (typically tenantFolder)

path::AbstractString : The folder path that this tenant is in

description::AbstractString : The description of this tenant entered into mPulse

created::DateTime : The timestamp when this object was created

lastModified::DateTime : The timestamp when this object was created

attributes::Dict : A Dict of attributes for this tenant

dswbUrls::Array{AbstractString} : An array of DSWB URLs that are valid auth redirect targets for this tenant

Throws

ArgumentError : if token is empty or tenantID and name are both empty

mPulseAPIException : if API access failed for some reason

source

mPulseAPI.getCustomMetricMap — Method

Gets a mapping of custom metric names to database field names from domain XML. This list also includes valid dates.

Arguments

body::{AbstractString|XMLElement|Dict} : This is an object containing the domain XML returned by mPulseAPI.getRepositoryDomain. It may be:

An AbstractString containing the domain XML. This will be parsed.
A LightXML.XMLElement pointing to the root node of the domain XML.
A Dict with a body element. This is the domain object returned by mPulseAPI.getRepositoryDomain.

Returns

{Dict} of Custom Metric names mapped to database fieldnames with the following structure:

Dict(
    <metric name> => Dict(
        "index"        => <index>,                      # Numeric index
        "fieldname"    => "custommetric<index>",        # Field name in dswb tables
        "lastModified" => <lastModifiedDate>,
        "description"  => "<description>",
        "dataType"     => Dict(
            "decimalPlaces"  => "2",
            "type"           => "<metric type>",
            "currencyCode"   => "<ISO 4217 Currency Code if type==Currency>"
        ),
        "colors"       => [<array of color HEX codes>]
    ),
    ...
)

Throws

ArgumentError : if the data type of body is unknown.

LightXML.XMLParseError : if body is an AbstractString but contains invalid XML

source

mPulseAPI.getCustomTimerMap — Method

Gets a mapping of custom timer names to database field names from domain XML. This list also includes valid dates.

Arguments

body::{AbstractString|XMLElement|Dict} : This is an object containing the domain XML returned by mPulseAPI.getRepositoryDomain. It may be:

An AbstractString containing the domain XML. This will be parsed.
A LightXML.XMLElement pointing to the root node of the domain XML.
A Dict with a body element. This is the domain object returned by mPulseAPI.getRepositoryDomain.

Returns

{Dict} of Custom Timer names mapped to database fieldnames with the following structure:

Dict(
    <timer name> => Dict(
        "index"         => <index>,                      # Numeric index
        "fieldname"     => "customtimer<index>",         # Field name in dswb tables
        "mpulseapiname" => "CustomTimer<index>",
        "lastModified"  => <lastModifiedDate>,
        "description"   => "<description>",
        "colors"        => Array(
            Dict(
                "timingType"  => "<seconds | milliseconds>",
                "timingStart" => "<start timer value for this colour range>",
                "timingEnd"   => "<end timer value for this colour range>",
                "colorStart"  => "<start of this color range>",
                "endStart"    => "<end of this color range>"
            ),
            ...
        )
    ),
    ...
)

Throws

ArgumentError : if the data type of body is unknown.

LightXML.XMLParseError : if body is an AbstractString but contains invalid XML

source

mPulseAPI.getRepositoryDomain — Method

Fetches a Domain object from the mPulse repository

To fetch a single domain, at least one of domainID, appKey or appName must be passed in to identify the domain. If none of these are passed in, then all domains that are readable by the specified token will be returned as an array.

The domain will be cached in memory for 1 hour, so subsequent calls using a matching domainID, appKey or appName return quickly without calling out to the API. This can be a problem if the domain changes in the repository. You can clear the cache for this domain using mPulseAPI.clearDomainCache and passing in one of domainID, appKey or appName.

Arguments

token::AbstractString : The Repository authentication token fetched by calling getRepositoryToken

Keyword Arguments

domainID::Int64 : The ID of the domain to fetch. This is the fastest method, but it can be hard to figure out a domain's ID

appKey::AbstractString : The App Key (formerly known as API key) associated with the domain. This is available from the mPulse domain configuration dialog.

appName::AbstractString : The App name in mPulse. This is available from the mPulse domain configuration dialog.

Returns

{Dict|Array{Dict}} If one of domainID, appKey or appName are passed in, then a single domain object is returned as a Dict.

If none of these are passed in, then an array of all domains is returned, each is a Dict.

The domain Dict has the following fields:

name : The app's name

id::Int64 : The app's ID

body::XMLElement : An XML object representing the app's XML definition

tenantID::Int64 : The ID of the tenant that this app is in

description::AbstractString : The description of this app entered into mPulse

created::DateTime : The timestamp when this object was created

lastModified::DateTime : The timestamp when this object was created

attributes::Dict : A Dict of attributes for this app, including its AppKey

custom_metrics::Dict : A {Dict} of Custom Metric names mapped to database fieldnames with the following structure:

Dict(
    <metric name> => Dict(
        "index"        => <index>,                      # Numeric index
        "fieldname"    => "custommetric<index>",        # Field name in dswb tables
        "lastModified" => <lastModifiedDate>,
        "description"  => "<description>",
        "dataType"     => Dict(
            "decimalPlaces"  => "2",
            "type"           => "<metric type>",
            "currencyCode"   => "<ISO 4217 Currency Code if type==Currency>"
        ),
        "colors"       => [<array of color HEX codes>]
    ),
    ...
)

custom_timers::Dict : A {Dict} of Custom Timer names mapped to database fieldnames with the following structure:

Dict(
    <timer name> => Dict(
        "index"         => <index>,                      # Numeric index
        "fieldname"     => "customtimer<index>",         # Field name in dswb tables
        "mpulseapiname" => "CustomTimer<index>",
        "lastModified"  => <lastModifiedDate>,
        "description"   => "<description>",
        "colors"        => Array(
            Dict(
                "timingType"  => "<seconds | milliseconds>",
                "timingStart" => "<start timer value for this colour range>",
                "timingEnd"   => "<end timer value for this colour range>",
                "colorStart"  => "<start of this color range>",
                "endStart"    => "<end of this color range>"
            ),
            ...
        )
    ),
    ...
)

session_timeout::Int64 : The session timeout value in minutes

resource_timing::Bool : Flag indicating whether resource timing collection is enabled or not

vertical_market::AbstractString : The vertical market that this domain belongs to

Throws

ArgumentError : if token is empty or domainID, appKey and appName are all empty

mPulseAPIException : if API access failed for some reason

Exception : if something unexpected happened while parsing the repository object

source

mPulseAPI.getNodeContent — Method

Gets the content of a node

Arguments

body::{AbstractString|XMLElement|Dict} : This is an object containing the domain XML returned by mPulseAPI.getRepositoryDomain. It may be:

An AbstractString containing the domain XML. This will be parsed.
A LightXML.XMLElement pointing to the root node of the domain XML.
A Dict with a body element. This is the domain object returned by mPulseAPI.getRepositoryDomain.

nodeName::AbstractString : The node whose contents shoudl be returned

default::Any : A default value to return if the required node was not found

Returns

{AbstractString|Number|Boolean} The content of the requested node cast to the same type as default or the value of default if the node was not found

Throws

ArgumentError : if the data type of body is unknown.

LightXML.XMLParseError : if body is an AbstractString but contains invalid XML

source

mPulseAPI.clearTenantCache — Function

Expire an entry from the tenant cache. Use this if the tenant has changed.

Keyword Arguments

tenantID::Int64 : The ID of the tenant to expire.

name::AbstractString : The Tenant name in mPulse. This is got from the mPulse domain configuration dialog.

Returns

true : on success

false : if the entry was not in cache

source

mPulseAPI.clearDomainCache — Function

Expire an entry from the domain cache. Use this if the domain has changed.

Keyword Arguments

domainID::Int64 : The ID of the domain to expire.

appKey::AbstractString : The App Key (formerly known as API key) associated with the domain. This is available from the mPulse domain configuration dialog.

appName::AbstractString : The App name in mPulse. This can be got from the mPulse domain configuration dialog.

Returns

true : on success

false : if the entry was not in cache

source

Alerts & Anomaly Detection

See the page on Alerts & Anomaly Detection Models for more details.

Other Object Types

To interact with other object types, you will need to use the following sparsely documented internal methods:

mPulseAPI.deleteRepositoryObject — Method

Internal convenience function. Deletes an object from the repository.

source

mPulseAPI.getRepositoryObject — Method

Internal convenience function. Fetches an object from the repository and caches it for an hour in the appropriate cache object

Returns a single object if searchKeys are passed in an filterRequired is set to true (default)
Returns an array of objects if searchKeys are not passed in and filterRequired is set to false
Throws an exception if searchKeys are not passed in and filterRequired is set to true

source

mPulseAPI.postRepositoryObject — Method

Internal convenience function. Updates an object from the repository.

source