Configuration Administration Integration Guide#

The Configuration Administration API provides endpoints for creating, retrieving, and managing the code and configuration of distributed components in Argus.

The API uses role based access control so any interaction will be limited by the requesting user’s role(s).

Please read the General integration guide to learn the general concepts and common data structures used throughout the Argus API.

Tip

The Swagger API documentation is always up-to-date and lets you try out any query with your user session or an API-key.

Introduction#

The configuration administration service manages the following concepts:

Code Artifact

A jar-file with Java code, which is downloadable by remote agents.

Code Profile

A bundle of code artifacts, together making out a code base for a Java ClassLoader.

Configuration Template

A template configuration for a component container, containing a code profile, a Spring/Guice configuration, and default properties.

Configuration Host

Representing a distributed host where code is run.

Configuration Instance

An instance of a component container, which runs a specific Template on a Host.

Property Mapper

A set of event normalization rules which are downloaded by remote agents. Which Property Mapper set is downloaded is configured in the remote agent config.

Configurations and Code are not intended to be used by end users, and is therefore not covered in this integration guide.

Property Mappers#

Property Mapper Configuration#

A property mapper transforms/normalises raw agent data as per its configuration.

All interactions the Property Mapper API use the base URL: https://api.mnemonic.no/configurationadmin/v1/propertymapper

The permissions relevant to Property Mapper Configuration management are:

  • addPropertyMapping

  • viewPropertyMapping

  • updatePropertyMapping

  • restorePropertyMapping

  • rollbackPropertyMapping

  • deletePropertyMapping

Create a Property Mapper#

To create a property mapper configuration submit a PropertyMapperAddRequest to the base URL.

A successful attempt requires that the JSON configuration object is valid, the user has the appropriate permission(s), and the property mapper’s shortName is unique:

curl -X POST "https://api.mnemonic.no/configurationadmin/v1/propertymapper" -H "Argus-API-Key: my/api/key" -H "accept: application/json" -H "Content-Type: application/json, " 
-d '{ 
  "name": "string", 
  "shortName": "string", 
  "configuration": "[
    { \"type\": \"set\", \"ifProp\": \"prop1\", \"ifPropBlank\": true, \"to\": \"prop1\", \"value\": \"value\" }
  ]", 
  "description": "string"
}'

Validation of the configuration during create and update is performed on several levels:

  • It must be valid JSON

  • The rule types must be one of move, copy, set, remove, extract, concat, intLookup, setFlag, timestamp, jsonFlatMap

  • The rule definitions and values must be valid as per the respective rule types

Note

ShortName

Property mapper shortNames must be unique between different collections of property mappers but NOT between versions of the same property mapper. Retrieving by shortname, unless a version is specified, will always return the primary version of the property mapper. Currently updating shortNames is not permitted.

Get a Property Mapper#

To fetch a single property mapper configuration append the property mapper’s id or shortname to the base URL:

curl -X GET -H "Argus-API-Key: my/api/key"
https://api.mnemonic.no/configurationadmin/v1/propertymapper/{idOrShortName}?includeConfig={true|false}

Get a Property Mapper’s Versions#

It is possible to retrieve a property mapper without the JSON configuration by using the includeConfig parameter. By default the API returns the configuration.

As new versions of a property mapper are created a user might wish to retrieve a specific version. To fetch the list of all versions of a particular property mapper, add the id of any version of that particular property mapper configuration or the property mapper’s unique shortname to the base URL, and append the base revision path:

curl -X GET -H "Argus-API-Key: my/api/key" https://api.mnemonic.no/configurationadmin/v1/propertymapper/{idOrShortName}/revisions

The list will contain a simplified view of the property mappers.

Get a Specific Property Mapper Version#

To view a specific version of a property mapper, append the version number you wish to retrieve to the same request:

curl -X GET -H "Argus-API-Key: my/api/key"
https://api.mnemonic.no/configurationadmin/v1/propertymapper/{idOrShortName}/revisions/{versionNumber}?includeConfig={true|false}

Like the base get endpoint, when retrieveing a specific version you can decide whether to include the JSON configuration in the response. By default the API returns the configuration.

Search for Property Mappers#

There are two property mapper configuration search endpoints; one for basic listing and one for advanced search.

The list endpoint allows a user to request property mappers filtered by specific query parameters, which include:

  • keywords

  • idOrShortName

  • creation/update/deletion timestamp ranges

  • creation/update/deletion user ids

  • whether to include deleted property mappers

The results can also be sorted, limited, and paginated with the appropriate query parameters. Please refer to the Swagger documentation for more detailed information.

curl -X GET -H "Argus-API-Key: my/api/key"
https://api.mnemonic.no/configurationadmin/v1/propertymapper&idOrShortName=x&includeDeleted=true&includeConfig={true|false}

The search endpoint provides similar functionality as the list one but is a POST endpoint and thus expects a PropertyMapperSearchRequest object as the payload.

curl -X POST -H "Argus-API-Key: my/api/key"
https://api.mnemonic.no/configurationadmin/v1/propertymapper/search?includeConfig={true|false}

Both endpoints accept the same includeConfig query parameter as the individual GET property mapper endpoints. Unlike those endpoints the default behaviour is, however, false.

Note

Search results

Both the list and search endpoints will only ever return primary versions of property mappers that match the provided criteria

Update a Property Mapper#

To update a property mapper, submit an UpdatePropertyMapperRequest via PUT to the base URL with the id or shortname of the property mapper appended to the base URL:

curl -X PUT -H "Argus-API-Key: my/api/key" https://api.mnemonic.no/configurationadmin/v1/propertymapper/{idOrShortName} 
-d '{
  "name": "string", 
  "configuration": "[
    { \"type\": \"set\", \"ifProp\": \"prop1\", \"ifPropBlank\": true, \"to\": \"prop1\", \"value\": \"value\" }
  ]", 
  "description": "string"
}'

Currently, it is only possible to modify a property mapper’s

  • name

  • description

  • JSON configuration

To be eligible for update, the property mapper must be the current primary i.e. not controlled version property mapper. Updating a deleted property mapper is also not permitted. It must first be restored before updating.

Rollback a Property Mapper#

To rollback a property mapper to a specific previous version, submit a rollback request to the path of the revision to which we want to rollback:

curl -X PUT -H "Argus-API-Key: my/api/key" https://api.mnemonic.no/configurationadmin/v1/propertymapper/{idOrShortName}/revisions/{versionNumber}/rollback

To be an eligible target for a rollback, the property mapper can neither be a primary nor deleted property mapper.

Delete a Property Mapper#

To delete a property mapper, submit a DELETE request to the base URL with the id or shortname of the property mapper appended to the base URL:

curl -X DELETE -H "Argus-API-Key: my/api/key" 
https://api.mnemonic.no/configurationadmin/v1/propertymapper/{idOrShortName}

To be eligible for deletion, the property mapper must be the current primary and not already deleted.

Restore a Property Mapper#

To restore a deleted property mapper, submit an empty PUT request to the restore endpoint:

curl -X PUT -H "Argus-API-Key: my/api/key" 
https://api.mnemonic.no/configurationadmin/v1/propertymapper/{idOrShortName}/restore

To be eligible for restoration, the property mapper must be the current primary and actually already be flagged as deleted.

Note

Version Control

All update, rollback, delete, and restore operations generate a new revision of the affected property mapper. The primary property mapper at the time of the request is flagged as a controlled version and a new primary property mapper is created as per the instructions in the respective requests. The previous property mapper points to the new one.