The Configuration Administration API provides endpoints for creating, retrieveing, and managing configurations.
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.
Detailed API documentation
The Swagger API documentation is always up-to-date and lets you try out any query with your user session or an API-key.
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. |
May override code profile and configuration properties.
|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 Mapper Configuration
A property mapper transforms/normalises raw agent data as per its configuration.
All interactions the Property Mapper API use the base URL:
The permissions relevant to Property Mapper Configuration management are:
Create a Property Mapper
To create a property mapper configuration submit a PropertyMapperAddRequest to the base URL.
A succesful attempt requires that the JSON configuration object is valid, the user has the appropriate permission(s), and the property mapper's shortName is unique:
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
Get a Property Mapper
To fetch a single property mapper configuration append the property mapper's id or shortname to the base URL:
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:
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:
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:
- 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.
The search endpoint provides similar functionality as the list one but is a POST endpoint and thus expects a PropertyMapperSearchRequest object as the payload.
Both endpoints accept the same includeConfig query parameter as the individual GET property mapper endpoints. Unlike those endpoints the default behaviour is, however, false.
NB: Both the list and search endpoints will only ever return primary versions of property mappers that match the provided critera
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:
Currently it is only possible to modify a property mapper's
- 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:
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:
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:
To be eligible for restoration, the property mapper must be the current primary and actually already be flagged as deleted.
NB: 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.
- No labels