Get incremental changes

This endpoint returns the assignments that have undergone changes from the date indicated in the request to the current date.

GET /api/v1/businesses/{businessId}/assignments/incremental?since={yyyy-MM-ddTHH:mm:ss.SSS}

If the data included in the request is correct, the response will contain the assignments that have changed from the date indicated in the since parameter to the current date. This parameter must be a date within the last 45 days in UTC format.

This is a paginated response, so after the first call, the response headers will include a cursor to the next page (next) that indicates the URL of the next incremental assignments request. To get the next page of data, it is necessary to make a request to that URL with the cursor:

GET /api/v1/businesses/{businessId}/assignments/incremental?cursor=*******

It is necessary to repeat this process until the response no longer contains the next header, indicating that pagination is complete and there is no more data to display.

Response example

[
    {
        "product": "0001-G",
        "day": "2024-07-17",
        "assignments": [
            {
                "person": "1006355",
                "orquestId": 3456,
                "presence": {
                    "worked": false,
                    "timeFrames": [
                        {
                            "startMinuteDay": 0,
                            "duration": 1425,
                            "paid": false,
                            "worked": false
                        }
                    ]
                },
                "virtual": false
            }
        ]
    },
    {
        "product": "0002-G",
        "day": "2024-07-03",
        "assignments": [
            {
                "person": "1006356",
                "orquestId": 1234,
                "presence": {
                    "worked": true,
                    "timeFrames": [
                        {
                            "startMinuteDay": 570,
                            "duration": 180,
                            "paid": true,
                            "location": {
                                "color": "#738ac8",
                                "description": "Opening boxes, reviewing funds",
                                "name": "KITCHEN OPENING",
                                "shortName": "KO",
                                "requiredLevel": 3,
                                "priority": 4,
                                "type": "VARIABLE",
                                "shouldAvoidOvercover": true,
                                "system": false,
                                "category": "ADMINISTRATIVE",
                                "product": "0002-G",
                                "id": "KITCHEN_OPENING",
                                "zone": "General"
                            },
                            "worked": true
                        }
                    ]
                },
                "virtual": false
            }
        ]
    }
]
Details

  • product: external identifier of the product or section the grouped assignments belong to.

  • day: day the grouped assignments correspond to, in yyyy-MM-dd format.

  • assignments: list of assignments for the given product and day. Each item contains the following information:

    • person: employee external identifier.

    • orquestId: internal identifier of the assignment in Orquest.

    • presence: type of assignment that contains the work periods (timeFrames) with their locations. It contains the following fields:

      • worked: whether the type of assignment or presence is worked (true) or if it is a rest day (false).

      • timeFrames: set of time intervals that contain the tasks to be performed. For each interval, the following information is included:

        • startMinuteDay: start of the interval in minutes elapsed since the beginning of the day (00:00).

        • duration: duration of the interval in minutes.

        • paid: whether the interval, whether work or rest, is paid (true) or not (false).

        • worked: determines if the timeFrame has an assigned task (true) or not (false).

        • location: task to be performed in the defined interval. For each task, the following information is included:

          • color: color configured in Orquest for the task.

          • description: description of the task defined in Orquest.

          • name: name of the task in Orquest.

          • shortName: task abbreviation in Orquest.

          • requiredLevel: skill level required to perform the task. Ranges from 0 (no training needed) to 3 (maximum training level) and must be previously configured in Orquest.

          • priority: priority of task coverage. Ranges from 0 (low) to 5 (high) and must be previously configured in Orquest.

          • maxResources: limit of people for the task.

          • type: type of task, whether it is fixed, variable, or non-plannable (FIXED, VARIABLE, NON_PLANIFIABLE).

          • shouldAvoidOvercover: if this parameter is true, the task will not be overcovered.

          • system: determines if the task was created by the system (true) or by the user (false).

          • category: category of the task previously configured in Orquest.

          • product: external identifier of the product or section.

          • id: external identifier of the task.

          • metadata: any additional data that has been previously configured for the task in Orquest. The metadata structure must be previously configured.

          • zone: physical place in the service (store, restaurant, etc.) where the location is carried out.

    • virtual: indicates whether the employee is virtual (true) or real (false).

Assignments are grouped by product and day.

The purpose of this endpoint is to allow a client to make recurring requests to keep their data updated without having to perform excessively complex update processes. Therefore, this request provides a list showing the current state of assignments so that only outdated data needs to be overwritten.

For example, if an assignment for an employee on a specific day is deleted, the API returns the assignments for the entire day for the involved product.

Considerations

Orquest only stores the last 45 days of incremental changes. If the client does not make an incremental change request within that time period, a complete assignment request will need to be made.

Due to the complexity of the data, it is difficult to know if an element has changed when making bulk modifications. For example, when publishing a draft, assignments may change in bulk, but the result appears unchanged because an identical assignment has replaced another.

Since assignments are grouped into larger concepts, it is possible to record a change on a day regardless of how many individual assignments have changed for that day. Therefore, it is common to receive entities that seem unchanged because they are part of a larger concept that has changed.

Using this endpoint requires that the functionality be activated in advance by the Orquest team, due to its computational and memory costs when performing audits on certain entities. Therefore, it will be necessary to analyze the use case and manage its activation.

Useful links

What is an assignment?