Config Management

Use the Config Management REST API to manage Meridian configurations. Changes take effect immediately.

GETs (reading data)

Config Management API GET functions
Resource Description

/cm/{configName}

Returns a list of configIds in JSON/YAML format, (for example, ["config1", "config2"]).
200: Return: String Array
400: Return: {"MESSAGE": "<ERROR_MESSAGE>"}

/cm/schema/{configName}

Returns OpenAPI schema (for Swagger UI) in JSON/YAML format.
200: Return: OpenAPI schema
400: Return: {"MESSAGE": "<ERROR_MESSAGE>"}

/cm/{configName}/{configId}

Returns configuration in JSON/YAML format.
200: Return: Config Bean
400: Return: {"MESSAGE": "<ERROR_MESSAGE>"}

/cm/{configName}/{configId}/{path}

Returns a part of the configuration specified by configName, configId, and the path to the part in JSONPath format. Returns 404 when the configuration does not exist. Returns 400 when the path parameter has a wrong format or specifies a nonexistent path.
200 Return: part of the configuration
404 Return: {"MESSAGE": "<ERROR_MESSAGE>"}
400 Return: {"MESSAGE": "<ERROR_MESSAGE>"}

POSTs (adding data)

Config Management API POST functions
Resource Description

/cm/{configName}/{configId}

Add new configuration. If the same configuration exists, it will return an error.
200: Return nothing
400: Return: {"MESSAGE": "<ERROR_MESSAGE>"}

/cm/{configName}/{configId}/{path}

Adds an array element to the configuration part specified by configName, configId, and the path to the part in JSONPath format. Returns 404 when the configuration does not exist. Returns 400 when the path parameter has a wrong format, specifies a nonexistent path, or the provided part of the configuration has a wrong format.
200 Return: nothing
404 Return: {"MESSAGE": "<ERROR_MESSAGE>"}
400 Return: {"MESSAGE": "<ERROR_MESSAGE>"}

PUTs (modifying data)

Config Management API PUT functions
Resource Description

/cm/{configName}/{configId}

Update configuration. If configuration does not exist, it will return error.
200: Return: nothing
400: Return: {"MESSAGE": "<ERROR_MESSAGE>"}

/cm/{configName}/{configId}/{path}

Updates a part of the configuration specified by configName, configId, and the path to the part in JSONPath format. Returns 404 when the configuration does not exist. Returns 400 when the path parameter has a wrong format, specifies a nonexistent path, or the provided part of the configuration has a wrong format.
200 Return: nothing
404 Return: {"MESSAGE": "<ERROR_MESSAGE>"}
400 Return: {"MESSAGE": "<ERROR_MESSAGE>"}

/cm/{configName}/{configId}/{pathToParent}/{nodeName}

Updates or inserts a part of the configuration specified by configName, configId, and the path to the parent node in JSONPath format with the node name. Returns 404 when the configuration does not exist. Returns 400 when the pathToParent parameter has a wrong format, specifies a nonexistent path, or the provided part of the configuration has a wrong format.
200 Return: nothing
404 Return: {"MESSAGE": "<ERROR_MESSAGE>"}
400 Return: {"MESSAGE": "<ERROR_MESSAGE>"}

Examples

The following example payload multiplies each thread pool size by a factor of 10 and empties the external requisitions list of entries (if any exist):

{
    "rescanThreads": 100,
    "requistion-dir": "/opt/opennms/etc/imports",
    "importThreads": 80,
    "scanThreads": 100,
    "writeThreads": 80,
    "foreign-source-dir": "/opt/opennms/etc/foreign-sources",
    "requisition-def": []
}
Do not change the requisition-dir and foreign-source-dir elements unless OpenNMS support tells you to do so.

You can also target a single element using a cURL command:

curl -X PUT -u 'admin:admin' https://opennms.example.com/opennms/rest/cm/provisiond/default -H 'Content-type: application/json' --data '{ "rescanThreads": 150 }'

Scheduled requisition imports

Each entry in the requisition-def array may carry a cron-schedule value that tells Provisiond when to pull and import that requisition. The value is parsed as a Quartz CronTrigger expression, not a standard Unix crontab expression.

  • The expression has six required fields (seconds minutes hours day-of-month month day-of-week) and an optional seventh year field, instead of the five Unix crontab(5) fields.

  • Either day-of-month or day-of-week must be ? — the two cannot both be specific values in the same expression.

  • Provisiond’s scheduler does not back-fill missed fires. If Meridian is down when a scheduled import would have run, the run is skipped and the next scheduled run picks up normally.

Example expressions:

0 0 0 * * ?       # every day at midnight
0 0/30 * * * ?    # every 30 minutes
0 0 2 ? * MON     # 02:00 every Monday

See the Quartz CronTrigger tutorial for the full grammar, including the L, W, and # modifiers.

Example cURL command that PUTs a single weekly-scheduled requisition definition:

curl -X PUT -u 'admin:admin' https://opennms.example.com/opennms/rest/cm/provisiond/default -H 'Content-type: application/json' --data '{ "requisition-def": [ { "import-name": "weekly-inventory", "import-url-resource": "requisition://customer1", "cron-schedule": "0 0 2 ? * MON" } ] }'

DELETEs (removing data)

Config Management API DELETE functions
Resource Description

/cm/{configName}/{configId}

Delete configuration.
200: Return nothing
400: Return: {"MESSAGE": "<ERROR_MESSAGE>"}

/cm/{configName}/{configId}/{path}

Deletes a part of the configuration specified by configName, configId, and the path to the part in JSONPath format. Returns 404 when the configuration does not exist. Returns 400 when the path parameter has a wrong format, specifies a nonexistent path, or the provided part of the configuration has a wrong format.
200 Return: nothing
404 Return: {"MESSAGE": "<ERROR_MESSAGE>"}
400 Return: {"MESSAGE": "<ERROR_MESSAGE>"}