Service associations

This section contains a detailed technical explanation of all the endpoints necessary to manage the information related to service associations through the API.

Considerations

Taking into account the data returned by the API in these requests, it is necessary to distinguish between two types of structures: service association and current service association.

Service association

This is a more general and comprehensive concept that encompasses all possible details about an employee’s association with a product or section. It includes fields that provide an exhaustive description of the relationship between the employee and the product, allowing for advanced aspects such as disponibility on different day types, regular cessions, and custom metadata to be defined.

[
    {
        "ownerProduct": "string",
        "product": "string",
        "from": "yyyy-MM-dd",
        "to": "yyyy-MM-dd",
        "splitPresence": true,
        "unplannable": false,
        "card": "string",
        "roles": [],
        "disponibility": [
            {
                "from": "yyyy-MM-dd",
                "to": "yyyy-MM-dd",
                "ranges": [
                    {
                        "dayType": "string",
                        "startMinuteDay": 0,
                        "duration": 0
                    }
                ]
            }
        ],
        "regularCessions": [
            {
                "product": "string",
                "minutes": 0,
                "days": ["string"]
            }
        ],
        "metadata": {},
        "id": "string",
        "service": "string",
        "person": {
            "name": "string",
            "surname": "string",
            "group": "string",
            "email": "string",
            "birthday": "yyyy-MM-dd",
            "employeeId": "string",
            "metadata": {},
            "seniority": "yyyy-MM-dd",
            "virtual": false
        }
    }
]
Service association

  • ownerProduct. The identifier of the product or section to which the employee belongs.

  • product. The identifier of the product or section where the employee will work. It may be the same as ownerProduct; if different, it is a cession.

  • from. The start date of the service association in the format yyyy-MM-dd.

  • to. The end date of the service association in the format yyyy-MM-dd. It can be set as null, indicating that no end date is set.

  • splitPresence. Determines whether it is a split shift. The default value is true.

  • unplannable. Determines whether the employee will be ignored by the scheduler and must be planned manually. The default value is false.

  • card. The employee’s card identifier in clocking systems.

  • roles. A list of role identifiers assigned to the employee in this service association.

  • disponibility. The employee’s availability during a specific period. By default, an employee’s availability is total, considering contract limitations. To change it, the following data must be provided:

    • from. Start date of the availability period in the format yyyy-MM-dd.

    • to. End date of the availability period in the format yyyy-MM-dd. It can be set as null if the service association also is.

    • ranges. List of availabilities for each day type. These ranges must be defined in the contract and include the following parameters:

      • dayType. The type of day to which the availability applies. System options include: ALL, WEEKENDS, WORKED, HOLIDAY, MONDAY, TUESDAY, WEDNESDAY, THURSDAY, FRIDAY, SATURDAY, SUNDAY. Other day types can be defined at the business level.

      • startMinuteDay. The start of the availability in minutes from 00:00. For example, 600 for 10:00 AM.

      • duration. The duration of the range in minutes.

  • regularCessions. Indicates if the employee works some days of the week in another product or section systematically. If there are regular cessions, they must be defined using the following fields:

    • product. The identifier of the target product or section where the employee will work.

    • minutes. The number of minutes the employee will work in the target product or section.

    • days. List of day types the employee will work on. Allowed values: MONDAY, TUESDAY, WEDNESDAY, THURSDAY, FRIDAY, SATURDAY, SUNDAY.

  • metadata. Any additional data related to the service association. The structure of this metadata must be configured in advance by the Orquest team.

  • id. External identifier of the service association.

  • service. External identifier of the service.

  • person. Basic employee data:

    • name. The employee’s first name.

    • surname. The employee’s last name(s).

    • group. If groups are defined within the business, the group to which the employee belongs.

    • email. The employee’s email, if one is set.

    • birthday. The birthdate in the format yyyy-MM-dd.

    • employeeId. The external identifier of the employee.

    • metadata. Additional data about the employee. The structure of this field must be previously configured by the Orquest team.

    • seniority. The employee’s seniority date in the format yyyy-MM-dd.

    • virtual. Determines whether it is a real employee or a virtual one used, for example, for simulations.

Current service association

This is a simplified model that contains only the essential fields, focusing on the necessary attributes to identify the current association and the employee’s relationship with the service.

[
    {
        "ownerProduct": "string",
        "product": "string",
        "from": "yyyy-MM-dd",
        "to": "yyyy-MM-dd",
        "splitPresence": false,
        "unplannable": false,
        "id": "string",
        "employeeId": "string",
        "service": "string"
    }
]
Current service association

  • ownerProduct. The identifier of the product or section to which the employee belongs.

  • product. The identifier of the product or section where the employee will work. It may be the same as ownerProduct; if different, it is a cession.

  • from. The start date of the service association in the format yyyy-MM-dd.

  • to. The end date of the service association in the format yyyy-MM-dd. It may be null, indicating that no end date is set.

  • splitPresence. Determines whether it is a split shift. The default value is true.

  • unplannable. Determines whether the employee will be ignored by the scheduler and must be planned manually. The default value is false.

  • id. External identifier of the service association.

  • employeeId. External identifier of the employee.

  • service. External identifier of the service or store.

Thus, the service association provides detailed information about the relationship, while the current service association focuses on representing the ongoing association in a simpler and more direct manner.