- 1. What is a family?
- 2. Create assets in Ermeo
- 3. Update assets in Ermeo
- 4. Retrieve all created or updated assets from your last synchronisation
This article will go through all the steps needed to synchronise assets between your systems and Ermeo. This involves the ability to create and updates assets in Ermeo as well as to retrieve assets from Ermeo to update your systems.
This article assumes that you already know how to authenticate your requests.
1. What is a family?
Routes used in this part:
Before diving into the main subject of this article, we need to understand the concept of family first. A family is the equivalent of what we call in the platform and the application a database. Therefore, a family is structured by attributes and contains assets that will have to follow the same structure. A few routes are available to manage your families directly from the API. In this article, we will mainly need to retrieve information about families rather than creating and updating ones. Thus, two routes are going to be important, to retrieve either all families from the workspace or a specific one.
In order to retrieve all families contained in a workspace, the following route will need to be called:
Here is the response of the API:
Different things are important in this response. The total_items corresponds to the number of families in the workspace. The total_pages is the number of pages you will have to go through in order to retrieve the information of all families. The items_per_page corresponds to the number of items in each page. By default, it is set to 10, but can be changed by passing a query parameter to the request. For instance, the next request allows you to retrieve 100 families on one page.
The next_page and previous_page correspond to the URL to call in order to either go to the next page to retrieve the next families or to go back to the previous page. We won't care about the next_page_search_after and search_after_id in this section.
The items contains all the families of the current page. In this case we have two families with several characteristics. We won't go too deep in all the keys and values contained in a family object, the most important things to keep in mind are the unique id of the family, its name as well as the attributes that structure this family. In this case, none of the families have attributes.
Let's now see how to call a specific family. We need to call the following route:
In this case, {id} should be replaced by the id of a specific family. For instance, if we want to retrieve the information about the family with the following id:
We would send the following request:
In that case, the API would return the following response:
This object is slightly the same as the objects retrieved in the items part of the Get all families request. In this response and only for the example, the Third Family had two attributes. Each of these attributes are structuring this family, and all the assets belonging to the family will have to follow this structure.
That was just a quick introduction to how families work in the API, this is the basics in order to understand the following parts of this article. If you want to have an explanation of every field in these responses, please refer to the API documentation.
2. Create assets in Ermeo
Routes used in this part:
This section will be useful if you need to create assets that you have in databases of your systems into Ermeo, to make their information available to the field workers during their jobs.
Creating an asset is not about sending only one request. We need to gather information from the API about how to create the asset. As seen in the previous part, assets must have a specific structure depending on the family they belong to.
Therefore, the first thing to know is the family we want to create our asset. Let's take the last family of the previous part for example. We know that its id is:
We also know that this family has two attributes: Attribute 1 and Attribute 2. This means that all the assets of this family should only have values for these attributes.
We now have to have information about these two attributes. To do this, we will use the route to search attributes:
This request is a search route. The API allows one to search for different entities in Ermeo: attributes, assets, families, jobs, and many other things. These routes are very powerful but quite difficult to apprehend. If you want to know more about how searching attributes works, please follow this link. In our case, we want to search attributes thanks to their id, as we retrieved them from the information about the Third family. Here is the body to retrieve attributes with specific ids:
This body means that we want to retrieve all the attributes having the id set to id_of_attribute_1 OR id_of_attribute_2. As each entity in Ermeo has a unique id, only two attributes are returned in the response of the API:
A few things are important in this response. First, all the keys from total_items to previous_page are the same as for the route to retrieve all the families of a workspace. Every time we retrieve a list of entities from the API, these fields will provide this information.
Then, in the items field, we can see that we have both of our attributes, but with their details this time. We now know that Attribute 1 is a number attribute, its unit is W, its minimum is 1 and its maximum is 10. We also know that Attribute 2 is a text attribute. This information is crucial to create our asset. If you want to know more about the other fields in this response, please follow this link.
With that in mind, the request and body to create an asset in the following one:
We now have all the information we need to create our asset, here is the body to send with the request:
In this body, we specify a name. This is the name your asset will have. We also specify the family it will belong to, in our case, the Third Family from the first part. Finally, the characteristics of the asset: its attributes. We know that Attribute 1 is a number and Attribute 2 is a text, and we decided that Asset 1 would have 5 as a value for Attribute 1 and Asset 1 description as a value for Attribute 2.
There is also another field we haven't talked about yet: the code. It is a unique field, meaning that two assets cannot have the same code. Let's say you have in your own system's database Asset 1, but this asset has a unique identifier, specific to your data structure. It is a very good practice to put this identifier in the code field of the asset. This will be used as a correspondance and ease the mapping between your systems and Ermeo.
The API will then send a response containing all the details of the created asset, taking of course into consideration the body sent with the request. It is generally a good practice to compare the response of the API with the body that has been sent. This confirms that the API has taken into account the information sent in the body. If this is not the case, this is most likely that the body is not formatted the right way. This is how the created asset would look in the Ermeo platform:
3. Update assets in Ermeo
Routes used in this part:
What if an asset has been updated in your system's database and needs to be updated in Ermeo? You can of course use the API to automate this kind of workflow.
We won't go too much into detail about this request. It is quite simple to understand and follow the same logic as the creation of an asset. Once we have identified the asset we want to update and how we want to update it (its attributes or his name for instance), we can use the following route:
Again, {id} should be replaced with the id of the asset to update. In the body sent with this request, we can decide to update a few things. If we take Asset 1 from the previous section, we can send the following body:
By sending this request, we update three things in our asset:
- his name, from Asset 1 to Asset 1 (updated name)
- its value for Attribute 1, from 5 to 6
- its value for Attribute 2, from Asset 1 description to Asset 1 updated description
The API then sends back a response containing all the details of the updated asset with the changes that we just made.
4. Retrieve all created or updated assets from your last synchronisation
Routes used in this part:
We now have everything we need to create and update assets in Ermeo. We also have seen how to respect the structure they should have according to the family they belong to. But how about retrieving information from your Ermeo databases?
Retrieving information from the API is easy when we know the routes to call. Some of them are more efficient than others. For example, let's assume that we have 100 000 assets in our database. That's quite a lot. If we send the request:
We would have the following body (simplified):
Each asset in items contains two very important fields:
- created_at corresponding to the date and time the asset has been created
- updated_at corresponding to the date and time the asset has been updated
That way, by going through the thousand pages (to retrieve all the assets) and checking these two fields we should be able to match only the assets we want to retrieve. If an asset has one of these fields that has been updated and that contains a date and time posterior to the last time you got all the assets of your workspace, this means that this asset has been updated (or created, depending on the field) during this period.
But that's not efficient. You need to go through all the pages in order to get all your assets. In this case, this corresponds to 1000 requests just to get newly created assets or updated ones... This uses server resources on your side and ours for almost nothing.
So how do we get these assets? In the section about creating assets, we talked about these very powerful search routes and used one to retrieve attributes with specific ids. We have a similar route to search for assets:
This route allows us to search for assets according to many fields:
- Their id
- Their code
- Their name
- Their parent
- Their attributes
- Their date of creation
- Their date of update
In our case, the last two points will be useful. Let's say we want to retrieve all the assets that have been created or updated the last day. Here is the body we should send:
In this body, we mention that we want to retrieve all the assets which have their field updated_at greater than or equal to (gte) the date yyyy-mm-dd at midnight (2022-01-15 00:00:00 for the 15th of January 2022 at midnight for example). The API will return all the assets that have been created and updated since this date and time.
You will notice that we didn't mention the field created_at. Nonetheless, we also retrieved the assets that have been created during this period of time. This is because when an asset is created, its field updated_at is automatically filled with the date of creation of this asset. Therefore, when an asset has never been updated, its field created_at is the same as its field updated_at. If we want to retrieve only the created assets during this period of time, we can send the following body with the request:
In that case, only the assets created since the date and time in the value will be returned by the API.