The Module Config endpoint is used to configure and control the nodes and modules in your cluster. It can be used to query for module configuration, update it, and start/stop the modules in the cluster.
This method will return a complete Smile CDR configuration property file. This is useful for example if you want to export a complete configuration from one environment in order to build another environment.
To invoke:
GET http://localhost:9000/module-config/properties
The server will produce a response resembling the following:
################################################################################
# Master
################################################################################
node.id=Master
################################################################################
# admin_json
################################################################################
module.admin_json.type=ADMIN_JSON
module.admin_json.requires.SECURITY_IN_UP=local_security
module.admin_json.config.cors.origins=*
module.admin_json.config.context_path=/
module.admin_json.config.threadpool.max=10
module.admin_json.config.sessions.timeout.mins=30
module.admin_json.config.threadpool.min=5
module.admin_json.config.sessions.scavenger.interval.millis=60000
module.admin_json.config.port=9000
For brevity only 1 module and a small subset of its configuration are shown but a real response might contain many more.
This method will return the complete configuration for the modules in your cluster. Note that passwords for external systems (e.g. database credentials) will be obscured.
To invoke:
GET http://localhost:9000/module-config/
The server will produce a response resembling the following:
{
"nodes": [
{
"nodeId": "Master",
"modules": [
{
"moduleId": "clustermgr",
"moduleType": "CLUSTER_MGR",
"options": [
{
"key": "kafka.ack_mode"
},
{
"key": "db.driver",
"value": "POSTGRES_9_4"
},
{
"key": "db.url",
"value": "jdbc:postgresql://localhost/cdr"
},
{
"key": "db.username",
"value": "cdr"
}
]
},
{
"moduleId": "local_security",
"moduleType": "SECURITY_IN_LOCAL",
"options": [
{
"key": "seed.username",
"value": "admin"
}
]
},
{
"moduleId": "smart_app_demo_host",
"moduleType": "SMART_APPS_HOST",
"options": [
{
"key": "port",
"value": "19201"
},
{
"key": "respect_forward_headers",
"value": "true"
}
]
}
]
}
]
}
For brevity only 1 module and a small subset of its configuration are shown but a real response might contain many more.
This method will return the complete configuration for a given module. Note that passwords for external systems (e.g. database credentials) will be obscured.
To invoke (substitute a node ID and module ID into the path below):
GET http://localhost:9000/module-config/{node_id}/{module_id}
The server will produce a response resembling the following:
{
"moduleType": "ADMIN_JSON",
"options": [
{
"key": "port",
"value": "19000"
},
{
"key": "respect_forward_headers",
"value": "true"
},
{
"key": "anonymous.access.enabled",
"value": "true"
},
{
"key": "security.http.basic.enabled",
"value": "true"
}
],
"dependencies": [
{
"moduleId": "local_security",
"type": "SECURITY_IN_UP"
}
]
}
Note that only settings which are not set to their default value are included in the response.
This method instantiates a new module.
To invoke (substitute a node ID and module ID into the path below):
POST http://localhost:9000/module-config/{node_id}/{module_id}/create[?start=true]
Content-Type: application/json
start=true to the request URL in order to have the module automatically be started on all running processes for the given node after it is created.This call should include a body such as the following:
{
"moduleType": "ENDPOINT_FHIR_REST_DSTU3",
"options": [
{
"key": "anonymous.access.enabled",
"value": "true"
}
],
"dependencies": [
{
"type": "PERSISTENCE_DSTU3",
"moduleId": "persistence"
},
{
"type": "SECURITY_IN_OIC",
"moduleId": "smart_auth"
},
{
"type": "SECURITY_IN_UP",
"moduleId": "local_security"
}
]
}
In this example, a new module will be created with id {module_id} and the options and dependencies as they were set in the request body.
The module Types that can be created are listed Here.
You can find the applicable options for each module type under the Modules heading.
The server will produce a response resembling the following:
{
"options": [
{
"name": "cors.origins",
"previousValue": "https://example.com",
"newValue": "*"
}
]
}
This method updates configuration for a given module. This can include changing dependencies and updating configuration properties. Any number of dependencies and properties can be changed.
To invoke (substitute a node ID and module ID into the path below):
PUT http://localhost:9000/module-config/{node_id}/{module_id}/set
Content-Type: application/json
restart=true to the request URL in order to have the module automatically be restarted on all running processes for the given node after the configuration has been updated.This call should include a body such as the following:
{
"options": [
{
"key": "cors.origins",
"value": "*"
}
]
}
Each option has two parts:
key is the property key, such as the value security.http.basic.enabled listed here.value is the actual value to setIn this example, a single configuration item is being updated but many could be updated at one time.
The server will produce a response resembling the following:
{
"options": [
{
"key": "cors.origins",
"previousValue": "https://example.com",
"newValue": "*"
}
]
}
This method starts a given module if it isn't already running or in the process of starting (in which case this method has no effect). This operation will trigger a start on all running Node Processes.
To invoke (substitute a node ID and module ID into the path below):
POST http://localhost:9000/module-config/{node_id}/{module_id}/start
The server will produce a response resembling the following:
{
"processes": [
{
"processId": "LongPoint",
"previousStatus": "STOPPED",
"newStatus": "START_REQUESTED"
}
]
}
This method stops a given module if it isn't already stopped or in the process of stopping (in which case this method has no effect). This operation will trigger a stop on all running Node Processes.
To invoke (substitute a node ID and module ID into the path below):
POST http://localhost:9000/module-config/{node_id}/{module_id}/stop
The server will produce a response resembling the following:
{
"processes": [
{
"processId": "LongPoint",
"previousStatus": "STARTED",
"newStatus": "STOP_REQUESTED"
}
]
}
This method restarts a given module if it isn't already in the process of starting or stopping (in which case this method has no effect). This operation will trigger a restart on all running Node Processes.
To invoke (substitute a node ID and module ID into the path below):
POST http://localhost:9000/module-config/{node_id}/{module_id}/restart
The server will produce a response resembling the following:
{
"moduleId": "admin_web",
"previousStatus": "STARTED",
"newStatus": "RESTART_REQUESTED"
}
This method archives a given module. Note that this is a logical delete; the module will be retained in the database because audit logs and other elements may depend on it. It will be marked as "archived", a random string will be appended to its ID, and it will no longer appear in the list of modules.
To invoke (substitute a node ID and module ID into the path below):
DELETE http://localhost:9000/module-config/{node_id}/{module_id}/archive
System restore allows users to reset a given node's configurations to a previous moment in history.
Restore points are automatically created when the new modules are added, existing modules are archived, or module configs are changed in any way.
A restore point is also created whenever the server starts up successfully (ie, no failing modules), provided the configs on start up are different from what they were at the last restore point.
A number of endpoints are exposed in order to allow working with restore points.
GET http://localhost:9000/module-config/{node_id}/restorePoints
Invoking this endpoint will return all known restore points in the system.
The configs themselves will be omitted, but the id, node id, user id (if done by a user) and other metadata will be included.
The following query parameters can optionally be provided:
| Query Parameter | Description |
|---|---|
| version | The version of the server when the restore point was created. If provided, only restore points for this version will be returned. |
| from | A datetime string. If specified, only restore points on or after this point will be returned. |
| to | A datetime string. If specified, only restore points before or on this point will be returned. |
| _offset | Used for paging. Defaulted to 0. If specified, will fetch that page in the search results. |
| _count | Used for paging. Defaulted to 100. If specified, this is the number of restore points that will be returned in the page request. |
Example with all parameters:
GET http://localhost:9000/module-config/{node_id}/restorePoints?version=2024.02.R01&from=2000-12-25T00:00-0500&to=2000-12-31T23:59-05:00
Example output:
{
"pid": 1,
"created": 1699560568674,
"serverVersion": "2024.02.R01",
"node": {
"nodeId": "node_id",
"configLocked": false,
"securityStrict": false,
"serverPortOffset": 0
},
"author": {
"pid": 1,
"nodeId": "node_id",
"moduleId": "local_security",
"username": "HSIMPSON",
"familyName": "Simpson",
"givenName": "Homer",
"systemUser": false,
"accountDisabled": false,
"external": false,
"serviceAccount": false
}
}
Where:
"pid" - the id of the restore point. This id can be used to obtain all the configs at this restore point."created" - the date-time the restore point was created."serverVersion" - the version of the server when this restore point was created."author" - (optional) the information about the user whose actions created this restore point.
If this isn't provided, the restore point was created by the system (on system start, for instance)."node" - information about the node for which this restore point exists.The configs for a given restore point can be obtained with the following endpoint:
GET http://localhost:9000/module-config/{node_id}/restorePoints/{id}
Where node_id is the id of the node that has the restore point and
id is the PID of the restore point itself.
Configs are returned as a JSON object of property keys to config values, as what would be in a server properties file.
The config keys may not be ordered and the values may be escaped or, in the case of passwords and other confidential information, omitted entirely.
Example output:
{
"pid": 2,
"created": 1699560483791,
"serverVersion": "2024.02.R01",
"node": {
"nodeId": "node_id",
"configLocked": false,
"securityStrict": false,
"serverPortOffset": 0
},
"author": {
"pid": 1,
"nodeId": "node_id",
"moduleId": "local_security",
"username": "HSIMPSON",
"familyName": "Simpson",
"givenName": "Homer",
"systemUser": false,
"accountDisabled": false,
"external": false,
"serviceAccount": false
},
"configs": {
"keyValuePairs": {
"config.key": "config_value"
}
}
}
This is the full Restore Point object, consisting of all the metadata that would be available from the /restorePoints endpoint, as well as the configuration settings themselves.
The actual configuration settings themselves will exist as un-ordered key-value pairs. Passwords and other sensitive data will be redacted.
A node can be restored to a previous restore point using the following endpoint:
POST http://localhost:9000/module-config/{node_id}/restorePoints/{id}
Where the "id" value is the id of the restore point and "node_id" is the node's id.
No body params are required for now. But this could change in future versions.
In order to save and reset to restore points, the system's property source must be in "DATABASE" mode.
node.propertysource=DATABASE
Restoring a system will not save or restore password type properties.
This is to prevent leaking of passwords, as well as to maintain a working system. If the system is to be restored to a previous point, it must already be connected to the database. "Restoring" a database password would break this.
Restore points are never removed.
Once a system is restored to a previous restore point, a new restore point will be created as the latest restore point.
All previous restore points, including those after the selected restore point, will continue to exist.
Restoring a system only restores the top-level configuration settings.
This will not restore the contents of files such as callback script files, JWT key-set files, or json file configurations. This will restore the text block versions of these.
Restore points are saved per node.
System restore will restore all modules within a specific node. There is currently no way to restore only a subset of modules. To restore all nodes, restore each node separately.
Restoring a server to a restore point created on a previous version of Smile is allowed, but is not recommended. Doing so may have unintended consequences as configuration settings may have been added, removed, or changed.
Do so at your own risk.
Restoring configuration does not restart any modules. The new (restored) configuration will not take effect until restart of each module, or the whole server.