Developer Platform (December 2024)

Configuration variables

«  Tools   ·  [   home  ·   reference  ·   community   |   search  ·   index   ·  routing table   ·  scopes table   ]   ·  Locales and time zones  »

The configuration variable actions let an organization read the configuration values that direct the operation of a back-end learning service.

Attributes

CVSCOPE_T

Possible values to describe configuration variable scope (that is, the org units and users affected by the variable’s value) and the way you can edit the variable (formerly known as the “type” of a configuration variable).

Value

Applies to…

System

the instance, including all orgs

Org

the org, and all descendant org units

OrgUnit

an org unit

Role

a role, independent of user enrollment

User

a user independent of enrollment

UserOrgUnit

a user enrolled within an org unit context
CVTYPE_T

Possible values to describe configuration variable value type, and the way you can expect to provide and receive these values through the API.

Value

Notes

bit

 

float

JSON number of the form 10.2

string

 

int

JSON number of the form 10

xml

 

enum

Listed in the AllowedValues property for a variable
ConfigVariable.Definition

When you make a query about a configuration variable’s definition, the service provides a JSON block like this:

{
    "ConfigId": <string:GUID>,
    "Name": <string>,
    "Scope": <string:CVSCOPE_T>,
    "Description": <string>,
    "DataType": <string:CVTYPE_T>,
    "DefaultValue": <string>,
    "CanEditSystemValue": <boolean>,
    "CanEditOverrideValues": <boolean>,
    "IsSensitiveData": <boolean>,
    "AllowedValues": null|[
        { "Value": <string> },
        { "Value": <string> }, ...
    ]
}
AllowedValues

Null for any configuration variable other than those of type enum. For enum types, this property contains an array of the allowed values the variable can contain.

IsSensitiveData

If true, the value will be obfuscated when stored in the database, and the value will not be directly visible through the learning service’s user interface, or through the Brightspace APIs.

For example, this means that you will not be able to read back password values through the API once they’re set: sensitive data values should come back as empty strings when fetched through the APIs.

CanEditSystemValue and CanEditOverrideValues

Org Admin users will never have CanEditSystemValue, but may have CanEditOverrideValues, depending on the variable in question.

Installation Admin users will always have identical values for these two properties, the value depending on the variable in question.

ConfigVariable.Values

When you make a query about a configuration variable’s current value state, the service provides a JSON block like this:

{
    "ConfigId": <string:GUID>,
    "DefaultValue": <string>,
    "SystemValue": <string>|null,
    "OrgValue": <string>|null,
    "NumOrgUnitValues": <number>,
    "NumRoleValues": <number>
}
DefaultValue

The non-modifiable value for the configuration variable provided when the instance gets created. If no other value gets provided for the configuration variable at another scope, this value gets applied.

SystemValue and OrgValue

The SystemValue is the value for the configuration variable that applies to all orgs residing in that learning service instance. This overrides the DefaultValue, if set.

The OrgValue is the value for the configuration variable that applies to a single org residing in the instance. This overrides the SystemValue, if set.

If either of these properties is null, it’s an indication that the value applied at that level comes from the next level up that has a value. Thus, if SystemValue is null, the value applied will come from the DefaultValue property; if the OrgValue is null, the value applied will come from the SystemValue property (if not null), or the DefaultValue property (if the SystemValue property is null).

Note

Note that “” (the empty string) is a valid value and different from null; if one of these properties has the value “”, then that value gets applied, and not the value assigned to the next level up.

ConfigVariable.ConfigSystemValue

Describes the configuration variable assigned for the system instance.

{
    "SystemValue": <string>|null
}
ConfigVariable.ConfigOrgValue

Describes the configuration variable assigned for an org inside the system instance.

{
    "OrgValue": <string>|null
}
ConfigVariable.OrgUnitValue

Describes the configuration variable value assigned for a particular org unit.

{
    "OrgUnitId": <number:D2LID>,
    "Value": <string>|null
}
ConfigVariable.SpecifiedOrgUnitValue

When you must provide a new value for a configuration value assigned for a particular org unit, you provide a structure like this one:

{
    "OrgUnitValue": <string>|null
}
ConfigVariable.RoleValue

Describes the configuration variable value assigned for a particular role.

{
    "RoleId": <number:D2LID>,
    "Value": <string>|null
}
ConfigVariable.SpecifiedRoleValue

When you must provide a new value for a configuration value assigned for a particular role, you provide a structure like this one:

{
    "RoleValue": <string>|null
}
ConfigVariable.ResolverValue

Describes the strategy the service will use to resolve the value of a configuration variable.

{
   "ouTypeSequence": [ <number:D2LID>, ... ]
}
ouTypeSequence

Array of OrgUnitType identifiers. This array may not contain any duplicates, and may not contain more than five elements.

Actions

Configuration variable API actions belong to three groups:

Definitions

GET /d2l/api/lp/(version)/configVariables/definitions/

Retrieve the definitions for all the configuration variables the user has access to view.

Parameters:
Query Parameters:

  • search (string) – Optional. Case-insensitive search string to match against the full Name of a configuration variable.

  • bookmark (string) – Optional. Bookmark to use for fetching next data set segment.

Status Codes:
API Versions:

  • 1.43+ – Route first appears in LMS v20.23.5.

  • 1.35-1.42 – Deprecated as of LMS v20.24.1.

  • 1.34- – Obsolete as of LMS v20.24.1.

Input. You can use a bookmark query parameter as a paging offset, to indicate that the service should return the segment of results immediately following your bookmark.

You can use a search query parameter to filter the result set to those configuration variables with a Name property that contains your search string.

Return. This action returns a paged result set containing the resulting Definition data blocks for the segment following your bookmark parameter (or the first segment, if the parameter is empty or missing).

Note

This action employs the configuration variable’s ConfigId property enclosed within the Definition block as the paging control value. You can fetch the segment of results following any configuration variable’s entry in the entire data set by passing that variable’s ConfigId as the bookmark value.

GET /d2l/api/lp/(version)/configVariables/(variableId)/definition

Retrieve the definitions for a configuration variable.

Parameters:

  • version (D2LVERSION) – API version.

  • variableId (GUID) – Configuration variable ID.

Status Codes:
API Versions:

  • 1.43+ – Route first appears in LMS v20.23.5.

  • 1.35-1.42 – Deprecated as of LMS v20.24.1.

  • 1.34- – Obsolete as of LMS v20.24.1.

Return. This action returns a Definition JSON block, containing the definition of the provided configuration variable.

Values

GET /d2l/api/lp/(version)/configVariables/(variableId)/values

Retrieve the value summary for a configuration variable.

Parameters:

  • version (D2LVERSION) – API version.

  • variableId (GUID) – Configuration variable ID.

Status Codes:
API Versions:

  • 1.43+ – Route first appears in LMS v20.23.5.

  • 1.35-1.42 – Deprecated as of LMS v20.24.1.

  • 1.34- – Obsolete as of LMS v20.24.1.

Return. This action returns a Values JSON block, containing the current value state for the provided configuration variable.

GET /d2l/api/lp/(version)/configVariables/(variableId)/values/org

Retrieve the current org value for a configuration variable.

Parameters:

  • version (D2LVERSION) – API version.

  • variableId (GUID) – Configuration variable ID.

Status Codes:
API Versions:

  • 1.43+ – Route first appears in LMS v20.23.5.

  • 1.35-1.42 – Deprecated as of LMS v20.24.1.

  • 1.34- – Obsolete as of LMS v20.24.1.

Return. This action returns a OrgValue JSON block, containing the current org value for the provided configuration variable.

GET /d2l/api/lp/(version)/configVariables/(variableId)/values/orgUnits/

Retrieve all the org unit override values for a configuration variable.

Parameters:

  • version (D2LVERSION) – API version.

  • variableId (GUID) – Configuration variable ID.

Query Parameters:

  • bookmark (string) – Optional. Bookmark to use for fetching next data set segment.

Status Codes:
API Versions:

  • 1.43+ – Route first appears in LMS v20.23.5.

  • 1.35-1.42 – Deprecated as of LMS v20.24.1.

  • 1.34- – Obsolete as of LMS v20.24.1.

Input. You can use a bookmark query parameter as a paging offset, to indicate that the service should return the segment of results immediately following your bookmark.

Return. This action returns a paged result set containing the resulting OrgUnitValue data blocks for the segment following your bookmark parameter (or the first segment, if the parameter is empty or missing).

Note

This action employs the OrgUnitId property enclosed within the OrgUnitValue block as the paging control value. You can fetch the segment of results following any org unit’s entry in the entire data set by passing that value’s OrgUnitId property as the bookmark value.

GET /d2l/api/lp/(version)/configVariables/(variableId)/values/orgUnits/(orgUnitId)

Retrieve an org unit override value for a configuration variable.

Parameters:

  • version (D2LVERSION) – API version.

  • variableId (GUID) – Configuration variable ID.

  • orgUnitId (D2LID) – Org unit ID.

Status Codes:
API Versions:

  • 1.43+ – Route first appears in LMS v20.23.5.

  • 1.35-1.42 – Deprecated as of LMS v20.24.1.

  • 1.34- – Obsolete as of LMS v20.24.1.

Return. This action returns an OrgUnitValue JSON block, containing an org unit override value for the provided configuration variable.

GET /d2l/api/lp/(version)/configVariables/(variableId)/effectiveValues/orgUnits/(orgUnitId)

Retrieve the effective value for a configuration variable within an org unit.

Parameters:

  • version (D2LVERSION) – API version.

  • variableId (GUID) – Configuration variable ID.

  • orgUnitId (D2LID) – Org unit ID.

Status Codes:
API Versions:

  • unstable – Route first appears in LMS v10.5.5.

Return. This action returns an OrgUnitValue JSON block, containing an org unit effective value for the provided configuration variable. Effective value takes into account that when the value is not set at the OrgUnit level, then it checks the Org level, and then the System level. It also takes into account the Resolver resolution strategy if applicable.

GET /d2l/api/lp/(version)/configVariables/(variableId)/values/roles/

Retrieve all the role override values for a configuration variable.

Parameters:

  • version (D2LVERSION) – API version.

  • variableId (GUID) – Configuration variable ID.

Query Parameters:

  • bookmark (string) – Optional. Bookmark to use for fetching next data set segment.

Status Codes:
API Versions:

  • 1.43+ – Route first appears in LMS v20.23.5.

  • 1.35-1.42 – Deprecated as of LMS v20.24.1.

  • 1.34- – Obsolete as of LMS v20.24.1.

Input. You can use a bookmark query parameter as a paging offset, to indicate that the service should return the segment of results immediately following your bookmark.

Return. This action returns a paged result set containing the resulting RoleValue data blocks for the segment following your bookmark parameter (or the first segment, if the parameter is empty or missing).

Note

This action employs the RoleId property enclosed within the RoleValue block as the paging control value. You can fetch the segment of results following any role’s entry in the entire data set by passing that value’s RoleId property as the bookmark value.

GET /d2l/api/lp/(version)/configVariables/(variableId)/values/roles/(roleId)

Retrieve a role override value for a configuration variable.

Parameters:

  • version (D2LVERSION) – API version.

  • variableId (GUID) – Configuration variable ID.

  • roleId (D2LID) – Role ID.

Status Codes:
API Versions:

  • 1.43+ – Route first appears in LMS v20.23.5.

  • 1.35-1.42 – Deprecated as of LMS v20.24.1.

  • 1.34- – Obsolete as of LMS v20.24.1.

Return. This action returns a RoleValue JSON block, containing a role override value for the provided configuration variable.

GET /d2l/api/lp/(version)/configVariables/(variableId)/values/system

Retrieve the current system value for a configuration variable.

Parameters:

  • version (D2LVERSION) – API version.

  • variableId (GUID) – Configuration variable ID.

Status Codes:
API Versions:

  • 1.43+ – Route first appears in LMS v20.23.5.

  • 1.35-1.42 – Deprecated as of LMS v20.24.1.

  • 1.34- – Obsolete as of LMS v20.24.1.

Return. This action returns a SystemValue JSON block, containing the current system value for the provided configuration variable.

PUT /d2l/api/lp/(version)/configVariables/(variableId)/values/org

Set a new org value for a configuration variable.

Parameters:

  • version (D2LVERSION) – API version.

  • variableId (GUID) – Configuration variable ID.

JSON Parameters:
Status Codes:
API Versions:

  • 1.43+ – Route first appears in LMS v20.23.5.

  • 1.35-1.42 – Deprecated as of LMS v20.24.1.

  • 1.34- – Obsolete as of LMS v20.24.1.

Input. The new org value will now override the variable’s system value.

PUT /d2l/api/lp/(version)/configVariables/(variableId)/values/orgUnits/(orgUnitId)

Set a new org unit override value for a configuration variable.

Parameters:

  • version (D2LVERSION) – API version.

  • variableId (GUID) – Configuration variable ID.

  • orgUnitId (D2LID) – Org unit ID.

JSON Parameters:
Status Codes:
API Versions:

  • 1.43+ – Route first appears in LMS v20.23.5.

  • 1.35-1.42 – Deprecated as of LMS v20.24.1.

  • 1.34- – Obsolete as of LMS v20.24.1.

PUT /d2l/api/lp/(version)/configVariables/(variableId)/values/roles/(roleId)

Set a new role override value for a configuration variable.

Parameters:

  • version (D2LVERSION) – API version.

  • variableId (GUID) – Configuration variable ID.

  • roleId (D2LID) – Role ID.

JSON Parameters:
Status Codes:
API Versions:

  • 1.43+ – Route first appears in LMS v20.23.5.

  • 1.35-1.42 – Deprecated as of LMS v20.24.1.

  • 1.34- – Obsolete as of LMS v20.24.1.

PUT /d2l/api/lp/(version)/configVariables/(variableId)/values/system

Set a new system value for a configuration variable.

Parameters:

  • version (D2LVERSION) – API version.

  • variableId (GUID) – Configuration variable ID.

JSON Parameters:
Status Codes:
API Versions:

  • 1.43+ – Route first appears in LMS v20.23.5.

  • 1.35-1.42 – Deprecated as of LMS v20.24.1.

  • 1.34- – Obsolete as of LMS v20.24.1.

Input. The new system value will now override the variable’s default value.

Resolver

To resolve the value for an org unit configuration variable, the back-end service uses the first value found in these locations, tested in order:

  1. The current org unit itself.

  2. In order, for each org unit type in the org unit’s ResolverValue.ouTypeSequence property array: walk up the ancestor chain of the current org unit, considering only ancestors that match that type.

  3. The current org.

  4. The system.

DELETE /d2l/api/lp/(version)/configVariables/(variableId)/resolver

Restore the default resolution strategy for an org unit configuration variable.

Parameters:

  • version (D2LVERSION) – API version.

  • variableId (GUID) – Configuration variable ID.

Status Codes:
API Versions:

  • unstable – Route first appears in LMS v10.4.12.

GET /d2l/api/lp/(version)/configVariables/(variableId)/resolver

Retrieve the resolution strategy for an org unit configuration variable.

Parameters:

  • version (D2LVERSION) – API version.

  • variableId (GUID) – Configuration variable ID.

Status Codes:
API Versions:

  • unstable – Route first appears in LMS v10.4.12.

Returns. This action returns a ResolverValue JSON block.

PUT /d2l/api/lp/(version)/configVariables/(variableId)/resolver

Update the resolution strategy for an org unit configuration variable.

Parameters:

  • version (D2LVERSION) – API version.

  • variableId (GUID) – Configuration variable ID.

JSON Parameters:
Status Codes:
API Versions:

  • unstable – Route first appears in LMS v10.4.12.

Input. Note that the provided ResolverValue JSON block replaces the configuration variable’s resolver strategy.

«  Tools   ·  [   home  ·   reference  ·   community   |   search  ·   index   ·  routing table   ·  scopes table   ]   ·  Locales and time zones  »