API Configuration

For situations in which a static configuration file determining behavior application-wide isn't the best approach, most of Engine's settings can be configured through the REST API. This has two simultaneous benefits:

1. Your application can dynamically configure Engine's behavior on the fly
2. Those settings can be scoped to only affect certain tenants, courses, or registrations

Here's an example: One of the Engine's most commonly configured settings is PlayerScoLaunchType. This setting is used to determine whether Engine should, on course launch, open the course content in a new window or open the content within an iframe on the player page. The appropriate value for this setting is highly dependent on the context in which Engine's player is being launched, and as such can be different for every customer.

If an Engine user has one client (whose tenant name is "client-4623") that insists that their courses should launch in a new window, then the behavior for that single tenant can be addressed without changing the behavior for every other client. To do this, the you would just need to make a PUT request to Engine's API.

Here are the URLs used to specify setting values at various levels:

• tenant: /{tenant}/configuration/{setting name}
• course: /{tenant}/courses/{course ID}/configuration/{setting name}
• registration: /{tenant}/registrations/{registration ID}/configuration/{setting name}

In each case, the body of the PUT request is a JSON object: {"value":"setting value"}

In our example above, the PUT request needed would be to /client-4623/configuration/PlayerLaunchType with a body of { "value": "NEW_WINDOW" }.

The API also allows for the ability to set multiple settings with a single request. For this, you would need to POST a JSON object that contains an array of all the setting names and respective values to the appropriate /configuration subresource. The body of the request should follow the format below:

{
    "settings": [
        { "settingId": "setting #1 name", "value": "setting #1 value" },
        { "settingId": "setting #2 name", "value": "setting #2 value" }
    ]
}

System Configuration

You are not limited to configuring tenant-level settings and above through Engine's API. You can also modify system-wide settings by setting up a special tenant name to serve as a placeholder for system-level configurations.

To do this, add an entry to your Engine config file for a setting called ApiConfigurationSystemTenantName (a common value of this setting is something like "system", but you can use whatever name works for your team). Once you've done that, you can set system-level settings by making requests to the /{tenant}/configuration/ endpoint and specifying this system tenant as the tenant name. When the tenant name in the URL matches the value you've specified with ApiConfigurationSystemTenantName, Engine will scope the configuration across the entire instance.

A common use of this functionality is for configuring any settings that might have sensitive values, like auth credentials or encryption secrets. Configuring these kinds of values through the API lets you keep your data in a secure location, rather than sitting in a plaintext config file on your server. If you're interested in that functionality, please refer to the section on security settings for more information about storing hashed or encrypted versions of these sensitive values.