Auto Provisioning Basics
Auto Provisioning is the ability of Foundry to automatically create a Foundry record whenever an MQTT message is sent to a specific topic for the first time. Foundry uses a combination of AWS IoT, AWS Kinesis, AWS Lamba, and AWS DynamoDB behind the scenes so you never have to worry about manually creating a new object every time you want to add a new object or device to Foundry.
To create an Auto Provisioning rule you will need at most five things, but most of the time you will only :
- Device Type: If you have not already you will need to create a Foundry Device Type. This will be the model for the object you are trying to create. For more on creating Device Types click here.
- Topic: This will be MQTT Topic your messages are coming in on.
- Group: Having a Group is not required, but if you would like all your newly created devices to be added to a specific Foundry group you will need to create one. For more on creating Foundry Groups click here.
- Attribute Name - This is the name (json_name) of that attribute that foundry will use to determine if a record already exists. For most Auto Provisioning rules you'll be using the mqtt_topic. More complex attribute names can be used too. For example, you can use the key "email_address".
- Attribute Value - This is the value that Foundry will use for its query to determine if a record already exists. For most Auto Provisioning rules you'll be using the topic(). Working off the example above if an incoming payload has an attribute called "email_address" the Auto Provisioning rule will see if an Object with that email address already exists in Foundry.
Creating Your First Auto Provisioning Rule
Navigate to the Provisioning Rules Page
If you have not already added the Auto Provisioning page to your sidebar, we highly recommend it. For instruction on how to add a new Foundry page to your sidebar see the bottom of this document. You can also directly navigate to this page using the URL; https://[ instance].thinglogix.com/#!/provisioningRules. Once here click "New Rule".
Creating Your Rule
In this step, you will actually be creating the rule itself. Here you will find 7 fields to fill out.
- Name: This will be the name of your Auto Provisioning rule. Important note: the name must contain only letters and numbers.
- Account: Here you will select from the dropdown the account you want your newly created objects to be associated with.
- Device Type: Select from the dropdown the Object type you want to create with this rule. If you have not created you Device Type yet please go back and create one.
- Group: Select from the dropdown the Foundry group you want your newly created objects to end up in. If you do not have a specific group you want them in you can select "No Group."
- Attribute Name: This is the name (json_name) of that attribute that foundry will use to determine if a record already exists. For most Auto Provisioning rules you'll be using the mqtt_topic.
- Attribute Value: This is the value that Foundry will use for its query to determine if a record already exists. For most Auto Provisioning rules you'll be using the topic().
- Topic: This value will be the topic you incoming messages are coming on.
Once you are finished filling in the fields click "Save Rule".
It's that easy, you have finished creating you Auto Provisioning rule!
Example:
I have a bunch of devices that are chirping on data on the topic "com.thinglogix/test/#" and I want to create a new object of type "Test" every time data is chirped on a topic I Foundry has not seen. I also do not have a group that I want these devices saved in. Once I filled out all the fields my page would look something like this.
Updating Your Auto Provisioning Rule
To edit your Auto Provisioning Rule, much like before navigate to the Provisioning Rules Page and click on the rule you want to edit. Make your changes and save your rule again.
Adding Pages to a Foundry Instance
If your gray sidebar is not fully visible, like below, click the button in the red circle below.
Click the name of your Foundry instance in the top left corner, as shown in the light blue circle to the left.
Click the ‘Page manager’ tab that just appeared.
The Page manager menu is where you can add pages to your instance of Foundry. Check the drop-down menus displayed to see if the page you are looking for is in one of those. If it is not, click the ‘New Page’ button.
The ‘Menu Item’ box selects which folder the new page will get added to.
The ‘Page Name’ is what the page’s name will be displayed as on the sidebar.
Select the URL of the page that you are trying to add.
Then click ‘Create’ and your page will appear on the left bar.