Skip to main content

Synchronise your jobs and reports with Ermeo

Ermeo Support
  • Updated
Follow

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, to retrieve data from finished jobs and retrieve 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:
Get all attributes
Get all users
Get all documents
Create a job

 

Creating jobs with the Ermeo API is the basis of automated planification to manage the work of field workers within Ermeo. A 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, jobs attributes will structure the jobs we want to create. A created job can have a value for all jobs attributes. This does not mean that has to be the case: if there are 20 jobs attributes on a workspace, a job can have a value for only 3 of these attributes. The request to retrieve all the jobs attributes is the following:

GET https://api.ermeo.com/api/v1/attributes?resource=intervention

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:

{
  "total_items": 2,
  "total_pages": 1,
  "items_per_page": 10,
  "next_page": null,
  "previous_page": null,
  "items": [
    {
      "id": "id_of_attribute_1",
      "code": "code_of_attribute_1",
      "name": "Attribute 1",
      "type": "number",
      "description": "",
      "resource": {
        "type": "intervention"
      },
      "settings": {},
      "created_by": {
        "id": "id_of_the_person_who_created_the_attribute",
        "code": "code_of_the_person_who_created_the_attribute"
      },
      "updated_by": {
        "id": "id_of_the_person_who_updated_the_attribute",
        "code": "code_of_the_person_who_updated_the_attribute"
      },
      "created_at": "date_of_creation",
      "updated_at": "date_of_update",
      "folder": null
    },
    {
      "id": "id_of_attribute_2",
      "code": "code_of_attribute_2",
      "name": "Attribute 2",
      "type": "text",
      "description": "",
      "resource": {
        "type": "intervention"
      },
      "settings": {
        "long_text": false
      },
      "created_by": {
        "id": "id_of_the_person_who_created_the_attribute",
        "code": "code_of_the_person_who_created_the_attribute"
      },
      "updated_by": {
        "id": "id_of_the_person_who_udpated_the_attribute",
        "code": "code_of_the_person_who_updated_the_attribute"
      },
      "created_at": "date_of_creation",
      "updated_at": "date_of_update",
      "folder": null
    }
  ]
}

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 asset. This confirms that we managed to only get jobs attributes. In this example, the API return two jobs attributes: a number attribute and a text attribute. This means that all the jobs we create will be able to have a 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:

GET https://api.ermeo.com/api/v1/users

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 to.

 

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:

GET https://api.ermeo.com/api/v1/documents

As for the users, we know 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:

POST https://api.ermeo.com/api/v1/interventions

The body sent with this request should look like:

{
  "name": "Intervention API",
  "status": "todo",
  "attributes": [
    {
      "id": "id_of_attribute_1",
      "value": {
        "number": 4
      }
    },
    {
      "id": "id_of_attribute_2",
      "value": {
        "text": "Description of the job"
      }
    }
  ],
  "users": [
    {
      "id": "user_assigned_to_the_job"
    }
  ],
  "planning": {
    "planned_timezone": "Europe/Paris", // exemple of a timezone
    "planned_start_date": "2022-03-20T14:00:00+01:00" // example of a planned_start_date
  },
  "document": {
    "id": "id_of_the_form"
  }
}

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 Description of the job.

Then come the user(s) assigned to this job. In this case, we decided to assign the job to only one user, but we coud 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 returned 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:
Get all jobs
Search jobs

 

We know 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:

GET https://api.ermeo.com/api/v1/interventions

We would have the following body (simplified):

{
  "total_items": 100000,
  "total_pages": 1000,
  "items_per_page": 100,
  "next_page": url_of_the_next_page,
  "previous_page": url_of_the_previous_page,
  "next_page_search_after": null,
  "search_after_id": null,
  "items": [all_interventions_of_the_workspace]
}

Each job in items contains three very important fields:

  1. status corresponding to the status of the intervention
  2. planning.real_end_date corresponding to the date and time the job has been finished
  3. is_preview corresponding to wether 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 check 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 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 assets, we have a route in order to search for jobs:

POST https://api.ermeo.com/api/v1/jobs/search

This route allows us to search for assets according to many fields:

  1. Their id
  2. Their code
  3. Their name
  4. Their status
  5. is_preview (wether they are from the studio preview or not)
  6. Their attributes
  7. Their real_start_date (date and time the job started)
  8. Their real_end_date (date and time the job finished)
  9. Their asset
  10. Their users

In our case, two fields will be useful:

  1. is_preview
  2. status
  3. real_end_date

Indeed, we want to retrieve all jobs that have been finished 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 the last day. Here is the body we should send:

[
  {
    "status":[
      {
        "operator":"equals",
        "value":{
          "text":"done"
        }
      }
    ],
    "is_preview":[
      {
        "operator":"equals",
        "value":{
          "yes_no":false
        }
      }
    ],
    "real_end_date": [
      {
        "operator": "gte",
        "value": {
          "date": "yyyy-mm-dd 00:00:00"
        }
      }
    ]
  }
]

In this body, we mention that we want to retrieve all the jobs which have their field real_end_date greater than or equals 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:
Get a job
Get a report
Get all custom reports
Export a report as an Ermeo report
Export a report as a custom report
Get an export
Download an export

 

Retrieving finished jobs since a certain date and time is one thing. We may also want to download their associated reports. There are two types or reports available to download in Ermeo : the standard report and the possible custom reports associated to 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:

GET https://api.ermeo.com/api/v1/interventions/{id}
"reports": [
  {
    "id": "first_report_id",
    "code": "first_report_code"
  },
  {
    "id": "second_report_id",
    "code": "second_report_code"
  }
]

In most of the 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 retrieved the report that has actually been finished. For this the route to call is:

GET https://api.ermeo.com/api/v1/reports/{id}

In the response of the API, the status of the report will be returned. We are looking for the report having 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}:

POST https://api.ermeo.com/api/v1/reports/{first_report_id}/export/pdf
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "code": "string",
  "settings": {
    "display_user": true,
    "display_unanswered_form_widgets": true,
    "display_duration": true,
    "display_hidden_form_widgets": true
  }
}

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:

{
  "name": "export_name",
  "id": "export_id",
  "status": "pending",
  "type": "reports",
  "format": "pdf",
  "created_at": "Date of creation of the export",
  "started_at": null,
  "finished_at": null,
  "expires_at": null,
  "num_of_downloads": 0,
  "users": [],
  "total": 1,
  "progress": 0.0,
  "failed": 0,
  "done": 0,
  "is_recurring": false,
  "nb_column": 0,
  "recurrence": null
}

As the exports is 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 download 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:

GET https://api.ermeo.com/api/v1/exports/{id}

Once the export is ready, we can download it!

GET https://api.ermeo.com/api/v1/exports/{id}/download

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 to 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 to the document the report is from. For this, a route exists:

GET https://api.ermeo.com/api/v1/custom_reports?document_id={id}

We can see that this requests 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:

POST https://api.ermeo.com/api/v1/reports/{first_report_id}/export/custom_report

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:

{
  "custom_report":{
    "id":"custom_report_id"
  },
  "settings":{
    "to_pdf":false
  }
}

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:

GET https://api.ermeo.com/api/v1/exports/{id}/download

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.

Related articles

Comments

0 comments

Please sign in to leave a comment.