Get a step’s configuration

This endpoint returns the configuration defined for a step of a needs proposal: its productivity rules, employee distribution and staffing limits.

GET /api/v1/businesses/{businessId}/products/{productId}/needs-config/seasons/{seasonId}/proposals/{proposalId}/steps/{stepId}

The external identifiers of the different entities (business, product, season, proposal and step) must be specified in the request URL. If the data included in the URL is correct, the response will contain the configuration defined for the specified step.

Response example

{
    "id": "STP1",
    "name": "Productivity",
    "type": "PRODUCTIVITY",
    "order": 4,
    "simpleProductivity": true,
    "productivityBands": [
        {
            "dayType": "ALL",
            "dayTypeNode": null,
            "startMinute": 540,
            "duration": 300,
            "salesBrackets": [
                {
                    "minSales": 0.0,
                    "maxSales": 400.0,
                    "productivity": 1.0
                },
                {
                    "minSales": 400.0,
                    "maxSales": 1500.0,
                    "productivity": 2.0
                },
                {
                    "minSales": 1500.0,
                    "maxSales": 3000.0,
                    "productivity": 3.0
                }
            ]
        }
    ],
    "employeeDistributionBands": [
        {
            "dayType": "ALL",
            "dayTypeNode": null,
            "startMinute": 540,
            "duration": 660,
            "distributions": [
                {
                    "totalEmployees": 1,
                    "locations": [
                        {
                            "id": "03",
                            "zone": "General",
                            "employees": 1
                        }
                    ]
                },
                {
                    "totalEmployees": 2,
                    "locations": [
                        {
                            "id": "03",
                            "zone": "General",
                            "employees": 2
                        }
                    ]
                },
                {
                    "totalEmployees": 3,
                    "locations": [
                        {
                            "id": "03",
                            "zone": "General",
                            "employees": 3
                        }
                    ]
                }
            ]
        }
    ],
    "employeeLimits": [
        {
            "dayType": "ALL",
            "dayTypeNode": null,
            "bands": [
                {
                    "startMinute": 540,
                    "duration": 300,
                    "minPersons": 1,
                    "maxPersons": 4
                },
                {
                    "startMinute": 840,
                    "duration": 360,
                    "minPersons": 2,
                    "maxPersons": 5
                }
            ]
        }
    ]
}
Details

  • id: external identifier of the step.

  • name: name of the step.

  • type: type of the step.

  • order: position of the step within the proposal.

  • simpleProductivity: determines whether the productivity value of each bracket is a fixed number of employees (true) or is defined by the demand covered by one employee (false). It is defined at business proposal level and can be null if not configured.

  • productivityBands: productivity rules of the step. Each rule includes the following information:

    • dayType: name of the day type the productivity rule applies to.

    • dayTypeNode: external identifier of the node where the day type is defined. Can be null for a system day type.

    • startMinute: start of the interval in minutes from 00:00 local time. For example, 540 for 9:00.

    • duration: duration of the interval in minutes.

    • salesBrackets: brackets defined for the productivity rule. Each bracket includes the following information:

      • minSales: lower bound of the bracket.

      • maxSales: upper bound of the bracket. The engine selects the bracket by its lower bound, so the highest one extends to infinity.

      • productivity: number of employees when the step is of simple productivity, and demand units per employee when it is not.

      • minVariable: lower bound of the variable needs. Can be null if not defined.

      • maxVariable: upper bound of the variable needs. Can be null if not defined.

  • employeeDistributionBands: employee distribution bands of the step. Each one includes the following information:

    • dayType: name of the day type the distribution rule applies to.

    • dayTypeNode: external identifier of the node where the day type is defined. Can be null for a system day type.

    • startMinute: start of the interval in minutes from 00:00 local time. For example, 540 for 9:00.

    • duration: duration of the interval in minutes.

    • distributions: distribution by number of employees needed. Each bracket includes the following information:

      • totalEmployees: total number of employees the distribution is defined for.

      • locations: distribution of that number of employees across the tasks. Each task includes the following information:

        • id: external identifier of the task.

        • zone: external identifier of the task’s zone.

        • employees: employees assigned to the task.

  • employeeLimits: staffing limits of the step. Each block includes the following information:

    • dayType: name of the day type the employee limit applies to.

    • dayTypeNode: external identifier of the node where the day type is defined. Can be null for a system day type.

    • bands: limits per time slot. Each bracket includes the following information:

      • startMinute: start of the interval in minutes from 00:00 local time. For example, 540 for 9:00.

      • duration: duration of the interval in minutes.

      • minPersons: minimum number of people. null means there is no minimum.

      • maxPersons: maximum number of people. null means there is no maximum.

Considerations

If there is no configuration defined, the response will return an empty array for that entity (productivityBands, employeeDistributionBands or employeeLimits).

Error codes

In addition to the common errors, this endpoint can return the following codes:

Code Message Description

404 Not Found

The product has no season with that id

The season specified in the URL does not exist.

The proposal is not active in that season

The proposal specified in the URL does not exist.

The proposal has no writable step with that id

The step specified in the URL does not exist in the proposal, or its type is not yet supported by this request.

Useful links

What are needs?

What is a needs generator?

How to get the needs configuration?