In this article, we will go through the different notions in order to synchronise jobs between your systems and Ermeo. This involves the possibility to plan jobs in Ermeo, retrieving data from finished jobs and retrieving the associated reports.
This article assumes that you already know how to authenticate your requests . We also recommend you to take a look at the article about how to synchronise assets with Ermeo.
Plan jobs in Ermeo:
Routes used in this part:
Creating jobs with the Ermeo API is the basis of automated planification to manage the work of field workers within Ermeo. Mandatory fields are required in order to create a job. Before sending the request to create a job, we will have to retrieve a few things first.
Let's start with the attributes. Just like with databases, job attributes will structure the jobs we want to create. A created job can have value for all job attributes. This does not mean that has to be the case: if there are 20 job attributes on a workspace, a job can have a value for only 3 of these attributes. The request to retrieve all the job attributes is the following:
We notice the query parameter resource set to intervention. This means that among all the attributes on the workspace (documents, assets, users, and interventions), we only want the API to return the job attributes:
This response has exactly the same structure as when we retrieved the attributes of a specific database in the article about how to synchronise assets with Ermeo. The only thing that has changed is the resource field. It is now set to intervention instead of an asset. This confirms that we managed to only get job attributes. In this example, the API return two job attributes a number attribute and a text attribute. This means that all the jobs we create will be able to have value for these two attributes.
Next, let's talk about users. When creating a job, It is advised but not mandatory to assign it to one or several users. In order to do this, we need to be aware of the users that have access to this workspace. In order to do this, a request to get all the users exists:
The API will return the list of all the users in the workspace. This response works just like all responses of lists in the API.(more information about this request by following this link).
By retrieving all the users of the workspace, we can now identify the id of the user(s) with wen to assign the job.
Finally, a form has to be linked to the job we want to create. This form corresponds to the tasks the field worker will have to complete in order to finish the job. To retrieve all the documents, a request exists:
As for the users, we now have the possibility to identify the document we want to link to the job we are creating via the id (more information about the response of this request by following this link).We now have everything we need to create a job: the attributes we want to set to our job, the user(s) we want to assign the job to, and the form they will have to go through in order to finish the job. Let's create our job:
The body sent with this request should look like this:
A few fields are important in this body: the name of the job is the name that will be shown to the user on his device when he starts the application.The status will always have to be todo. This means that the job we are creating is planned and not started yet. Then come the attributes.
We have retrieved both Attribute 1 and Attribute 2 and set their value respectively to 4 and the Description of the job.
Then comes the user(s) assigned to this job. In this case, we decided to assign the job to only one user, but we could have of course assigned it to more.
The planning object corresponds to the planification details of the job. In this case, we decided that this job must be done on the 20th of March at 14:00 Paris time.
Finally, we need to link the form for this job. As we retrieved the list of documents and identified the one to link to this job earlier, this only corresponds to a reference via the id of the selected document.
Once sent, the API will return the created job, containing all the details of this intervention according to the body (more information about this request by following this link). This job is now ready to be completed on the due date of the 20th of March by the user we decided to assign this intervention to!
Retrieve finished jobs from your last synchronisation
Routes used in this part:
We now have everything we need to create jobs in Ermeo. This part is now going through the steps to retrieve your finished jobs.
Just like searching assets in the article about how to synchronise your resources with Ermeo , we don't especially want to retrieve all the jobs every time we have to synchronise them. This would not be efficient at all:
We would have the following body (simplified):
Each job in items contains three very important fields:
- status corresponding to the status of the intervention
- planning.real_end_date corresponding to the date and time the job has been finished
- is_preview corresponds to whether the job has been done from the studio preview or not.
That way, by going through the (possible) hundred pages (to retrieve all the jobs) and checking these three fields we should be able to match only the jobs we want to retrieve. If a job has its fields status and real_end_date that has been updated and that contains a date and time posterior to the last time you got all the jobs of your workspace, this means that this job has been finished during this period of time.
But that's not efficient. You need to go through all the pages in order to get all your assets. This could represent hundreds of requests just to get newly finished jobs. This uses server resources on your side and on ours for almost nothing.
So how do we get these jobs? Just like searching assets, we have a route in order to search for jobs:
This route allows us to search for assets according to many fields:
- Their id
- Their code
- Their name
- Their status
- is_preview (whether they are from the studio preview or not)
- Their attributes
- Their real_start_date (date and time the job started)
- Their real_end_date (date and time the job finished)
- Their asset
- Their users
In our case, two fields will be useful:
- is_preview
- status
- real_end_date
Indeed, we want to retrieve all jobs that have been finished on the last day. Here is the body we should send:
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 on the last day. Here is the body we should send:
In this body, we mention that we want to retrieve all the jobs which have their field real_end_date 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). Moreover, we don't want to retrieve the jobs that have been done from the preview of the studio: these jobs are mainly done for test purposes. Finally, the status is used to tell the API we only want finished jobs.
Download finished reports files via exports
Routes used in this part:Export a report as an Ermeo report
Retrieving finished jobs after a certain date and time is one thing. We may also want to download their associated reports. There are two types of reports available to download in Ermeo: the standard report and the possible custom reports associated with the document.
Identify reports to download
When retrieving a job, there is a field that will allow us to get the associated reports: reports. This field is an array of objects that contains all the reports associated to the job:
In most cases, we will only have one report per job. But when a field worker decides to start over a job, we don't delete the associated report. We just make it archived. This report and its data are still accessible from the job.
As there can be several reports for a job, we will need to go through all these reports to check their status, as we may only want to retrieve the report that has actually been finished. For this, the route to call is:
In response to the API, the status of the report will be returned. We are looking for the report to have its status set to done. When we have identified the report to retrieve, we can go to the next steps: creating an export of the report and downloading it.
What is an export?
Now that we have the report that we want to download, let's create an export based on this report. But what is an export in Ermeo? The report we want to download is not generated at the end of the job. We are here talking about the file itself, not the data inside this report. As this file is generated on demand, we need to ask to generate this file. This is what we call an export. After creating an export, an asynchronous task will be run on our side, generating the export. Once this export is finished, it will be available to download.
Download standard Ermeo reports
The nature of the report we want to download is defined by the type of export we ask to the API. Let's create an export in order to download the Ermeo standard report associated to the report {first_report_id}:
In the body sent with the request, we can send specific details about how we want to "format" the Ermeo report:
- display_user: wether the field worker(s) who made the job should be displayed in the header or not
- display_unanswered_form_widgets: wether the tasks that have not been answered should be displayed or not
- display_duration: wether the duration of each task should be displayed or not
- display_hidden_form_widgets: wether the tasks that have been hidden to the field worker(s) should be displayed or not
The API should return the following response:
As the exports are a generic feature of Ermeo (it is possible to create many different types of exports), many fields are not relevant in our case. The main things are:
- The id of the export
- The status of the export
- The date and time the export has been finished (finished_at)
- The date and time the export expired (expires_at): we will not be able to download this export after this date and time
- The format of the file created by the export
The status of the export is the most important field to take into consideration. Indeed, an export can only be downloaded once its status is set to ready. As this is an asynchronous task, it is recommended to retrieve the created export every 10 seconds until its status is set to ready thanks to the following route:
Once the export is ready, we can download it!
When sending this request, the API will return a stream of the file. You only have to create a file from this stream and apply the right extension thanks to the format returned in the export.
Download custom reports
Custom reports are associated with a document. When making jobs from this document, the associated reports will be available to download in the custom report format. In order to download a custom report, we first need to retrieve all the custom reports associated with the document the report is from. For this, a route exists:
We can see that this request needs the id of the associated document to the report. We can get this information when retrieving the report. Once we have identified the custom_report to export, we can send the following body:
This request is slightly different from the one to create an export of a standard Ermeo report. Here is the body to send with the request:
The custom report id is defined in this body. We also see that the settings contain a field: to_pdf. As custom reports are Excel or Word files, we give the possibility to convert the file to PDF in order to retrieve a PDF file when downloading it.
The steps are then exactly the same as downloading the standard Ermeo report: check the status of the created export every 10 seconds, and send this request to download the file:
When sending this request, the API will return a stream of the file. You only have to create a file from this stream and apply for the right extension thanks to the format returned in the export.