Dataset lifecycle
In this document you will learn about the statuses during solving and the solving lifecycle.
(The dataset status is indicated on the top right in the sidebar in the Platform UI, or by the solverStatus field in the API.)
Dataset statuses
A dataset can be in one of several states:
| Status | Description | API value |
|---|---|---|
A new dataset has been created from a new input dataset or a patch to an existing dataset. |
|
|
The dataset has been validated. |
|
|
The submitted dataset was invalid. |
|
|
The score analysis and KPIs for the dataset have been computed before solving. This can be useful for datasets that already include partial solutions (e.g. employees assigned to shifts, vehicles assigned to visits). |
|
|
The data is in the queue to be solved. |
|
|
The input dataset is being converted into the planning problem and augmented with additional information, such as distance matrix (if applicable). |
|
|
The planning problem is currently being solved. |
|
|
A solution was not found before the run was terminated. |
|
|
Solving has completed and no further solution will be generated. |
|
|
An error has occurred and solving was unsuccessful. |
|
Typical lifecycle
When you submit a dataset you can specify if solving should start (?operation=SOLVE) or not (?operation=NONE), by appending the query parameter to the API endpoint.
If omitted, SOLVE is the default.
The solving status can become "Failed" because of errors at any stage.
The "Dataset created" and "Solving scheduled" (when solving is requested) occur synchronously and are triggered by the API call.
The other statuses occur asynchronously as resources become available.
There are 3 possible scenarios:
3. Submit the dataset and do not solve followed by a second call to start solving
First operation "NONE":
-
Synchronously.
-
Asynchronously
Second operation "SOLVE":
-
Synchronously.
-
Asynchronously
When to use ?operation=NONE
There are two common reasons to submit a dataset without solving:
Reality check — evaluating what actually happened: After a plan has been executed, submit the real-world assignments using ?operation=NONE.
The platform computes constraint scores, broken constraints, and KPI metrics for the actual plan without re-solving it.
You can then compare this evaluated dataset against the original optimized plan using the Comparison UI.
See Reality check: plan vs. reality for a step-by-step guide.
Score analysis workaround for large datasets: Synchronous operations such as score analysis and recommendations can time out at the gateway for large datasets, even when a solver thread is available.
As a workaround, submit the dataset with ?operation=NONE to load and evaluate it asynchronously, then call the score analysis endpoint on the resulting dataset.
This avoids the synchronous timeout.
See Solve queue for more context on synchronous operation limits.
Actions
Cancelling a solve: When a dataset that is being solved is Cancelled (via the Platform UI or the API) it goes from the current state to either "Incomplete" or "Completed".
Solving restarted
Sometimes solving may need to restart because of an error or the availability of resources.
When this happens, you can expect the following:
-
Logs will show the appended logs of the previous solving process (unless the previous log is unavailable).
-
The "submitted time" or "active time" of the solve is not reset to the time of the restart. The original times are preserved.
-
The score graph will include events produced by all of the solves.
Solving failed
Timefold generates multiple solutions during solving, when solving fails (SOLVING_FAILED) due to an error, you can review the best solution to the point of failure (if a solution was generated) in the Platform UI or through the API.
Webhooks
Our platform supports webhook events. Events are sent during the lifecycle of a dataset. See Webhooks for details.