diff --git a/APIs/schemas/bulkProperties-set-request.json b/APIs/schemas/bulkProperties-set-request.json index 4603b22..28699b8 100644 --- a/APIs/schemas/bulkProperties-set-request.json +++ b/APIs/schemas/bulkProperties-set-request.json @@ -17,6 +17,10 @@ }, "recurse": { "type": "boolean" + }, + "restoreMode": { + "type": "integer", + "description": "numeric representation of NcRestoreMode enum options" } } } diff --git a/APIs/schemas/bulkProperties-validate-request.json b/APIs/schemas/bulkProperties-validate-request.json index 7796c1c..c4cf370 100644 --- a/APIs/schemas/bulkProperties-validate-request.json +++ b/APIs/schemas/bulkProperties-validate-request.json @@ -1,7 +1,7 @@ { "$schema": "http://json-schema.org/draft-04/schema#", "type": "object", - "description": "OPTIONS request body for invoking ValidateSetPropertiesByPath method on NcBulkPropertiesManager", + "description": "PATCH request body for invoking ValidateSetPropertiesByPath method on NcBulkPropertiesManager", "title": "Bulk properties Validate request", "required": [ "arguments" @@ -17,6 +17,10 @@ }, "recurse": { "type": "boolean" + }, + "restoreMode": { + "type": "integer", + "description": "numeric representation of NcRestoreMode enum options" } } } diff --git a/APIs/schemas/bulkProperties-validate-response.json b/APIs/schemas/bulkProperties-validate-response.json index 0a077c2..1642eb0 100644 --- a/APIs/schemas/bulkProperties-validate-response.json +++ b/APIs/schemas/bulkProperties-validate-response.json @@ -1,6 +1,6 @@ { "$schema": "http://json-schema.org/draft-04/schema#", "type": "object", - "description": "Returns a NcMethodResultObjectPropertiesSetValidation from a bulkProperties OPTIONS", + "description": "Returns a NcMethodResultObjectPropertiesSetValidation from a bulkProperties PATCH", "title": "NcMethodResultObjectPropertiesSetValidation" } diff --git a/docs/API requests.md b/docs/API requests.md index df48b2c..47018db 100644 --- a/docs/API requests.md +++ b/docs/API requests.md @@ -10,9 +10,9 @@ Concurrency control is left to specific device implementations, however devices The URL provided in the [IS-04 device](IS-04%20interactions.md) is used as the base URL for all subsequent requests. -As described in the Configuration API, the [rolePaths](https://specs.amwa.tv/is-14/branches/v1.0-dev/APIs/ConfigurationAPI.html#rolepaths_get) endpoint returns all the role paths available for the device. Each `rolePath` MUST be created by appending [NcObject roles](https://specs.amwa.tv/ms-05-02/latest/docs/NcObject.html) starting with the `root block` and using `.` as the delimiter. Consequently the `.` character MUST not be used inside individual object roles. +As described in the Configuration API, the [rolePaths](https://specs.amwa.tv/is-14/branches/v1.0-dev/APIs/ConfigurationAPI.html#rolepaths_get) endpoint MUST return all the device model's role paths. Each `rolePath` MUST be created by appending [NcObject roles](https://specs.amwa.tv/ms-05-02/latest/docs/NcObject.html) starting with the `root block` and using `.` as the delimiter. Consequently the `.` character MUST not be used inside individual object roles. -It is RECOMMENDED for Device model objects roles to use `Unreserved Characters` as described in [RFC 3986 - 2.3. Unreserved Characters](https://www.ietf.org/rfc/rfc3986.txt). When `Reserved Characters` are used in an object role, they MUST be URL encoded when included in the `rolePaths` endpoint and subsequently in a URL. +It is RECOMMENDED for device model objects roles to use `Unreserved Characters` as described in [RFC 3986 - 2.3. Unreserved Characters](https://www.ietf.org/rfc/rfc3986.txt). When `Reserved Characters` are used in an object role, they MUST be URL encoded when included in the `rolePaths` endpoint and subsequently in a URL. Device model object roles are case sensitive and thus any `rolePaths` and URLs which include them are also case sensitive as described in [RFC 7230](https://datatracker.ietf.org/doc/html/rfc7230#section-2.7.3). @@ -39,7 +39,7 @@ The following subsections define common use cases for the applicable HTTP verbs | PUT | [Modify a property](#changing-a-property) | baseUrl/rolePaths/{rolePath}/properties/{propertyId}/value | [property-value-put-request](https://specs.amwa.tv/is-14/branches/v1.0-dev/APIs/schemas/property-value-put-request.json) | [NcMethodResult](https://specs.amwa.tv/ms-05-02/latest/docs/Framework.html#ncmethodresult) | | PUT | [Setting bulk properties for a role path](#setting-bulk-properties-for-a-role-path) | baseUrl/rolePaths/{rolePath}/bulkProperties | [bulkProperties-set-request](https://specs.amwa.tv/is-14/branches/v1.0-dev/APIs/schemas/bulkProperties-set-request.json) | [NcMethodResultObjectPropertiesSetValidation](https://specs.amwa.tv/nmos-control-feature-sets/branches/publish-device-configuration/device-configuration/#ncmethodresultobjectpropertiessetvalidation) | | PATCH | [Invoke a method](#invoking-a-method) | baseUrl/rolePaths/{rolePath}/methods/{methodId} | [method-patch-request](https://specs.amwa.tv/is-14/branches/v1.0-dev/APIs/schemas/method-patch-request.json) | [NcMethodResult](https://specs.amwa.tv/ms-05-02/latest/docs/Framework.html#ncmethodresult) | -| OPTIONS | [Validating bulk properties for a role path](#validating-bulk-properties-for-a-role-path) | baseUrl/rolePaths/{rolePath}/bulkProperties | [bulkProperties-validate-request](https://specs.amwa.tv/is-14/branches/v1.0-dev/APIs/schemas/bulkProperties-validate-request.json) | [NcMethodResultObjectPropertiesSetValidation](https://specs.amwa.tv/nmos-control-feature-sets/branches/publish-device-configuration/device-configuration/#ncmethodresultobjectpropertiessetvalidation) | +| PATCH | [Validating bulk properties for a role path](#validating-bulk-properties-for-a-role-path) | baseUrl/rolePaths/{rolePath}/bulkProperties | [bulkProperties-validate-request](https://specs.amwa.tv/is-14/branches/v1.0-dev/APIs/schemas/bulkProperties-validate-request.json) | [NcMethodResultObjectPropertiesSetValidation](https://specs.amwa.tv/nmos-control-feature-sets/branches/publish-device-configuration/device-configuration/#ncmethodresultobjectpropertiessetvalidation) | ## GET @@ -79,10 +79,16 @@ This is equivalent to invoking the [GetDatatype method](https://specs.amwa.tv/ms |:--:| | _**Getting bulk properties**_ | -The URL MUST target a specific role path in the device model. Devices treat this as a request to retrieve all the properties of that role path inside a [bulk values holder](https://specs.amwa.tv/nmos-control-feature-sets/branches/publish-device-configuration/device-configuration/#ncbulkvaluesholder) and MUST return a response of type [NcMethodResultBulkValuesHolder](https://specs.amwa.tv/nmos-control-feature-sets/branches/publish-device-configuration/device-configuration/#ncmethodresultbulkvaluesholder). If the `recurse` query parameter is set to `true` then the response will include the values of the target role path as well as any nested role paths. Not including the `recurse` query parameter MUST be treated as providing a `recurse` value of `true`. If the request encountered an error then the response result returned MUST inherit from [NcMethodResultError](https://specs.amwa.tv/ms-05-02/latest/docs/Framework.html#ncmethodresulterror) and include an errorMessage of type [NcString](https://specs.amwa.tv/ms-05-02/latest/docs/Framework.html#primitives). +The URL MUST target a specific role path in the device model. This MUST retrieve all the properties of that role path as a [bulk values holder](https://specs.amwa.tv/nmos-control-feature-sets/branches/publish-device-configuration/device-configuration/#ncbulkvaluesholder) and MUST return a response of type [NcMethodResultBulkValuesHolder](https://specs.amwa.tv/nmos-control-feature-sets/branches/publish-device-configuration/device-configuration/#ncmethodresultbulkvaluesholder). If the `recurse` query parameter is set to `true` then the response MUST include the values of the target role path as well as any nested role paths. Not including the `recurse` query parameter MUST be treated as providing a `recurse` value of `true`. If the request encountered an error then the response result returned MUST inherit from [NcMethodResultError](https://specs.amwa.tv/ms-05-02/latest/docs/Framework.html#ncmethodresulterror) and include an `errorMessage` of type [NcString](https://specs.amwa.tv/ms-05-02/latest/docs/Framework.html#primitives). If devices cannot accept backup requests due to temporary internal constraints (e.g. requires to be in maintenance mode) then they MUST use a status of `NotReady` and supply further details on the reason for this in the `errorMessage`. This is equivalent to invoking the `GetPropertiesByPath` method on the [Bulk properties manager object](https://specs.amwa.tv/nmos-control-feature-sets/branches/publish-device-configuration/device-configuration/#ncbulkpropertiesmanager). +Retrieving properties through the `bulkProperties` endpoint allows a user to perform a `full backup` or a `partial backup`. + +A `full backup` is a [backup data set](Backup%20&%20restore.md#definitions) returned by a `GET` operation on the `/bulkProperties` endpoint of the root block with the `recurse` parameter set to true. + +A `partial backup` is a [backup data set](Backup%20&%20restore.md#definitions) returned by a `GET` operation on the `/bulkProperties` endpoint of any object of the device model, other than the root block. A partial backup can also be obtained by a `GET` operation on the `/bulkProperties` endpoint of the root block with the `recurse` query parameter set to false; however this will only result in a backup of the root block only. + ## PUT ### Changing a property @@ -99,8 +105,6 @@ The body of the request MUST include an object which includes the new value of t This is equivalent to invoking the generic [Set method](https://specs.amwa.tv/ms-05-02/latest/docs/NcObject.html#generic-getter-and-setter) on the specific object for the required property. -`TODO`: Figure out how we map deprecation statuses for properties and methods. - ### Setting bulk properties for a role path | ![Setting bulk properties](images/set-bulk-properties.png) | @@ -110,7 +114,7 @@ This is equivalent to invoking the generic [Set method](https://specs.amwa.tv/ms The PUT verb MUST be used for setting a bulk properties data set. The URL MUST target a specific role path. -The body of the request MUST include an object which includes an `arguments` object with `dataSet` and `recurse` sub elements. +The body of the request MUST include an object which includes an `arguments` object with `dataSet`, `recurse` and `restoreMode` sub elements. ```json { @@ -118,7 +122,8 @@ The body of the request MUST include an object which includes an `arguments` obj "dataSet": { ... }, - "recurse": true + "recurse": true, + "restoreMode": 1 } } ``` @@ -127,10 +132,12 @@ If the `recurse` value is `true` then the device will attempt to use the provide For a full schema of the required body object see the [bulkProperties-set-request](https://specs.amwa.tv/is-14/branches/v1.0-dev/APIs/schemas/bulkProperties-set-request.json) schema. -The response MUST be of type [NcMethodResultObjectPropertiesSetValidation](https://specs.amwa.tv/nmos-control-feature-sets/branches/publish-device-configuration/device-configuration/#ncmethodresultobjectpropertiessetvalidation). If the request encountered an error then the response result returned MUST inherit from [NcMethodResultError](https://specs.amwa.tv/ms-05-02/latest/docs/Framework.html#ncmethodresulterror) and include an errorMessage of type [NcString](https://specs.amwa.tv/ms-05-02/latest/docs/Framework.html#primitives). +The response MUST be of type [NcMethodResultObjectPropertiesSetValidation](https://specs.amwa.tv/nmos-control-feature-sets/branches/publish-device-configuration/device-configuration/#ncmethodresultobjectpropertiessetvalidation). If the request encountered an error then the response result returned MUST inherit from [NcMethodResultError](https://specs.amwa.tv/ms-05-02/latest/docs/Framework.html#ncmethodresulterror) and include an errorMessage of type [NcString](https://specs.amwa.tv/ms-05-02/latest/docs/Framework.html#primitives). If devices cannot accept restore requests due to temporary internal constraints then they MUST use a status of `NotReady` and supply further details on the reason for this in the errorMessage. This is equivalent to invoking the `SetPropertiesByPath` method inside the [Bulk properties manager object](https://specs.amwa.tv/nmos-control-feature-sets/branches/publish-device-configuration/device-configuration/#ncbulkpropertiesmanager). +Setting properties through the `bulkProperties` endpoint allows a user to perform a restore. + ## PATCH ### Invoking a method @@ -158,20 +165,16 @@ The response MUST be of type [NcMethodResult](https://specs.amwa.tv/ms-05-02/lat This is equivalent to invoking the specified method. -`TODO`: Figure out how we map deprecation statuses for properties and methods. - -## OPTIONS - ### Validating bulk properties for a role path | ![Validating bulk properties](images/validate-bulk-properties.png) | |:--:| | _**Validating bulk properties**_ | -The OPTIONS verb MUST be used for validating a bulk properties data set. +The PATCH verb MUST be used for validating a bulk properties data set. The URL MUST target a specific role path. -The body of the request MUST include an object which includes an `arguments` object with `dataSet` and `recurse` sub elements. +The body of the request MUST include an object which includes an `arguments` object with `dataSet`, `recurse` and `restoreMode` sub elements. ```json { @@ -179,7 +182,8 @@ The body of the request MUST include an object which includes an `arguments` obj "dataSet": { ... }, - "recurse": true + "recurse": true, + "restoreMode": 1 } } ``` diff --git a/docs/Backup & restore.md b/docs/Backup & restore.md new file mode 100644 index 0000000..a3ea71f --- /dev/null +++ b/docs/Backup & restore.md @@ -0,0 +1,166 @@ +# Backup & restore + +Supporting backup & restore is a key feature of IS-14. To discuss the various possible combinations of backup and restore, this section utilizes terms explained in the [Definitions](#definitions) section. + +The [Configuration API](https://specs.amwa.tv/is-14/branches/v1.0-dev/APIs/ConfigurationAPI.html) defines a `bulkProperties` endpoint which allows: + +- [Getting all the properties of a role path](https://specs.amwa.tv/is-14/branches/v1.0-dev/docs/API_requests.html#getting-all-the-properties-of-a-role-path) +- [Setting bulk properties for a role path](https://specs.amwa.tv/is-14/branches/v1.0-dev/docs/API_requests.html#setting-bulk-properties-for-a-role-path) +- [Validating bulk properties for a role path](https://specs.amwa.tv/is-14/branches/v1.0-dev/docs/API_requests.html#validating-bulk-properties-for-a-role-path) + +These mechanisms are used for enabling backup and restore functionality and this section of the specification aims to cover the expectations, behaviour and requirements for the following scenarios: + +- [Performing a backup](#performing-a-backup) +- Restoring a full backup data set to a [dynamic device after a faulty unit is replaced with an identical spare](#restoring-a-full-backup-data-set-to-a-dynamic-device-after-a-faulty-unit-is-replaced-with-an-identical-spare) +- Restoring a full backup data set to a [fixed device after a faulty unit is replaced with an identical spare](#restoring-a-full-backup-data-set-to-a-fixed-device-after-a-faulty-unit-is-replaced-with-an-identical-spare) + +`Note`: This does not mean that the backup & restore functionality can only be used in these scenarios. + +## Definitions + +A `device`, for the purposes of this section, is a physical or logical entity that can be backed up and restored using the procedures described. It may or may not correspond to an IS-04 Device or IS-04 Node. + +`Backup data set` is the set of data retrieved from a device using the backup procedures described. This is represented as an [NcBulkValuesHolder](https://specs.amwa.tv/nmos-control-feature-sets/branches/publish-device-configuration/device-configuration/#ncbulkvaluesholder) object. + +`Backup validation fingerprint` is an optional string in a `backup data set` that can be used to capture the various versions of the hardware, software and/or firmware that made up a device at the time the backup was performed. The format of the string is defined by the vendor and is opaque to other systems. This could contain information such as: + +- Manufacturer key +- Product key +- Software versions +- Hardware revisions +- Backup response hash +- Timestamp +- Whether its a full device model backup or a partial backup + +A `device model` in the context of this specification refers to all the objects and their properties which are exposed in the configuration API. + +A `full backup` is a `backup data set` that includes all properties for all role paths of a device model. This is achieved by using the [/bulkProperties endpoint](https://specs.amwa.tv/is-14/branches/v1.0-dev/docs/API_requests.html#getting-all-the-properties-of-a-role-path). + +A `partial backup` is a `backup data set` that includes only a subset of role paths of a device model. This is achieved by using the [/bulkProperties endpoint](https://specs.amwa.tv/is-14/branches/v1.0-dev/docs/API_requests.html#getting-all-the-properties-of-a-role-path). + +A `modified backup` is a `full backup` or `partial backup` where the backup data set has been modified by a client. Examples of modified backups include: updating values of existing backup data set properties, adding/removing device model role paths from the backup data set. + +## General concepts + +Role path objects within a backup data set contain a boolean property called `isRebuildable`. If the object is a non-block object `isRebuildable` means the object can be reconstructed (constructing a fresh object which can accept changes even to its readonly properties). If the object is a block, `isRebuildable` depicts it can be reconstructed as mentioned in the statement before but also that its members can be added or removed. When a parent block object is not rebuildable but a member child is rebuildable the implication is that the child cannot change its role within that block when being rebuilt through a restore. + +The restore mechanism achieved by [Setting bulk properties for a role path](https://specs.amwa.tv/is-14/branches/v1.0-dev/docs/API_requests.html#setting-bulk-properties-for-a-role-path) affects the device model by either rebuilding it or modifying it. + +A restore mode of `Modify` MUST only be allowed to make changes to existing writeable properties of existing device model objects and cannot modify the device model in a structural way (cannot cause the addition or removal of objects from blocks). + +A restore mode of `Rebuild` allows the changes performed through the `Modify` mode and allows the following additional ones: + +- adding new members to rebuildable block objects by constructing new member objects (structural changes) +- removing existing members from rebuildable block objects by deconstructing the member objects (structural changes) +- reconstructing existing objects (constructing fresh objects which can accept changes even to its readonly properties) + +In the interest of interoperability even devices with no `rebuildable` device model objects MUST accept `Rebuild` restores but only perform the changes in scope for a `Modify` restore whilst including notices for any changes to readonly properties. Furthermore, performing a `Modify` restore MUST be possible even when the backup data set contains readonly properties since writeable properties will results in the desired changes being applied and the readonly properties will result in notices in the response returned. + +The general pattern for how devices interpret the restore workflow can be explained as follows: + +- devices MUST always offer healthy objects in the device model after a restore +- devices MUST attempt to use the backup data set provided first as a pool of information for changing/constructing/deconstructing/reconstructing a particular role path object and if they have all the necessary data they MUST report the restore status as `Ok`. +- if the backup data set provided doesn't have the information required for changing/constructing/deconstructing/reconstructing a particular role path object, but the device can fill in the necessary gaps from an internal knowledge store, then they MUST report the restore status as `Ok` and include properties which have benefited from internal knowledge store data in the [notices](https://specs.amwa.tv/nmos-control-feature-sets/branches/publish-device-configuration/device-configuration/#ncpropertyrestorenotice) property as `Warning` notices. +- if devices cannot find the required information for changing/constructing/deconstructing/reconstructing a particular role path object in either the backup data set provided or an internal knowledge store then they MUST return `Failed` as the restore status. + +## Performing a backup + +Creating a backup is performed by using the `bulkProperties` endpoint of a device alongside the [Get verb](https://specs.amwa.tv/is-14/branches/v1.0-dev/docs/API_requests.html#getting-all-the-properties-of-a-role-path). + +In order to retrieve the whole device model (full backup), requests MUST use `root` as the `rolePath`. The response contains a `validationFingerprint` and the `values` of all the role paths in the device model. + +| ![Performing a full backup](images/performing-full-backup.png) | +|:--:| +| _**Performing a full backup**_ | + +Partial backups can be created by choosing other role paths. The scope of backups can further be restricted by using a query parameter of `recurse=false` which will only include the properties of the targeted role path. + +It is RECOMMENDED to store the backup file in its entirety and not remove elements from the data set as they might contain dependencies required by some of the role paths. + +## Restoring a full backup data set to a dynamic device after a faulty unit is replaced with an identical spare + +The following assumptions are made: + +- the spare device replacing the faulty unit is the same product type from the same vendor +- a [full backup](#performing-a-backup) has been created of the faulty unit when it was healthy +- the devices are dynamic containing rebuildable blocks and objects + +The first step is to perform a [Validation request](https://specs.amwa.tv/is-14/branches/v1.0-dev/docs/API_requests.html#validating-bulk-properties-for-a-role-path) to check if the backup data set can be successfully restored. + +In order to validate applying the whole backup data set against the device model, requests MUST use `root` as the `rolePath`. + +The request body MUST include: + +- the backup dataSet +- a boolean `recurse` argument (set to `true` for validating the whole device model) +- the `restoreMode` argument (set to `Rebuild` in order to allow blocks to be repopulated with the same members as per the original device) + +| ![Validating a full backup](images/validating-full-backup.png) | +|:--:| +| _**Validating a full backup**_ | + +The response MUST include a collection of all target device model role paths with a validation `status` property and a `notices` array of property notices. For role paths which have a `status` which is not a 2XX value the response MUST also include a `statusMessage` with details of why the validation failed. When there are properties of role path objects which cannot be validated from the values provided in the dataset, these MUST be reported in the `notices` property as `Warning` notices. + +The backup can be restored by performing a [Set request](https://specs.amwa.tv/is-14/branches/v1.0-dev/docs/API_requests.html#setting-bulk-properties-for-a-role-path) to restore the backup. + +In order to use the whole backup data set to restore against the device model, requests MUST use `root` as the `rolePath`. + +The request body MUST include: + +- the backup dataSet +- a boolean `recurse` argument (set to `true` for validating the whole device model) +- the `restoreMode` argument (set to `Rebuild` in order to allow blocks to be repopulated with the same members as per the original device) + +| ![Restoring a full backup](images/restoring-full-backup.png) | +|:--:| +| _**Restoring a full backup**_ | + +The response MUST include a collection of all target device model role paths with a validation `status` property and a `notices` array of property notices. For role paths which have a `status` which is not a 2XX value the response MUST also include a `statusMessage` with details of why the restore failed. When there are properties of role path objects which cannot be restored from the values provided in the dataset, these MUST be reported in the `notices` property as `Warning` notices. + +If devices require a system reboot in order to apply the restore then they MUST perform this immediately after responding to the restore request. + +The diagram below captures how the `Rebuild` restore uses the backup data set to transition the spare device from its out of the box device model to a state of functionality identical to the original faulty device. + +| ![Rebuild restore of spare](images/restoring_on_dynamic_spare.png) | +|:--:| +| _**Rebuild restore of spare**_ | + +## Restoring a full backup data set to a fixed device after a faulty unit is replaced with an identical spare + +The following assumptions are made: + +- the spare device replacing the faulty unit is the same product type from the same vendor +- a [full backup](#performing-a-backup) has been created of the faulty unit when it was healthy +- the devices are fixed containing no rebuildable blocks or objects + +The first step is to perform a [Validation request](https://specs.amwa.tv/is-14/branches/v1.0-dev/docs/API_requests.html#validating-bulk-properties-for-a-role-path) to check if the backup data set can be successfully restored. + +In order to validate applying the whole backup data set against the device model, requests MUST use `root` as the `rolePath`. + +The request body MUST include: + +- the backup dataSet +- a boolean `recurse` argument (set to `true` for validating the whole device model) +- the `restoreMode` argument (set to `Modify` in order to only allow changes to writeable properties) + +The response MUST include a collection of all target device model role paths with a validation `status` property and a `notices` array of property notices. For role paths which have a `status` which is not a 2XX value the response MUST also include a `statusMessage` with details of why the validation failed. When there are properties of role path objects which cannot be validated from the values provided in the dataset, these MUST be reported in the `notices` property as `Warning` notices. + +The backup can be restored by performing a [Set request](https://specs.amwa.tv/is-14/branches/v1.0-dev/docs/API_requests.html#setting-bulk-properties-for-a-role-path) to restore the backup. + +In order to use the whole backup data set to restore against the device model, requests MUST use `root` as the `rolePath`. + +The request body MUST include: + +- the backup dataSet +- a boolean `recurse` argument (set to `true` for validating the whole device model) +- the `restoreMode` argument (set to `Modify` in order to only allow changes to writeable properties) + +The response MUST include a collection of all target device model role paths with a validation `status` property and a `notices` array of property notices. For role paths which have a `status` which is not a 2XX value the response MUST also include a `statusMessage` with details of why the restore failed. When there are properties of role path objects which cannot be restored from the values provided in the dataset, these MUST be reported in the `notices` property as `Warning` notices. + +If devices require a system reboot in order to apply the restore then they MUST perform this immediately after responding to the restore request. + +The diagram below captures how the `Rebuild` restore uses the backup data set to transition the spare device from its out of the box device model to a state of functionality identical to the original faulty device. + +| ![Modify restore of spare](images/restoring_on_fixed_spare.png) | +|:--:| +| _**Modify restore of spare**_ | diff --git a/docs/README.md b/docs/README.md index 7b65248..b0e8a61 100644 --- a/docs/README.md +++ b/docs/README.md @@ -9,7 +9,4 @@ - [API requests](API%20requests.md) - [Data type marshalling](Data%20type%20marshalling.md) - [IS-04 interactions](IS-04%20interactions.md) - -### Examples - -- [Getting block members](Getting%20block%20members.md) +- [Backup & restore](Backup%20&%20restore.md) diff --git a/docs/images/performing-full-backup.png b/docs/images/performing-full-backup.png new file mode 100644 index 0000000..8a9fab7 Binary files /dev/null and b/docs/images/performing-full-backup.png differ diff --git a/docs/images/restoring-full-backup.png b/docs/images/restoring-full-backup.png new file mode 100644 index 0000000..61c8840 Binary files /dev/null and b/docs/images/restoring-full-backup.png differ diff --git a/docs/images/restoring_on_dynamic_spare.png b/docs/images/restoring_on_dynamic_spare.png new file mode 100644 index 0000000..6f8d088 Binary files /dev/null and b/docs/images/restoring_on_dynamic_spare.png differ diff --git a/docs/images/restoring_on_fixed_spare.png b/docs/images/restoring_on_fixed_spare.png new file mode 100644 index 0000000..13c2a7e Binary files /dev/null and b/docs/images/restoring_on_fixed_spare.png differ diff --git a/docs/images/set-bulk-properties.png b/docs/images/set-bulk-properties.png index 401869b..70166d2 100644 Binary files a/docs/images/set-bulk-properties.png and b/docs/images/set-bulk-properties.png differ diff --git a/docs/images/validate-bulk-properties.png b/docs/images/validate-bulk-properties.png index ee38805..719f454 100644 Binary files a/docs/images/validate-bulk-properties.png and b/docs/images/validate-bulk-properties.png differ diff --git a/docs/images/validating-full-backup.png b/docs/images/validating-full-backup.png new file mode 100644 index 0000000..51b99f3 Binary files /dev/null and b/docs/images/validating-full-backup.png differ diff --git a/examples/bulkProperties-get-200.json b/examples/bulkProperties-get-200.json index 495b1a1..47faab0 100644 --- a/examples/bulkProperties-get-200.json +++ b/examples/bulkProperties-get-200.json @@ -11,6 +11,7 @@ "index": 6 }, "name": "userLabel", + "typeName": "NcString", "isReadOnly": false, "value": "this is the property value" }, @@ -20,6 +21,7 @@ "index": 1 }, "name": "enabled", + "typeName": "NcBoolean", "isReadOnly": false, "value": true } diff --git a/examples/bulkProperties-set-request.json b/examples/bulkProperties-set-request.json index 0d62a5b..96655e8 100644 --- a/examples/bulkProperties-set-request.json +++ b/examples/bulkProperties-set-request.json @@ -12,6 +12,7 @@ "index": 6 }, "name": "userLabel", + "typeName": "NcString", "isReadOnly": false, "value": "Stereo Gain Block" }, @@ -21,6 +22,7 @@ "index": 1 }, "name": "enabled", + "typeName": "NcBoolean", "isReadOnly": false, "value": true } @@ -35,6 +37,7 @@ "index": 6 }, "name": "userLabel", + "typeName": "NcString", "isReadOnly": false, "value": "Channel Gain Block" }, @@ -44,6 +47,7 @@ "index": 1 }, "name": "enabled", + "typeName": "NcBoolean", "isReadOnly": false, "value": true } @@ -51,6 +55,7 @@ } ] }, - "recurse": false + "recurse": true, + "allowIncomplete": true } } diff --git a/examples/bulkProperties-validate-request.json b/examples/bulkProperties-validate-request.json index 0d62a5b..e112851 100644 --- a/examples/bulkProperties-validate-request.json +++ b/examples/bulkProperties-validate-request.json @@ -12,6 +12,7 @@ "index": 6 }, "name": "userLabel", + "typeName": "NcString", "isReadOnly": false, "value": "Stereo Gain Block" }, @@ -21,6 +22,7 @@ "index": 1 }, "name": "enabled", + "typeName": "NcBoolean", "isReadOnly": false, "value": true } @@ -35,6 +37,7 @@ "index": 6 }, "name": "userLabel", + "typeName": "NcString", "isReadOnly": false, "value": "Channel Gain Block" }, @@ -44,6 +47,7 @@ "index": 1 }, "name": "enabled", + "typeName": "NcBoolean", "isReadOnly": false, "value": true } @@ -51,6 +55,6 @@ } ] }, - "recurse": false + "recurse": true } }