--- name: cumulocity-manage-smartrest-templates description: "Create a SmartREST 2.0 template collection with its X-ID, list and find collections, export a collection, and delete it. Use when the user wants to create, find, export, or delete SmartREST 2.0 template collections." compatibility: "Requires network access to a Cumulocity tenant and the C8Y_BASEURL, C8Y_TENANT, C8Y_USER, and C8Y_PASSWORD environment variables." --- # Manage SmartREST 2.0 template collections Source: https://cumulocity.com/docs/skills/device-management/manage-smartrest-templates/ Sector: Skills, Device management & connectivity Release: Latest Description: Create a SmartREST 2.0 template collection with its X-ID, list and find collections, export a collection, and delete it. ## Before you start Use these skills first: - `cumulocity-authentication` skill: [Authenticate REST API requests](https://cumulocity.com/docs/skills/platform-administration/authentication/index.md) A SmartREST 2.0 template collection is a set of request and response templates that devices use to communicate with Cumulocity. Devices refer to a collection by its unique ID, the X-ID. For the templates themselves, see [SmartREST 2.0](https://cumulocity.com/docs/smartrest/smartrest-two/#template-collections). A template collection consists of the following parts: * A managed object of the type `c8y_SmartRest2Template`. Its fragment `com_cumulocity_model_smartrest_csv_CsvSmartRestTemplate` contains the arrays `requestTemplates` and `responseTemplates`. * An external ID of the type `c8y_SmartRest2DeviceIdentifier` on this managed object. Its value is the X-ID. Each X-ID is unique in the tenant. > **Requirements:** > ROLES & PERMISSIONS: > > * To create and delete template collections: ROLE_INVENTORY_ADMIN > * To create the X-ID: ROLE_IDENTITY_ADMIN > * To find a collection by its X-ID: ROLE_IDENTITY_READ > * To read template collections: ROLE_INVENTORY_READ The examples use `` for the ID of the managed object of the collection and `` for its X-ID. ### To create a template collection {#to-create-a-template-collection} 1. Send a [Create one or multiple managed objects](https://cumulocity.com/api/core/#operation/postManagedObjectCollectionResource) request: ```http POST /inventory/managedObjects Content-Type: application/json Accept: application/json { "name": "My template collection", "type": "c8y_SmartRest2Template", "com_cumulocity_model_smartrest_csv_CsvSmartRestTemplate": { "requestTemplates": [], "responseTemplates": [] } } ``` The request creates a collection without templates. The platform returns HTTP 201 and the managed object with its `id`. Note the `id` as ``. 2. Send a [Create an external ID](https://cumulocity.com/api/core/#operation/postExternalIDCollectionResource) request to give the collection its X-ID: ```http POST /identity/globalIds//externalIds Content-Type: application/json Accept: application/json { "type": "c8y_SmartRest2DeviceIdentifier", "externalId": "" } ``` The platform returns HTTP 201 and the external ID with `"externalId": ""`. If the platform returns HTTP 409, another collection already has this X-ID. Find it as described in [To find a template collection by its X-ID](https://cumulocity.com/docs/skills/device-management/manage-smartrest-templates/#to-find-a-template-collection-by-its-x-id). Do not delete or move the existing X-ID. Choose another X-ID, or use the existing collection. To add templates to the collection, use the Device Management application, see [To create a new SmartREST template](https://cumulocity.com/docs/device-management-application/smartrest-templates/#to-create-a-new-smartrest-template). ### To list all template collections {#to-list-all-template-collections} Send a [Retrieve all managed objects](https://cumulocity.com/api/core/#operation/getManagedObjectCollectionResource) request with the type of the collections: ```http GET /inventory/managedObjects?type=c8y_SmartRest2Template&pageSize=1000 ``` The platform returns HTTP 200. The `managedObjects` array contains the template collections with their `id` and `name`. ### To find a template collection by its X-ID {#to-find-a-template-collection-by-its-x-id} Send a [Retrieve a specific external ID](https://cumulocity.com/api/core/#operation/getExternalIDResource) request: ```http GET /identity/externalIds/c8y_SmartRest2DeviceIdentifier/ ``` The platform returns HTTP 200. The ID of the collection is in `managedObject.id`. If the platform returns HTTP 404, no collection has this X-ID. ### To export a template collection {#to-export-a-template-collection} Send a [Retrieve a specific managed object](https://cumulocity.com/api/core/#operation/getManagedObjectResource) request: ```http GET /inventory/managedObjects/ ``` The platform returns HTTP 200 and the collection. Keep only the following properties of the response: * `name` * `type` * `com_cumulocity_model_smartrest_csv_CsvSmartRestTemplate` The result has the format of the export and import in the Device Management application. You can import it there, see [To import an existing SmartREST template](https://cumulocity.com/docs/device-management-application/smartrest-templates/#to-import-an-existing-smartrest-template). ### To delete a template collection {#to-delete-a-template-collection} > **Caution:** > After you delete a collection, devices can no longer use its X-ID. Delete only collections that no device uses. Send a [Remove a specific managed object](https://cumulocity.com/api/core/#operation/deleteManagedObjectResource) request: ```http DELETE /inventory/managedObjects/ ``` The platform returns HTTP 204 and deletes the collection together with its X-ID. If the platform returns HTTP 404, the collection does not exist anymore. ## API reference ### Core API Reference: https://cumulocity.com/api/core/ - [POST /inventory/managedObjects](https://cumulocity.com/api/core/#operation/postManagedObjectCollectionResource): Create one or multiple managed objects - [POST /identity/globalIds/{id}/externalIds](https://cumulocity.com/api/core/#operation/postExternalIDCollectionResource): Create an external ID - [GET /inventory/managedObjects](https://cumulocity.com/api/core/#operation/getManagedObjectCollectionResource): Retrieve all managed objects - [GET /identity/externalIds/{type}/{externalId}](https://cumulocity.com/api/core/#operation/getExternalIDResource): Retrieve a specific external ID - [GET /inventory/managedObjects/{id}](https://cumulocity.com/api/core/#operation/getManagedObjectResource): Retrieve a specific managed object - [DELETE /inventory/managedObjects/{id}](https://cumulocity.com/api/core/#operation/deleteManagedObjectResource): Remove a specific managed object ## Linked from the documentation - [SmartREST 2.0](https://cumulocity.com/docs/smartrest/smartrest-two/) - [SmartREST templates](https://cumulocity.com/docs/device-management-application/smartrest-templates/)