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

NameType
idInteger (unique)
name (read-only)String
master_checkpoint_idInteger
master_checklist_id (read-only)Integer
statusString
begin_atDate
end_atDate
delayInteger
children (read-only)Array of IDs
parents (read-only)Array of IDs
deliveryBoolean
min_child_gapFloat
max_child_gapInteger
time_calculation_methodString
has_issueBoolean
critical_pathBoolean
validated_atDatetime

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.