Lineitems::checkpoints
Manage Project line's checkpoints
Description
A checkpoint is one of the most important part of a Project Line as it defines a task within that project.
A checkpoint is always part of a checklist (see MasterChecklist), has a MasterCheckpoint (giving it a name), a starting date (begin_at
), a duration in working days, a list of children/parents, and some additional fields to specificy specific time behaviors (floating, starting at a fixed date, minimum gap from children, etc.).
The starting date of a checkpoint as retrieved from the API is the expected starting date, by default. It’s not adjusted to take into account delays. It is possible to retrieve adjusted dates from the index
by passing the parameter adjust_dates
.
Checkpoint base fields
Name | Type |
---|---|
id | Integer (unique) |
name (read-only) | String |
master_checkpoint_id | Integer |
master_checklist_id (read-only) | Integer |
validated | Boolean |
begin_at | Date |
end_at | Date |
delay | Integer |
children (read-only) | Array of IDs |
parents (read-only) | Array of IDs |
delivery | Boolean |
min_child_gap | Float |
max_child_gap | Integer |
time_calculation_method | String |
has_issue | Boolean |
critical_path | Boolean |
validated_at | Datetime |
Params format (creation/update)
For this resource, all the params can be included in a key checkpoint
.
For instance, creating an independent Checkpoint in the Project Line 1234 in XML (POST /api/v1/line_items/1234/checkpoints):
<checkpoint>
<master-checklist>Technical Files</master-checklist>
<master-checkpoint>Example Checkpoint</master-checkpoint>
<duration>3</duration>
<begin-at>2015-01-01</begin-at>
<position>independent</position>
</checkpoint>
In JSON the root key isn’t necessary and the following body would be accepted:
{
"master_checklist": "Technical Files",
"master_checkpoint": "Example Checkpoint",
"duration": 3,
"begin_at": "2015-01-01",
"position": "independent"
}
Checkpoint associated resources
Master Checkpoint
The Master Checkpoint of a Checkpoint will determine:
- Its name
- Its checklist
It’s available in the Checkpoint format in the key master_checkpoint
and the id is available in master_checkpoint_id
for convenience.
As a result, it’s not possible to just ‘rename’ a Checkpoint: the master checkpoint must be renamed or a new master checkpoint must be selected.
Parents/Children
The dependencies between checkpoints are sent out in the reponses in the parents
and children
keys.
They contain IDs of other checkpoints in this Project Line. For instance, if checkpoint 1234 is a parent of checkpoint 6789, the data will be:
[
{
id: 1234,
parents: [],
children: ["6789"]
},
{
id: 6789,
parents: ["1234"],
children: []
},
]
The behavior of a checkpoint is defined by its time_calculation_method
, and the various gaps (min_child_gap
and max_child_gap
).
Validated
It represents whether the checkpoint is validated or not.
Delay
When a checkpoint is validated, the field validated_at
is updated with the exact time of the validation.
Also, the delay of the checkpoint at the time of validation is saved, in days, in the field delay
.
A negative value means the checkpoint was validated early. A positive value means the checkpoint was late by a certain number of days.
GET /api/v1/line_items/:line_item_id/checkpoints
Retrieve all the checkpoints in a Project Line, but only the minimum necessary to build the Project Line workflow
Params
Param name | Description |
---|---|
adjust_dates optional |
If set to true, Winddle will recalculate the checkpoint dates and update the delays according to Today’s date (in UTC timezone) Boolean (true/false) |
GET /api/v1/line_items/:line_item_id/checkpoints/:id
Retrieve all the available information on a checkpoint (including comments and attachments)
POST /api/v1/line_items/:line_item_id/checkpoints
Add a new checkpoint to a project line
Params
Param name | Description |
---|---|
duration required |
Duration (working days) of the task, must be > 0 Must be a Integer |
time_calculation_method optional |
Allows to control the advanced behavior of the checkpoint (time calculation) Must be one of:parent_due_date , fixed_date , floating .
|
min_child_gap optional |
Minimum gap between this CP and its children Must be a Integer |
max_child_gap optional |
Trailing distance from its children (CP must be ‘floating’) Must be a Integer |
begin_at optional |
Date (Y-m-d) for the expected start of the CP Must be a String |
master_checkpoint required |
A Winddle Master Checkpoint. Can be either an ID (unique integer) or the Master Checkpoint name. |
master_checklist optional |
A Winddle Master Checklist. Can be either an ID (unique integer) or the Master Checklist name. |
position optional |
Position of the new checkpoint in the workflow. independent , after:<CheckpointId> , before:<CheckpointId> .
|
PATCH /api/v1/line_items/:line_item_id/checkpoints/:id/validate
Validate an unvalidated checkpoint
Params
Param name | Description |
---|---|
validation_date optional |
Actual date of validation, default to Today Must be a Date |
force_parents_validation optional |
If set to true, will also validate all the unvalidated ancestors with no delay Boolean (true/false) |
ignore_dependencies optional |
If set to true, will ignore dependencies when trying to validating the checkpoint Boolean (true/false) |
force_started_validation optional |
If set to true, will validate automatically all started checkpoints (in progress, delayed) Boolean (true/false) |
PATCH /api/v1/line_items/:line_item_id/checkpoints/:id/validate_with_booking
Validate an unvalidated checkpoint with booking
Params
Param name | Description |
---|---|
booked_on optional |
Actual date of booking Must be a Date |
validation_date optional |
Actual date of validation, default to Today Must be a Date |
PATCH /api/v1/line_items/:line_item_id/checkpoints/:id/validate_with_inspection
Validate an unvalidated checkpoint with a fail/pass status
Params
Param name | Description |
---|---|
validation_date optional |
Actual date of validation, default to Today Must be a Date |
inspection_status required |
The status (empty string for pending, ‘passed’, ‘failed’, ‘with_reserve’) Must be a String |
PATCH /api/v1/line_items/:line_item_id/checkpoints/:id/unvalidate
Unvalidate a validated checkpoint
PATCH /api/v1/line_items/:line_item_id/checkpoints/:id/mark_issue
Mark the checkpoint with issue
PATCH /api/v1/line_items/:line_item_id/checkpoints/:id/resolve_issue
Resolve checkpoint marked with an issue
PATCH /api/v1/line_items/:line_item_id/checkpoints/:id/inspection_status
Update the inspection status of a CP
Params
Param name | Description |
---|---|
inspection_status optional |
The status (empty string for pending, ‘passed’, ‘failed’, ‘with_reserve’) Must be a String |
PATCH /api/v1/line_items/:line_item_id/checkpoints/:id/dates
Change the begin at and duration of a checkpoint
Params
Param name | Description |
---|---|
duration optional |
New duration for the checkpoint (working days) Must be a Integer |
begin_at optional |
New begin at date (ignored if due_date present), format Y-m-d Must be a String |
due_date optional |
New due date, format Y-m-d. Can also be set to |
time_calculation_method optional |
Allows to control the advanced behavior of the checkpoint (time calculation) Must be one of:parent_due_date , fixed_date , floating .
|
update_milestone optional |
Update the date of the associated milestone if any, default to false Boolean (true/false) |
update_parents optional |
If set to true, will perform a reverse scheduling from this checkpoint Boolean (true/false) |
ignore_dependencies optional |
If set to true, will ignore dependencies when trying to update date Boolean (true/false) |
PATCH /api/v1/line_items/:line_item_id/checkpoints/:id/retry
Allow to retry a CP as long as none of its children are validated.
PATCH /api/v1/line_items/:line_item_id/checkpoints/:id/dependencies
Update the dependencies of a particular checkpoint as well as advanced behavior related to dependencies
Params
Param name | Description |
---|---|
time_calculation_method optional |
Allows to control the advanced behavior of the checkpoint (time calculation) Must be one of:parent_due_date , fixed_date , floating .
|
min_child_gap optional |
Minimum gap between this CP and its children Must be a Integer |
max_child_gap optional |
Trailing distance from its children (CP must be ‘floating’) Must be a Integer |
parents optional |
Array of CP ids to be used as new list of parents for the CP Must be an array of any type |
children optional |
Array of CP ids to be used as new list of children for the CP Must be an array of any type |
clear_parents optional |
True to remove all the parents from this CP Boolean (true/false) |
clear_children optional |
True to remove all the children from this CP Boolean (true/false) |
PATCH /api/v1/line_items/:line_item_id/checkpoints/:id/name
Update the Master Checkpoint used for a checkpoint
This method allows to rename CP in a Project Line’s workflow.
Renaming equals changing the Master::Checkpoint used for the Checkpoint.
For convenience, a company admin can use this method to both create a new MCP and assign it to the checkpoint. If the MCP is new, a Master::Checklist must be provided using the master_checklist
param.
Params
Param name | Description |
---|---|
master_checkpoint required |
A Winddle Master Checkpoint. Can be either an ID (unique integer) or the Master Checkpoint name. |
master_checklist optional |
A Winddle Master Checklist. Can be either an ID (unique integer) or the Master Checklist name. |
DELETE /api/v1/line_items/:line_item_id/checkpoints/:id
Remove the checkpoint from the project line's workflow
The checkpoint must not be validated for it to be removed.
If the checkpoint has any children and isn’t independent, then those children will be appended to his first parent’s children.