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
status	String
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).

Status

The status of a checkpoint in the data (key status) isn’t the status visible on Winddle.com (“Delayed”, “Not Started”, etc.) but the validation status: is the checkpoint validated or not.

A checkpoint is validated if status == “validated”. Any other values (possible values include null, empty or “unvalidated”) means the checkpoint isn’t validated.

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` creates a CP without parents/children, `before:3` creates a new CP and set the CP with ID 3 as its child and `after:5` would create the new CP and set it as a child of the CP with ID 5. Must be one of: `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 `current` to represent the current value. Must be a String
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.