I want to integrate incidences

What are incidences?

As detailed here, incidences represent any employee absence: vacation, personal day, maternity leave, etc.

How to integrate incidences?

To register new incidences in the system, the following endpoints can be used:

What operations can be performed in incidence integration?

Add an absence

Once the incidence is registered in the business absence catalog (Business configuration > Absence types), it can be applied to an employee through the following endpoints:

Example

In the business absence catalog, there is an incidence type MEDICAL_APPOINTMENT with identifier (type) 01.

To apply it to the employee with identifier 1006356, make the following request:

POST /api/v1/import/incidence
{
  "business": "BUSINESSID",
  "employeeId": "1006356",
  "type": "01",
  "initTime": "12:00",
  "endTime": "14:00",
  "workedMinutes": 120,
  "from": "2024-07-02",
  "to": "2024-07-02",
  "id": "0156"
}

After registration, this absence will appear in the service incidence calendar (Employee Management > Absence calendar), and according to the business configuration, the necessary parameters for the employee will be applied: not allowing shift assignments, setting a margin between the absence and the shift, etc.

Add multiple absences

To add multiple absences to the same employee —provided they are registered in the business absence catalog— the following endpoint can be used:

This request includes the lag parameter, so it must be considered for the correct data management within Orquest.
Example

In the business absence catalog, there is an incidence type MEDICAL_APPOINTMENT with identifier (type) 01 and VACATION with identifier (type) 02.

To apply multiple absences with these types to the employee with identifier 1006356, make the following request:

POST /api/v1/import/incidences
{
  "lag": 0,
  "business": "BUSINESSID",
  "employeeId": "1006356",
  "incidences": [
    {
      "type": "01",
      "workedMinutes": 30,
      "initTime": "09:30",
      "endTime": "10:30",
      "from": "2024-07-08",
      "to": "2024-07-08",
      "id": "015601"
    },
    {
      "type": "02",
      "workedMinutes": 0,
      "from": "2024-07-15",
      "to": "2024-07-20",
      "id": "025601"
    },
    {
      "type": "02",
      "workedMinutes": 0,
      "from": "2024-08-01",
      "to": "2024-08-15",
      "id": "025602"
    }
  ]
}

After a successful response, the following absences will appear in the service absence calendar (Employee Management > Absence calendar) for the employee:

  • 2024-07-08: MEDICAL APPOINTMENT from 9:30 to 10:30 with 30 worked minutes.

  • 2024-07-15 to 2024-07-20: VACATION period.

  • 2024-08-01 to 2024-08-15: VACATION period.

As in the previous scenario, according to the business configuration, the necessary parameters for the employee will be applied: not allowing shift assignments, setting a margin between the incidence and the shift, etc.

As the request specifies lag = 0, all system data for this employee is overwritten by the sent data. Therefore, any previously registered absence disappears from the system.

Delete incidences

To delete incidences registered in the system, the following endpoints can be used:

  • Remove incidence through its external identifier. If the external identifier of the incidence is correct, the request will delete the record. If the identifier is not correct, the request will return a 404 Not Found error with the message: Could not find any incidence with id --- for business ---.

  • Remove employee incidences. If the employee identifier is correct, the request will delete all incidence records within the time interval specified in the request. If the employee identifier is not correct, the request will return a 404 Not Found error with the message: Could not find employee with id ---.

Example

In the absence calendar, the employee with identifier 1006356 has an absence of type VACATION with identifier (type) 02 from 2024-07-15 to 2024-07-20.

If the following request is made:

DELETE /api/v1/business/{businessId}/employees/1006356/incidences?from=2024-07-16&to=2024-07-16

Since the interval specified in the request includes the dates for which this absence is defined (2024-07-16), the entire absence is removed from the absence calendar.

Get incidences

Registered incidences for business employees can be queried by service or product through the following endpoints:

If the query range exceeds 30 days, the request will return a 406 Not Acceptable error.

FAQ

What time zone is considered for integration?

In the integration of incidences, the time zone configured for the service is considered. For example, for a service in UTC+2, the following incidence is sent:

POST /api/v1/import/incidence
{
  "business": "BUSINESSID",
  "employeeId": "1006357",
  "type": "01",
  "initTime": "17:00",
  "endTime": "19:00",
  "workedMinutes": 0,
  "from": "2024-07-05",
  "to": "2024-07-05",
  "id": "0157"
}

The result in the absence calendar will be an absence of type 01 from 17:00 to 19:00, as it appears in the request body.

What is the difference between get by service and get by product?

The difference between get incidences by service and get by product lies in the segmentation of the obtained data.

The choice between one query and the other will depend on business analysis and management needs, as the level of detail of the obtained data is the same.

Is it mandatory to set an identifier for the incidence?

No, the external identifier is not mandatory for incidences integration in Orquest, but it is highly recommended. Moreover, if you want to delete incidences through the identifier, it will be necessary to have defined it previously.