I want to integrate employees

What are employees?

As detailed here, employees are individuals hired to perform specific work within a business. The information related to employees includes all data concerning assignments, skills, clockins, contracts, service associations, requests and incidences.

How to integrate employees?

To integrate employees through the API, there are different endpoints available. Below is a breakdown of various scenarios and the endpoints useful in each case.

Add a list of employees

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

Create or update employee list (complex). Allows adding a list of employees by providing the complete information of each employee (personal data, user, service associations and contracts).
Create or update employee list (simplified). Allows adding a list of employees including only the essential information related to personal data, service associations and contracts.

Considering that each option requires specific fields, the choice of an endpoint depends on the information to be integrated into Orquest.

Modify data of an existing list of employees

The endpoints available to modify a list of employees are the same as in the previous scenario:

The complex version includes more data than the simple version and allows incorporating the lag parameter. It is essential for determining the number of days prior to the request that will be considered when managing the sent information.

This section shows some of the operations that can be performed in the employee integration and that consider this parameter.

Add an employee

To add a new employee to the system, the endpoints exposed in the previous scenarios can be used, including only the data of the employee to be integrated:

Additionally, the following endpoints can be used:

Create or update employee (complex). Allows adding all data, including linked user, contracts, service associations, etc., using the employee ID in the URL.
Create or update employee (simplified). Allows adding an employee including only the essential information related to personal data, service associations and contracts.

Considering that each option requires specific fields, the choice of an endpoint depends on the information to be integrated into Orquest.

Modify employee data

All endpoints from the previous scenarios allow modifying an employee’s information:

Each of these endpoints requires specific information about the employee to be integrated. Therefore, it is recommended to review the mandatory information and collect it before making the request.

What operations can be performed in employee integration?

Considering the complexity of the employee endpoints exposed above, the Orquest API allows performing specific operations such as the following:

Add, modify or delete a contract.
Add, modify or delete a service association.
Add, modify or delete a cession.
Add, modify or delete availability.

Add a new contract

To add a new contract to an employee who already has previous contracts, the available options are as follows:

Sending all data
Sending only the new data

Using any of the endpoints, include in the request body both the information of the previous contracts and the new contract.

Create or update employee list (complex): defining lag = 0 because all information is being sent.
Create or update employee list (simplified).
Create or update employee (complex): defining lag = 0 because all information is being sent.
Create or update employee (simplified).

Send the data of the new contract without including previous contracts, considering the lag parameter with a value that covers the validity period of the new contract. In this case, the lag value will always be greater than 0.

Since the lag parameter must be included, the endpoints that can be used are:

Modify contract data

The options available in this scenario vary depending on the data defined for the employee.

If the employee has only one contract, the one to be modified, the information can be sent from any of the available endpoints. Thus, the contract data is overwritten.
If there are previous contract data, all information or only the information to be modified can be sent:

Sending all data
Sending only the new data

Any of the endpoints can be used, including in the request body both the previous information, which is not altered, and the contract to be modified.

Create or update employee list (complex): defining lag = 0 because all information is being sent.
Create or update employee list (simplified).
Create or update employee (complex): defining lag = 0 because all information is being sent.
Create or update employee (simplified).

Send the new contract data considering the lag parameter with a value that covers the validity period of the contract to be modified. In these cases, the lag is always greater than 0.

Since the lag parameter must be included, the endpoints that can be used are:

Delete a contract

To delete a contract from the system, simply exclude the element in the request body when sending the updated information. The Orquest API will overwrite the data, excluding from the system the elements that are not in the request.

As in the previous scenarios, all updated information can be sent from any of the available endpoints or use requests with the lag parameter to send only the information of the period covering the contract to be deleted.

Add, modify or delete a service association

To perform any of these operations related to service associations, follow the same steps as with contract integration.

Thus, all updated information can be sent from any of the available endpoints or use the complex requests with the lag parameter to send only the information of the period covering the service associations to be added, modified or deleted.

Add, modify or delete a cession

A cession, as detailed here, is understood as a service association where the employee will be related to the product they belong to (ownerProduct) and, temporarily, to a product they have been assigned to (product).

To add or modify a cession, follow the same steps as above, considering that the cession must start and end within the interval defined by a service association. In the following example, the request body includes a service association and a cession (same ownerProduct, different product) within the service association period.

Example

"serviceAssociations": [
      {
        "ownerProduct": "0001-G",
        "product": "0001-G",
        "from": "2021-06-25",
        "to": null,
        "splitPresence": null,
        "unplannable": null,
        "card": null,
        "roles": null
      },
      {
        "ownerProduct": "0001-G",
        "product": "0002-G",
        "from": "2024-03-01",
        "to": "2024-03-31",
        "splitPresence": null,
        "unplannable": null,
        "card": null,
        "roles": null
      }
]

To delete a cession, simply exclude the element in the request body when sending the updated information.

All employee endpoints support this operation:

Including all information (simple or complex with lag = 0).
Including only the changing information (complex with lag > 0).

Add, modify or delete availability

The disponibility field indicates, within a service association or cession, the employee’s availability depending on the day type over a specific period. To add or modify availability periods of an employee, send the mandatory data for this field within the service association or cession.

Example

  "serviceAssociations": [
    {
      "ownerProduct": "0001-G",
      "product": "0001-G",
      "from": "2021-06-25",
      "to": null,
      "splitPresence": null,
      "unplannable": null,
      "card": null,
      "roles": null,
      "disponibility": [
        {
          "from": "2021-06-25",
          "to": "2023-06-01",
          "ranges": [
            {
              "dayType": "ALL",
              "startMinuteDay": 600,
              "duration": 600
            },
            {
              "dayType": "MONDAY",
              "startMinuteDay": 450,
              "duration": 600
            }

          ]
        },
        {
          "from": "2023-06-02",
          "to": null,
          "ranges": [
            {
              "dayType": "ALL",
              "startMinuteDay": 660,
              "duration": 600
            },
            {
              "dayType": "MONDAY",
              "startMinuteDay": 600,
              "duration": 600
            }

          ]
        }
      ]
    }
  ]

To delete an availability period, simply exclude the element in the request body when sending the updated information.

All employee endpoints support this operation:

Including all information (simple or complex with lag = 0).
Including only the changing information (complex with lag > 0).

Possible error messages

Some of the error messages that may appear during employee integration are:

Message	Meaning
cession_no_contained_in_association	Some cessions are not contained within a service association.
contract_overlapped	Some contracts are overlapped.
email_not_valid	The email address is not valid.
role_not_valid	The role is either invalid or does not exist.
has_not_service_id	The service either does not exist or has not been indicated.
has_not_valid_type	The type either does not exist or has not been indicated.
not_valid_person	The person object is not valid.
not_valid_metadata	The metadata is not valid, either due to structure or configuration.
overlapped_associations	Some service associations are overlapped.
service_not_exits	The service is either invalid or does not exist.
interval_disponibility_out_of_association	The availability interval is not contained within the service association.
person_advice	The person object does not have valid data.
interval_day_overlapped	Some availability intervals are overlapped.

Message

Meaning

cession_no_contained_in_association

Some cessions are not contained within a service association.

contract_overlapped

Some contracts are overlapped.

email_not_valid

The email address is not valid.

role_not_valid

The role is either invalid or does not exist.

has_not_service_id

The service either does not exist or has not been indicated.

has_not_valid_type

The type either does not exist or has not been indicated.

not_valid_person

The person object is not valid.

not_valid_metadata

The metadata is not valid, either due to structure or configuration.

overlapped_associations

Some service associations are overlapped.

service_not_exits

The service is either invalid or does not exist.

interval_disponibility_out_of_association

The availability interval is not contained within the service association.

person_advice

The person object does not have valid data.

interval_day_overlapped

Some availability intervals are overlapped.

FAQ

What happens if an employee is created without a service association?

The employee will only appear in the main business node. To retrieve the employee, there are two options:

Use any of the available endpoints to modify the employee’s data and add a service association.
Link the employee from the graphical user interface: Organizational Diagram > People > View Unassigned Employees > Retrieve Employee.

How does the lag parameter work in requests?

The lag parameter determines the number of days prior to the request date that will be considered when managing information in Orquest. For more information on its behavior, it is recommended to visit the following link, where explanatory examples are provided.

How to apply a contract type?

To apply a contract type, the "contractTypeId" field must be included within the contracts object, considering the following conditions:

Orquest DOES NOT apply contract types to contracts whose end date is earlier than the current system date.
The contract type ID must match the one configured at the business level: Organizational Diagram > Contract types > Outer ID.

If applicable, different fields of the contract will be overwritten with the values set in the contract type.

If any value other than 0 is provided, the request information takes precedence, even if a contract type is applied. For example, if the contract type has no vacation days but the request includes "numberOfHolidays": 7, the contract type will be applied, and 7 vacation days will be set.

After integrating a contract via API with an associated contract type, manual changes made through the Orquest interface may cause the contract type to no longer apply. Specifically, the contract type will be removed if any field is manually modified within the following sections:

Contract definition.
Control period (Expiration).
Holidays.

If contract metadata has been created for the business, modifying any of it will also cause the previously applied contract type to disappear.