Using provisioning rules

This guide explains how to use provisioning rules in the nRF Cloud portal and APIs.

Note

Before you follow this guide, read it through carefully according to your desired interface. You cannot edit rules after you activate them.

Requirements

• An nRF91x1 device. Contact Support to ask about availability for the nRF9160.
• Modem firmware v2.0.0 or later.
• nRF Device provisioning sample or another sample that integrates the nRF Cloud device provisioning library.

Prerequisites

• Create a provisioning group for the target devices if you have not already created one.
• Claim the device or devices to which a rule will apply.

Managing provisioning rules in the nRF Cloud portal

This section explains how to create and manage provisioning rules using the nRF Cloud portal.

Creating provisioning rules

Complete the following steps to create a new provisioning rule:

1. Log in to the nRF Cloud portal.

2. In the left sidebar, select Security Services.

   A panel opens to the right.

3. Select Provisioning Rules.

4. Click the Create Rule button to create a new rule.

   A pop-up opens.

5. Fill in the Name field.

6. (Optional) Include a description of the rule.
7. Select the target provisioning group.

8. Click the Create Rule button.

   A page opens for the newly created provisioning rule. The rule status is DRAFT until you activate it.

9. Add provisioning commands to a configuration associated with the rule:

   1. Click the Create Command button.

      A pop-up opens.

   2. Add the desired command to the configuration. The information required depends on which type of command you are adding.

      • If you are adding a Configuration, enter the key and value, then click the blue + button next to the value field. Repeat for each key-value pair you add.

   3. Click the Create Command button inside the pop-up.

   4. Repeat with additional commands as needed.

While the rule status is DRAFT, you can still edit the associated provisioning configuration and commands. Once the rule is activated, you can no longer edit it. Check your commands carefully before proceeding.

Once the rule is activated and a device attempts secure provisioning, the Provisioning Service checks if it meets the specified conditions. If a rule applies, the device begins executing the provisioning commands in the configuration associated with that rule.

Managing rules in the nRF Cloud portal

The Provisioning Rules page provides an overview of provisioning rules you have created, including status.

Once you have created a provisioning rule, you can activate, suspend, resume, or delete it.

ActivatingSuspending and resumingCopyingDeleting

Caution

Once you activate a rule, you cannot change the commands under it or target conditions. You can only suspend, resume, or delete it. To avoid errors, refer to the best practices for provisioning rules. Carefully review your provisioning configurations before you activate the associated rule.

To activate a rule with DRAFT status:

1. Go to the page for a specific provisioning rule.
2. Click the Activate button.

The provisioning rule is now active. As you add devices to the indicated provisioning group, those devices check for new provisioning commands according to application configuration. While a rule is active, you can suspend, copy, or delete it.

If multiple rules apply to the same device, the device processes the associated configurations according to the time each rule was created, in chronological order. This means that the device processes commands from the oldest rule first. See Troubleshooting for more on how to address errors.

To suspend an activated rule:

1. Go to the page for a specific provisioning rule.
2. Click the Suspend button.

The provisioning rule is now suspended. Devices to which this rule applies do not continue to process provisioning commands until you re-activate the rule.

To resume the suspended rule, click the Resume button. This re-activates the rule so it applies to newly connected and reconnected devices.

1. Go to the page for a specific provisioning rule.
2. Click the Copy button.
3. Edit the name for the new rule. Rule names must be unique within your team.
4. Click the Copy Rule button.

A page opens for the newly created rule. Continue with adding commands, editing existing ones, and activating the rule as needed.

The copied rule is in DRAFT status until you activate it.

You can delete a rule with any status.

1. Select the check box next to the rule name.
2. Click the Delete button.

The rule is now deleted.

Managing provisioning rules through the APIs

This section outlines provisioning rule operations through the APIs.

Access

Endpoints for the Provisioning Service are available to admin and owner roles.

Creating and viewing rulesManaging commandsActivatingDeletingSuspending and resuming

Before creating a rule, you must create a provisioning group to define the rule target.

Call the CreateProvisioningRule endpoint to create a new provisioning rule. Include the required name and tags parameters. The server responds with status 201 and information about the new rule, including its ID, name, description, tags, and status.

Once you have created a rule, see the Managing commands tab on this page to add commands.

If a rule is still in DRAFT status, you can call the UpdateProvisioningRule endpoint to update the name or tags associated with the rule. The server responds with status 200 and information about the rule with a new updatedAt time.

Note

The service still processes an updated rule according to the createdAt time, not the updatedAt time.

Call the ListProvisioningRules endpoint to list all provisioning rules associated with your team and visible to your role. You can optionally filter rules according to their status. The server responds with status 200 and a list of all provisioning rules your role gives you access to.

Call the FetchProvisioningRule endpoint to fetch details for a specific provisioning rule. Include the rule-id parameter. The server responds with status 200 and information about the rule.

These endpoints all relate to managing commands associated with a rule and are different from the endpoints to create a provisioning configuration for an individual device. See the API documentation for each endpoint for more detailed information on forming requests, as well as required and optional parameters.

You can manage individual commands and operations, including skipping failed commands, from an individual claimed device's page.

Call the CreateProvisioningRuleCommand endpoint to add a command to the configuration included in a provisioning rule. Include the rule-id parameter in the request. Other required parameters depend on the selected request type. See the API documentation for more detailed information on command types and requirements. The server responds with status 202 if the request is successful. Repeat this call as required for each command in your configuration.

You cannot edit commands once you add them, but until you activate a rule, you can delete and add commands to the rule as needed. Commands are processed according to the order you created them.

Call the ListProvisioningRuleCommands endpoint to list configured commands for a specific provisioning rule. Include the rule-id parameter. The server responds with status 200 and a list of all commands associated with a rule.

Call the GetProvisioningRuleCommand endpoint to fetch a specific command from a provisioning rule. Include the rule-id parameter. The server responds with status 200 and information about the command.

Call the DeleteProvisioningRuleCommand endpoint to delete a specific command from a provisioning rule. Include the rule-id and command-id parameters. The server reponds with status 204.

Call the DeleteAllProvisioningRuleCommands endpoint to delete all commands from a rule. You can only delete commands from a rule in DRAFT status. Include the rule-id parameter. The server responds with status 204.

Caution

Once you activate a rule, you cannot change the commands under it or target conditions. You can only suspend, resume, or delete it. To avoid errors, refer to the best practices for provisioning rules. Carefully review your provisioning configurations before you activate the associated rule.

Call the ActivateProvisioningRule endpoint to activate a provisioning rule. Include the rule-id parameter in your request.

This changes its status from DRAFT to ACTIVE. Once you activate the rule, you can suspend it or delete it if necessary, but you cannot edit its name or commands. The server responds with status 200 when you successfully activate the rule.

You can check the status of an active rule using the FetchProvisioningRule endpoint.

Call the DeleteProvisioningRule endpoint to delete a specific provisioning rule. Include the rule-id parameter.

The server responds with status 204 if the rule is successfully deleted.

Call the SuspendProvisioningRule endpoint to suspend a provisioning rule. This is similar to skipping a provisioning command in a configuration, but applies to the whole rule. The rule is not deleted, but is not applied when a device connects. Include the rule-id parameter. The server responds with status 200 and information about the rule to show its status is now SUSPENDED.

Call the ResumeProvisioningRule endpoint to resume a suspended rule. Include the rule-id parameter. The server repsonds with status 200 and information about the rule to show its status is now ACTIVE.

Once you resume the rule, devices to which the rule applies begin processing its commands again.