# Variables
# GET Retrieve a Variable Definition
# /definitions/Variables
# Description
Retrieves the list of latest (based on version number) variable definitions. The result can be filtered by providing the filter parameter. The result can be limited by providing the limit parameter (default is 100). Deleted definitions can be included by setting the includeDeleted parameter to true.
# Parameters
| Name | Located in | Description | Required | Schema |
|---|---|---|---|---|
| limit | query | Limit the number of returned values. Defaults to 100 if not specified | No | LimitClause |
| includeDeleted | query | Whether to return a definition that has been marked as deleted | No | - |
| filter | query | A boolean expression used to filter the results | No | WhereClause |
# Responses
| Code | Description | Schema |
|---|---|---|
| 200 | Success | VariableDefinitions |
| 400 | Invalid request. Response will contain details about all encountered validation errors - i.e. request payload too large, malformed JSON, etc | ServiceErrors |
| 404 | Not found. One or more resources were not found, response may contain details about missing resources | ServiceErrors |
| 5XX | Service error. Service has encountered one or more unexpected conditions that prevented it from fulfilling the request, which may or may not be temporary. Response will contain more details about these errors | ServiceErrors |
# POST Add a New Variable Definition
# /definitions/variables
# Description
Establishes a new variable definition with a basic dataType. Either it must be a brand-new variableDefinitionId or the version property provided must follow the definitions' semantic versioning criteria. The request will not be accepted in any other case. Keep in mind that the definition has not been updated. A major version increase is necessary if adjustments are needed. This endpoint therefore does not support PUT operations.
# Payloads
{
"variableDefinitionId": "scales",
"version": "1.0.0",
"dataType": "integer"
}
{
"variableDefinitionId": "pollingType",
"version": "1.0.0",
"dataType": "string"
"enum": ["fast", "furious"]
}
On the Top level of the definition there are only tree properties allowed:
variableDefinitionId- string - mandatoryversion- string - semantic verion format - mandatorydataType- primitive dataTypes
Only primitive dataTypes are supported for variable definitions.
# Responses
| Code | Description | Schema |
|---|---|---|
| 201 | Definition was added to database | VariableDefinition |
| 400 | Invalid request. Response will contain details about all encountered validation errors - i.e. request payload too large, malformed JSON, etc | ServiceErrors |
| 409 | Conflict - definition with this id already exists | |
| 5XX | Service error. Service has encountered one or more unexpected conditions that prevented it from fulfilling the request, which may or may not be temporary. Response will contain more details about these errors | ServiceErrors |
# GET Retrieve a Variable Definition
# /definitions/variables/{variableDefinitionId}
# Description
Gets latest (based on its version) variable definition based on versions for specific variableDefinitionId. Deleted variable definition can also be retrieved by this operation, if the includeDeleted flag is set to true.
# Parameters
| Name | Located in | Description | Required | Schema |
|---|---|---|---|---|
| variableDefinitionId | path | definition id | Yes | string |
| includeDeleted | query | Whether to return a definition that has been marked as deleted | No | - |
# Responses
| Code | Description | Schema |
|---|---|---|
| 200 | Success. Retrieve object models by filter criteria. | VariableDefinition |
| 404 | Not found. One or more resources were not found, response may contain details about missing resources | ServiceErrors |
| 5XX | Service error. Service has encountered one or more unexpected conditions that prevented it from fulfilling the request, which may or may not be temporary. Response will contain more details about these errors | ServiceErrors |
# DELETE Delete a Variable Definition
# /definitions/variables/{variableDefinitionId}
# Description
Marks the variable definition as deleted. No new instances can be created and no new versions added. The variable definition will stay in the database though, as this is a soft delete. To delete the entity completely (hard delete), please contact the Operations Team.
# Parameters
| Name | Located in | Description | Required | Schema |
|---|---|---|---|---|
| variableDefinitionId | path | definition id | Yes | string |
# Responses
| Code | Description | Schema |
|---|---|---|
| 204 | Variable definition was successfully deleted. | |
| 404 | Not found. One or more resources were not found, response may contain details about missing resources | ServiceErrors |
| 5XX | Service error. Service has encountered one or more unexpected conditions that prevented it from fulfilling the request, which may or may not be temporary. Response will contain more details about these errors | ServiceErrors |
# GET Get Variable Definition Versions
# /definitions/variables/{variableDefinitionId}/versions
# Description
Retrieves a list of available versions for the given variableDefinitionId. In order to retrieve the versions of a soft-deleted definition the includeDeleted flag has to be set to "true".
# Parameters
| Name | Located in | Description | Required | Schema |
|---|---|---|---|---|
| variableDefinitionId | path | definition id | Yes | string |
| includeDeleted | query | Whether to return a definition that has been marked as deleted | No | - |
# Responses
| Code | Description | Schema |
|---|---|---|
| 200 | Success | VariableVersions |
| 404 | Not found. One or more resources were not found, response may contain details about missing resources | ServiceErrors |
| 5XX | Service error. Service has encountered one or more unexpected conditions that prevented it from fulfilling the request, which may or may not be temporary. Response will contain more details about these errors | ServiceErrors |
# GET Get Variable Definition by Version Number
# /definitions/variables/{variableDefinitionId}/versions/{version}
# Description
Retrieves a specific variable definition identified by variableDefinitionId. Additionally, a version number needs to be supplied which can be partial (e.g., 1 or 1.1) which means that the latest sub version of that version will be returned (e.g., 1.2.5 or 1.1.3). In order to retrieve the specified version of a soft-deleted definition the includeDeleted flag has to be set to "true".
# Parameters
| Name | Located in | Description | Required | Schema |
|---|---|---|---|---|
| variableDefinitionId | path | definition id | Yes | string |
| version | path | (Partial) version number | Yes | string |
| includeDeleted | query | Whether to return a definition that has been marked as deleted | No | - |
# Responses
| Code | Description | Schema |
|---|---|---|
| 200 | Success. Retrieve object models by filter criteria. | VariableDefinition |
| 404 | Not found. One or more resources were not found, response may contain details about missing resources | ServiceErrors |
| 5XX | Service error. Service has encountered one or more unexpected conditions that prevented it from fulfilling the request, which may or may not be temporary. Response will contain more details about these errors | ServiceErrors |
# Reuse Primitive Variable Definitions
# Description
In TypeDefinitions and Extensions for variables components, Variable Definitions can be reused. Before utilizing in TypeDefinition or Extensions, variable definitions must be created.
NOTE
Only variables component can reuse variable definitions.
# Reuse in TypeDefinition
{
"typeId": "motorType",
"version": "1.0.0",
"model": "abb.ability.device",
"isExtensible": true,
"variables": {
"var": {
"dataType": "scales@1" //variable definition scales already defined
}
}
}
# Reuse in Extensions
{
"properties": {
"speed": {
"dataType": "integer"
}
},
"variables": {
"length": {
"dataType": "scales@1" //variable definition scales already defined
}
}
}