43.6.1Module Config Endpoint

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.

43.6.2Fetch Config: Module Property File

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.

43.6.3Fetch Config: All Modules

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.

43.6.4Fetch Config: Single Module

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.

43.6.5Create Module

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

43.6.5.1Parameters

• start – (optional) You can add the parameter 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.

43.6.5.2Request Body

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.

43.6.5.3Response

The server will produce a response resembling the following:

{
  "options": [
    {
      "name": "cors.origins",
      "previousValue": "https://example.com",
      "newValue": "*"
    }
  ]
}

43.6.6Set Module Config

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

43.6.6.1Parameters

• restart – (optional) You can add the parameter 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.

43.6.6.2Request Body

This call should include a body such as the following:

{
  "options": [
    {
      "key": "cors.origins",
      "value": "*"
    }
  ]
}

Each option has two parts:

• The key is the property key, such as the value security.http.basic.enabled listed here.
• The value is the actual value to set

In this example, a single configuration item is being updated but many could be updated at one time.

43.6.6.3Response

The server will produce a response resembling the following:

{
  "options": [
    {
      "key": "cors.origins",
      "previousValue": "https://example.com",
      "newValue": "*"
    }
  ]
}

43.6.7Start Module

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"
    }
  ]
}

43.6.8Stop Module

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"
    }
  ]
}

43.6.9Restart Module

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"
}

43.6.10Archive Module

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" 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

43.6.11Reinstate Module

This method reinstates a given module if it is archived. Once reinstated, the module will be in a "STOPPED" status.

To invoke (substitute a node ID and module ID into the path below):

POST http://localhost:9000/module-config/{node_id}/{module_id}/reinstate

43.6.12System Restore

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.

43.6.12.1Fetching 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:

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.

43.6.12.2Get Configs for a Specific Restore Point

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.

43.6.12.3Restoring to an Existing Restore Point

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.

43.6.12.4System Restore Limitations

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.