User Guide

Getting Started

To start using the API, it is necessary to have an integration user. This is a standard Orquest user, which can be created from the application, with the "Access importer API" permission enabled.

The integration user will have full control over the Orquest data related to the nodes they have visibility over. If the user requires access to all business information, they can be placed directly in the root node of the hierarchical structure.

Authentication

To use the different resources offered by the API, it is necessary to authenticate as an integration user. Currently, there are two ways to do this:

API Key.
Authentication Form (Deprecated).

Environments

To ensure the smoothest experience with the Orquest API, it is important to understand the different environments available. Below are the two main environments: test and production.

Test environment (TEST). This environment is designed for testing purposes without affecting real data. It is ideal for experimenting with the API, validating configurations and testing new integrations.

Orquest (TEST).

API (TEST).

Production environment (PROD). This is the environment where real data is managed and final operations are conducted.

Orquest (PROD).

API (PROD).

Since the URLs are different, requests should be made to the appropriate endpoint according to the environment. For example, to query the available services in a business, it is possible to make the request to the following URLs:

TEST: https://test.orquest.es/api/api/v1/business/BUSINESSID/services
PROD: https://importer.orquest.es/api/v1/business/BUSINESSID/services

As the base URL for the TEST environment is https://test.orquest.es/api, the /api is duplicated when adding the rest of the endpoint.

Automatic Code Generation

The API is fully described in an OpenAPI file. Through this file, developers can use any of the available automatic code generation tools.

Openapi-generator is one of the tools available for this purpose, but it is advisable to explore the different options to choose the one that best suits the needs of each project.

Temporal data

The application displays the configured time zone for each service, meaning the time values corresponding to each region where the users or services are located.

However, the temporal values integrated through the API must be entered in UTC+0, that is, in Universal Time Coordinated. This measure ensures consistency and the correct handling of dates and times in all operations carried out in the system.

The insertion is done with the time transformed. For example, to send measures for a full day in a service with a UTC+2 time zone, it is necessary to send the data from 22:00 UTC+0 of the previous day to 22:00 UTC+0 of the same day.

For detailed information about the time zone affecting each country, you can refer to the official documentation of the IANA (Internet Assigned Numbers Authority), which maintains a time zone database widely used in computer systems and applications to determine the local time in different locations.

Lag

The lag parameter within API requests determines the number of days prior to the current date that will be considered when managing information in Orquest.

Lag = 0: all the information in the request will be included in the integration process, regardless of the date, replacing any previous information with what is specified in the request body. All system data is overwritten.
Lag > 0: changes the information of those elements that are within the lag period. If there is earlier data not included in the request and that does not fall within the lag period, this information remains unchanged.

Below, the behavior of this parameter in the integration of contracts is detailed, being the same for service associations, availabilities, etc.

Example 1
Example 2
Example 3

Scenario: the request includes information about an old contract whose validity falls within the lag period and information about a new contract that starts on the day of the request.

Request date: 2024-06-01
Previous contract: 2021-06-25 to 2024-05-31 (included in the request)
New contract: 2024-06-01 to 2025-06-01 (included in the request)
Lag: 10

{
  "business": "CST",
  "lag": 10,
  "partial": false,
  "ignoreWithoutOuterId": false,
  "ignoreServiceAssociations": true,
  "ignoreContracts": false,
  "person": {
    "name": "Evaristo",
    "surname": "Garrido",
    "birthday": "1989-02-03",
    "employeeId": "1006353"
  },
  "contracts": [
    {
      "from": "2021-06-25",
      "to": "2024-05-31",
      "regularMinutes": 2400,
      "weeklyContract": true,
      "additionalMinutes": 1200,
      "regularControlPeriod": "WEEKLY",
      "additionalControlPeriod": "WEEKLY",
      "calendarDaysOff": true,
      "numberOfHolidays": 30,
      "numberOfPublicHolidays": 14,
      "weeklyDaysInvolved": "MONDAY_SUNDAY",
      "costPerHour": 10,
      "personCategory": "001"
    },
    {
      "from": "2024-06-01",
      "to": "2025-06-01",
      "regularMinutes": 2400,
      "weeklyContract": true,
      "additionalMinutes": 1200,
      "regularControlPeriod": "WEEKLY",
      "additionalControlPeriod": "WEEKLY",
      "calendarDaysOff": true,
      "numberOfHolidays": 30,
      "numberOfPublicHolidays": 14,
      "weeklyDaysInvolved": "MONDAY_SUNDAY",
      "costPerHour": 10,
      "personCategory": "001"
    }
  ]
}

Outcome:

As the lag period covers the validity dates of both contracts, both are updated in the system with the data from the request.

If there were earlier contracts in the system whose validity falls outside the lag period, they remain in the system.

Scenario: the request only includes the new contract data, but the lag period covers the validity of an earlier contract.

Request date: 2024-06-01
Previous contract: 2021-06-25 to 2024-05-31 (not included in the request)
New contract: 2024-06-01 to 2025-06-01 (included in the request)
Lag: 10

{
  "business": "CST",
  "lag": 10,
  "partial": false,
  "ignoreWithoutOuterId": false,
  "ignoreServiceAssociations": true,
  "ignoreContracts": false,
  "person": {
    "name": "Evaristo",
    "surname": "Garrido",
    "birthday": "1989-02-03",
    "employeeId": "1006353"
  },
  "contracts": [
     {
      "from": "2024-06-01",
      "to": "2025-06-01",
      "regularMinutes": 2400,
      "weeklyContract": true,
      "additionalMinutes": 1200,
      "regularControlPeriod": "WEEKLY",
      "additionalControlPeriod": "WEEKLY",
      "calendarDaysOff": true,
      "numberOfHolidays": 30,
      "numberOfPublicHolidays": 14,
      "weeklyDaysInvolved": "MONDAY_SUNDAY",
      "costPerHour": 10,
      "personCategory": "001"
    }
  ]
}

Outcome:

As the lag period covers the validity dates of both contracts, the new contract is included in the system and the previous contract disappears.

Scenario: the request includes information about a new contract that starts within the lag period and there is a previous contract with an end date prior to the lag period.

Request date: 2024-06-01
Previous contract: 2021-06-25 to 2024-04-30 (not included in the request)
New contract: 2024-05-01 to indefinite (included in the request)
Lag: 1

{
  "business": "CST",
  "lag": 1,
  "partial": false,
  "ignoreWithoutOuterId": false,
  "ignoreServiceAssociations": true,
  "ignoreContracts": false,
  "person": {
    "name": "Evaristo",
    "surname": "Garrido",
    "birthday": "1989-02-03",
    "employeeId": "1006353"
  },
  "contracts": [
     {
      "from": "2024-05-01",
      "to": null,
      "regularMinutes": 2400,
      "weeklyContract": true,
      "additionalMinutes": 1200,
      "regularControlPeriod": "WEEKLY",
      "additionalControlPeriod": "WEEKLY",
      "calendarDaysOff": true,
      "numberOfHolidays": 30,
      "numberOfPublicHolidays": 14,
      "weeklyDaysInvolved": "MONDAY_SUNDAY",
      "costPerHour": 10,
      "personCategory": "001"
    }
  ]
}

Outcome:

As the lag period covers the validity date of the new contract, it is added to the system and the previous contract remains unchanged.

In short, whenever a value greater than 0 is set, it changes the information of those elements that fall within the lag period.

This parameter ensures that relevant information is not lost and that both past and future data can be updated as needed. Additionally, it allows sending only the data that will be altered, without the need to send in the request all the information previously registered.

Metadata

The API allows adding additional data to certain entities that can later be viewed in the application. This data is called metadata and must be configured by the Orquest team within the business, establishing the information to be integrated and its type (boolean, numeric, textual, etc.).

The integration is done through the metadata field in the entities that have it, forming a JSON object with the keys that were previously indicated. Since it is a collection-type field, the API’s behavior in the update considers the following scenarios:

If null is sent: the information in these fields is not altered.
If not sent: the information in these fields is not altered.
If sent empty {}: all previous information is deleted.
If other data is sent: all information is overwritten, meaning the new fields are inserted, the ones that do not appear are deleted, and the existing ones are updated.

The following is an example:

metadata
null
Ø
{}
New data

In the employee entity, inside person, the following metadata has been configured:

[
  {
    "name": "John",
    "surname": "Smith",
    "employeeId": "10163",
    "metadata": {
        "salary": "40k",
        "position": "translator"
    }
  }
]

If null is sent in the update, metadata remains.

[
  {
    "name": "Johnny",
    "surname": "Smith",
    "employeeId": "10163",
    "metadata": null
  }
]

Outcome:

[
  {
    "name": "Johnny",
    "surname": "Smith",
    "employeeId": "10163",
    "metadata": {
        "salary": "40k",
        "position": "translator"
    }
  }
]

If this field is not sent in the update, metadata remains.

[
  {
    "name": "Johnny",
    "surname": "Smith",
    "employeeId": "10163"
  }
]

Outcome:

[
  {
    "name": "Johnny",
    "surname": "Smith",
    "employeeId": "10163",
    "metadata": {
        "salary": "40k",
        "position": "translator"
    }
  }
]

If an empty object is sent in the update, the data is deleted.

[
  {
    "name": "Johnny",
    "surname": "Smith",
    "employeeId": "10163",
    "metadata": {}
  }
]

Outcome:

[
  {
    "name": "Johnny",
    "surname": "Smith",
    "employeeId": "10163"
  }
]

If other data is sent in the update, with fields that have been previously configured in Orquest, the information is overwritten.

[
  {
    "name": "Johnny",
    "surname": "Smith",
    "employeeId": "10163",
    "metadata": {
        "salary": "45k",
        "alias": "JS"
    }
  }
]

Outcome:

[
  {
    "name": "Johnny",
    "surname": "Smith",
    "employeeId": "10163",
    "metadata": {
        "salary": "45k",
        "alias": "JS"
    }
  }
]

When updating the metadata for service association, the behavior is different:

If the field is not sent, it is sent to null or empty {}, the previously created metadata disappears.

Therefore, to keep the service association metadata in the system, it is necessary to always include it in the request.

Identifiers

The Orquest API allows including external identifiers in many of its entities. This is a crucial aspect for integrating Orquest with other systems, facilitating synchronization and avoiding duplication.

Types of identifiers

In Orquest, there are two types of identifiers: external identifiers and internal identifiers.

External identifiers: allow linking Orquest entities with entities from other systems. It is strongly recommended to use external identifiers to simplify the integration process and avoid duplication of information.
Internal identifiers: allow establishing a unique internal identifier that Orquest assigns to each entity (orquestId). This value is used for internal references and should not be used as an integration key with external systems. It is a read-only data that cannot be modified.

In an external system, for example, an employee has the identifier 123MD. When creating or updating information related to this employee in Orquest, 123MD can be assigned as employeeId. The system will also have an internal identifier for this employee that will be used exclusively within Orquest.

Best practices

Using external identifiers allows each entity in Orquest to correspond to a unique entity in the external system, thus preventing the creation of duplicate records. Additionally, it aligns Orquest entities with those in external systems through common identifiers, facilitates data exchange and simplifies process integration, ensuring data integrity and consistency.

It is also recommended to avoid using sensitive data as external identifiers, such as ID numbers, passport numbers, or any other information that could expose a person’s identity or be used improperly. This helps protect both the privacy of individuals and the integrity of the system.