Get Started

Get started with shift scheduling

A tutorial for getting started with shift scheduling.

The Nextmv shift scheduling app on marketplace provides a low-code entry point to the Nextmv platform and is the recommended starting point when solving a shift scheduling problem. It is a pre-built app with out-of-the-box functionality available now on Nextmv Cloud.

Once you subscribe to the Nextmv shift-scheduling app on marketplace, you can start running your model via the API.

marketplace_landing_page

After subscribing to the marketplace app, you are ready to run.

scheduling_app

Note, all requests must be authenticated with Bearer Authentication. Make sure your request has a header containing your Nextmv Cloud API key, as such:

  • Key: Authorization
  • Value: Bearer <YOUR-API-KEY>
Authorization: Bearer <YOUR-API-KEY>
Copy

Use this endpoint to submit a run:

POSThttps://api.cloud.nextmv.io/v1/applications/{application_id}/runs

New application run.

Create new application run.

View API details

For the payload, use only the "input" key, and you can submit an object similar to this one, which follows the input schema:

{
  "workers": [
    {
      "availability": [
        {
          "start": "2023-09-03T04:00:00+02:00",
          "end": "2023-09-03T11:00:00+02:00"
        },
        {
          "start": "2023-09-04T14:00:00+02:00",
          "end": "2023-09-04T22:00:00+02:00"
        }
      ],
      "id": "1"
    },
    {
      "availability": [
        {
          "start": "2023-08-28T15:00:00+02:00",
          "end": "2023-08-29T00:00:00+02:00"
        },
        {
          "start": "2023-08-29T16:00:00+02:00",
          "end": "2023-08-29T17:00:00+02:00"
        }
      ],
      "id": "2"
    },
    {
      "availability": [
        {
          "start": "2023-08-29T02:00:00+02:00",
          "end": "2023-08-29T11:00:00+02:00"
        },
        {
          "start": "2023-08-30T16:00:00+02:00",
          "end": "2023-08-31T03:00:00+02:00"
        },
        {
          "start": "2023-08-31T15:00:00+02:00",
          "end": "2023-08-31T22:00:00+02:00"
        },
        {
          "start": "2023-09-01T07:00:00+02:00",
          "end": "2023-09-01T12:00:00+02:00"
        },
        {
          "start": "2023-09-01T23:00:00+02:00",
          "end": "2023-09-02T05:00:00+02:00"
        },
        {
          "start": "2023-09-02T03:00:00+02:00",
          "end": "2023-09-02T08:00:00+02:00"
        },
        {
          "start": "2023-09-03T07:00:00+02:00",
          "end": "2023-09-03T11:00:00+02:00"
        }
      ],
      "id": "3"
    },
    {
      "availability": [
        {
          "start": "2023-08-28T11:00:00+02:00",
          "end": "2023-08-28T19:00:00+02:00"
        },
        {
          "start": "2023-08-28T20:00:00+02:00",
          "end": "2023-08-29T03:00:00+02:00"
        },
        {
          "start": "2023-08-29T04:00:00+02:00",
          "end": "2023-08-29T06:00:00+02:00"
        },
        {
          "start": "2023-08-29T22:00:00+02:00",
          "end": "2023-08-29T22:00:00+02:00"
        },
        {
          "start": "2023-08-30T12:00:00+02:00",
          "end": "2023-08-30T14:00:00+02:00"
        },
        {
          "start": "2023-09-04T06:00:00+02:00",
          "end": "2023-09-04T07:00:00+02:00"
        }
      ],
      "id": "4"
    }
  ],
  "required_workers": [
    {
      "start": "2023-08-29T09:00:00+02:00",
      "end": "2023-08-29T09:30:00+02:00",
      "count": 2
    },
    {
      "start": "2023-08-29T09:30:00+02:00",
      "end": "2023-08-29T10:00:00+02:00",
      "count": 3
    },
    {
      "start": "2023-08-29T10:00:00+02:00",
      "end": "2023-08-29T10:30:00+02:00",
      "count": 1
    },
    {
      "start": "2023-08-29T10:30:00+02:00",
      "end": "2023-08-29T11:00:00+02:00",
      "count": 2
    },
    {
      "start": "2023-08-29T11:00:00+02:00",
      "end": "2023-08-29T11:30:00+02:00",
      "count": 4
    },
    {
      "start": "2023-08-29T11:30:00+02:00",
      "end": "2023-08-29T12:00:00+02:00",
      "count": 3
    }
  ]
}
Copy

You can also specify "options" in the payload, which will override the default options. All values must be a string. Visit the options page for more information. This is a sample of options that can be passed:

{
  "input": {},
  "options": {
    "solve.duration": "1m",
    "limits.shift.minduration": "4h"
  }
}
Copy

Here is a curl command that summarizes the request:

curl -X 'POST' \
  'https://api.cloud.nextmv.io/v1/applications/{application_id}/runs?instance_id=latest' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer $API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "input": $INPUT,
    "options": $OPTIONS
  }'
Copy

After the run is submitted, you will obtain a run_id. To retrieve the results you can:

  • Go to the Runs of the app and look for the run_id in the table. Clicking on the run_id will take you to the results page.
  • Use the endpoint below to get the results, using the run_id. You should use polling to query for the results. When you poll, the .metadata.status of the result will shown the run status. A status of succeeded means the run is complete and the results are available.
GEThttps://api.cloud.nextmv.io/v1/applications/{application_id}/runs/{run_id}

Get run result.

Get the result of a run.

View API details

Here is a curl command that summarizes the request:

curl -X 'GET' \
  'https://api.cloud.nextmv.io/v1/applications/{application_id}/runs/{run_id}' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer $API_KEY'
Copy

After running, a JSON payload that follows the output schema, should have been returned with the solution, similar to this one:

{
  "options": {
    "limits": {
      "day": {
        "max_duration": 36000000000000
      },
      "shift": {
        "max_duration": 28800000000000,
        "min_duration": 7200000000000,
        "recovery_time": 28800000000000
      },
      "week": {
        "max_duration": 144000000000000
      }
    },
    "penalty": {
      "over_supply": 1000,
      "under_supply": 500
    },
    "solve": {
      "control": {
        "bool": [],
        "float": [],
        "int": [],
        "string": []
      },
      "duration": 10000000000,
      "mip": {
        "gap": {
          "absolute": 0.000001,
          "relative": 0.0001
        }
      },
      "verbosity": "off"
    }
  },
  "solutions": [
    {
      "assigned_shifts": [
        {
          "end": "2023-08-29T11:00:00+02:00",
          "start": "2023-08-29T03:00:00+02:00",
          "worker_id": "3"
        }
      ],
      "number_assigned_workers": 1
    }
  ],
  "statistics": {
    "result": {
      "custom": {
        "constraints": 2713,
        "provider": "highs",
        "status": "optimal",
        "variables": 913
      },
      "duration": 0.116243292,
      "value": 5500
    },
    "run": {
      "duration": 0.116243292
    },
    "schema": "v1"
  },
  "version": {
    "sdk": "VERSION"
  }
}
Copy

🎉 🎉 🎉 🎉 🎉 🎉 🎉 🎉 🎉 🎉 🎉 🎉

You are all set to keep exploring!

Visit the options reference for detailed information on all the available options.

Page last updated