Projects::lineitems

Manage Project lines within a given Project (create, list, update, delete...)

Description

A Project Line is the link between a Product and a Project. It contains a workflow (multiple checkpoints linked by relationships/constraints), a list of partners, files, comments, etc.

The purpose of a Project is a task to be completed by a certain date, deliver_at. The task itself is described by the checkpoints, but they are not mandatory.

Although only one Product can be associated to a Project Line, multiple variants can be assigned.

Project Line status

The project line doesn’t have a status field as it’s dynamically computed from all the checkpoints.

Project Line base fields

NameType
idInteger (unique)
nameString (2..100 chars)
source_idString (max 255 chars)
referenceString (unique, max 255 chars)
deliver_atDate
cancelledBoolean
manufacturerString (max 255 chars)
incotermsString (enum)
freight_typeString (enum)
total_price (read-only)Float
total_quantity (read-only)Integer
created_atDatetime
updated_atDatetime

Project line enum values

  • freight_type: sea, air, road, rails, intermodal, express
  • incoterms: dat, dap, exw, fca, fas, fob, cfr, cif, cip, cpt, ddp, ddu, dpu

Params format (creation/update)

The project to which the Project Line belongs to is defined by the service URL used to call this service (/projects/project_id/line_items).

For this resource, all the params can be included in a key line_item.

For instance, creating a Project Line for Project “EXAMPLEPROJECT” in XML (POST /api/v1/projects/EXAMPLEPROJECT/line_items):

<line-item>
  <product>TestProduct</product>
  <deliver-at>2015-01-01</deliver-at>
</line-item>

In JSON, the root key is not necessary and the following body would be accepted:

{
  "product": "TestProduct",
  "deliver_at": "2015-01-01"
}

Project Line associated resources

Project

For convenience, some basic information about the Project owning this Project Line are sent out in the project key.

Product

A Project Line is defined by its project, it’s deliver_at and its product.

The selected Product (must be of the same company as the Project) will be sent in the product key.

Please see the Project/LineItems service for more details on the product structure.

Used variants

A Project Line can use none, one or more variants of the selected product.

Those variants are sent in the key used_variants of the product key.

Checkpoints

Please see the LineItems/Checkpoints service for more details on the checkpoints structure.

Custom values (LIST)

This array, sent in the key customs contains an entry for each Custom Fields created in the Project’s company that is attached to a Project Line.

For each of those custom fields, the following keys are provided:

  • id : id of the Custom Field
  • name: name of the Custom FIeld
  • value: value for this Project Line, if any
  • updated_at: Datetime of the update for the value, if any

Roles

There are 2 main roles associated with Project Lines:

  • can_update: can the token owner update fields in this Project Line?

  • can_manage: can the token owner manage (delete, add partners) this Project Line?

Price Quantity

The Prices and Quantities are managed in a separate service.

For reading the values, the Project Line service is enough, however, whenever update is needed, please use the dedicated PriceQuantity service.

Partners

Partners are sent out in the key partners. For each partner, the following information is sent out:

{
  self: Boolean (is this partner the token owner?),
  owner: Boolean (is this partner the project line owner?),

  <Winddle User resource fields>

  partnership: {
    id: Partnership Winddle ID (internal),
    visible: String (position name)
    position: Boolean (is the partner visible?)
  }
}

Another key, pending_partners is used to list all the pending invitations. For those, the following information is sent out:

{
  status: "pending",
  invitation: {
    id: Invitation Winddle ID (internal),
    status: "pending",
    created_at: Datetime (when was the invitation sent?),
    visible: Boolean (visible partner?)
  },
  position: String (position name)
  receiver: User resource (if Winddle User)
  email: String (email used for the invitation)
}

Comments

The comments attached to a project line are sent with the key comments.

For more details, you may refer to the Comments service.

Files

The files attached to a project line are sent with the key attachments.

For more details, you may refer to the Attachments service.

>>>

GET /api/v1/projects/:project_id/line_items/:id

Retrieve everything there is to know about a project line (workflow, files, comments, etc.)

Params

Param name Description
project_id
required

Project id, name or source_id

Must be a String or an Integer
id
required

Project Line id, reference or source_id

Must be a String or an Integer
>>>

POST /api/v1/projects/:project_id/line_items

Create a new project line for the project

Delivery Date

When the delivery date is unknown, the LI can be created with a start_at date. That date will serve as a base to calculate the delivery date. For instance, if a template with a workflow of 50 days is provided, then the delivery date will be set to start_at + 50 working days.

When both start_at and deliver_at are provided, the start_at is used to apply the template, and then the deliver_at is used for the actual Project Line delivery date.

When no dates are provided, then start_at will be set to the current date.

Product

The product to be used for the new Project Line must be put in the product key of the request params.

It’s possible to put a name, a source_id or a Winddle ID in the product field to identify the Product.

It’s also possible to nest the creation of a completely new Product by using the same format as the creation of a new Product in the Product service

Workflow

The workflow to use when creating the Project Line must be set in the template field.

All of the options related to applying workflows can be set in the key template_options.

Either the Winddle ID of the template or its name can be used.

Milestones

If a workflow has a been selected, it’s possible to set the dates for the milestones in that workflow with an array milestones in the key template_options.

The milestones are identified either by their name or combination of master_checkpoint_id and master_checkpoint_index. As a reminder, the master_checkpoint_index is the index of occurence of a master checkpoint in the template, 0 being the first occurence.

Note: if the template has multiple milestones with the same name, only the first date provided will be used for all the milestones. It’s necessary to use the combination of master_checkpoint_id and master_checkpoint_index in those cases.

The date for the milestone is set in the field due_date.

The confirmed_date of the milestone will always be updated with the provided new date, however, the initial_date will only be updated when the update_milestones has been set to true (which is its default value).

Below is an example to set the dates for two different milestones, using both of the available format:

template_options: {
  milestones: [
    {
      name: "MilestoneName",
      due_date: "2015-01-01"
    },
    {
      master_checkpoint_id: 574,
      master_checkpoint_index: 0,
      due_date: "2015-02-01"
    }, ...
  ], other options
}

Checkpoints

If a workflow has a been selected, it’s possible to overwrite (and fix, in the case of a flexible workflows) the duration of specific checkpoints, when the template is applied, with an array checkpoints in the key template_options.

The checkpoints are identified either by their name or combination of master_checkpoint_id and master_checkpoint_index. As a reminder, the master_checkpoint_index is the index of occurence of a master checkpoint in the template, 0 being the first occurence.

Note: if the template has multiple checkpoints with the same name, only the first duration provided will be used for all the checkpoints. It’s necessary to use the combination of master_checkpoint_id and master_checkpoint_index in those cases.

The duration in working days for the checkpoint is set in the field duration.

Below is an example to set the dates for two different checkpoints, using both of the available format:

template_options: {
  checkpoints: [
    {
      name: "CheckpointName",
      duration: 3
    },
    {
      master_checkpoint_id: 574,
      master_checkpoint_index: 0,
      duration: 4
    }, ...
  ], other options
}

Invitations

When creating a Project Line, it’s possible to automatically create a few invitations for external partners.

See the example below for the format to be used:

invites: {
  users: [
    {
      "id": "user1@winddle.com",
      "position": "PositionA"
    },
    {
      "id": "user2@winddle.com"
      "position": "PositionA"
    }
  ],
  "workgroups": ["WorkgroupA"]
}

This would invite 2 users (with PositionA) as well as all the users in the WorkgroupA (with the correct position).

Variants

The variants to be used in the Project Line can be set in the variants key, as an array of Variant identifiers (id, name, source_id) or as an array of attributes (can be mixed).

The attributes are used to create new variants and assign them to this Project line.

For instance, assuming a product with two existing variants: BLUE and RED. To assign the variant BLUE and a new variant called GREEN, the following can be sent in the variants key:

variants: [
  "BLUE",
  {
    name: "GREEN"
  }
]

It’s also possible to use the id in the attribute format to select the variant, for instance:

variants: [
  {
    id: "BLUE"
  }
]

Note that when using the attribute format, if no id has been specified, it’s assumed that a new variant must be created. If the id has been set, it will be used to identify the variant, all the other fields will be ignored (it will not be used to update the variant).

Price Quantity

When creating a Project Line, it’s possible to set the total_price and total_quantity by sending the following data:

"price_quantity": {
  "prices": <em>Total Price</em>,
  "quantities": <em>Total Quantity</em>
}

This follows the same format as the PriceQuantity service, please refer to it for more details on the format of complex prices/quantities.

Examples

Example of a Project Line creation, nesting the creation of a Product.

{
  "reference": "ProjectLine-001",
  "template": "ExampleWorkflow",
  "template_options": {
    "keep_duration": true,
    "keep_fixed": false
  },
  "deliver_at": "2015-01-01",
  "product": {
     "name": "NewProduct",
     "reference": "NewProduct-001"
  }
}

Params

Param name Description
project_id
required

Project id, name or source_id

Must be a String or an Integer
source_id
optional

ID in Customer’s source system (optional, max 255 char.)

Must be a String
reference
optional

internal reference - length must be 255 characters maximum and unique in the scope of the company

Must be a String
manufacturer
optional

length must be 255 characters maximum

Must be a String
deliver_at
optional

LI expected delivery date, format Y-m-d

Must be a String
customs
optional

Custom values for the Project Line

An array of Custom Values for the Product.

Each element of this array should have the following format:

{
 field: The Winddle ID or the Name of the Custom Field
 value: The value for this field
}

Not providing a value for a Field will leave it as blank or keep its current value if any has been set.
variants
optional

Array of Winddle variants (name or ID) - must be part of the used product’s variants

Must be an array of any type
template
optional

The workflow to apply on the Project Line when it’s created

A Winddle Workflow (Checkpoints+Roles) templates. Can be either an ID (unique integer) or the name of the template.
template_options
optional

Used to apply template

Must be a Hash
template_options[end_at]
optional

End date for the workflow, default to deliver_at, format Y-m-d

Must be a String
template_options[start_at]
optional

Start date for the workflow, format Y-m-d

Must be a String
template_options[keep_duration]
optional

Default to false - keep duration of existing CPs

Boolean (true/false)
template_options[keep_fixed]
optional

Default to false - keep starting date of fixed CPs

Boolean (true/false)
template_options[milestones]
optional

Milestones due date constraints

Must be an Array of nested elements
template_options[milestones][name]
optional

Name of the milestone

Must be a String
template_options[milestones][due_date]
required

Due date, format YYYY-MM-DD

Must be a String
template_options[milestones][master_checkpoint_index]
optional

Master checkpoint index in the template for the milestone’s reference checkpoint

Must be a Integer
template_options[milestones][master_checkpoint_id]
optional

Master checkpoint ID for the milestone’s reference checkpoint

Must be a Integer
template_options[checkpoints]
optional

Checkpoints duration constraints

Must be an Array of nested elements
template_options[checkpoints][name]
optional

Name of the checkpoint

Must be a String
template_options[checkpoints][duration]
required

Duration in working days

Must be a Integer
template_options[checkpoints][master_checkpoint_index]
optional

Master checkpoint index in the template

Must be a Integer
template_options[checkpoints][master_checkpoint_id]
optional

Master checkpoint ID

Must be a Integer
product
required 		A Winddle Product. Can be either a product ID (unique integer) or a product Name (which must be unique within the company).
invites
optional 		An object that describes invitations on a line item. To describe an invitation, you need a parameter to indentify a user (id or email) and a position (id or name). Hopefully, that's also the structure of a workgroup, so workgroups can also be used in invitations. Format: { workgroups: [, ...], users: [{ id: , position: }, ...] }
price_quantity
optional 		See LineItem::PriceQuantity
>>>

PUT /api/v1/projects/:project_id/line_items/:id

Update one or multiple values in the project line

Overwrite partners

For a project line manager, it’s possible to simply overwrite the list of partners by providing a complete list to Winddle. Winddle will compare this new list to the current list of partners and pending invitations, and:

  • Remove partners that are not in the new list
  • Cancel invitations for pending partners who are not in the new list
  • Invite partners that are in the new list but aren’t already partners

The format for the partners key allow to define a partner by its email or its Winddle ID, as well as set the position (optional) for new partners (will not be used if the user is already a partner of the company).

  partners: [
    { user: "email@email.com", position: "Position Name" },
    { user: 12, position: "Position Name" },
    { user: "email@email.com" },
    { user: 12 },
    "email@email.com",
    12,
  ]

It’s also possible to remove all the partners from the project line, only keeping the project line managers, by sending:

  partners: 'clear'

Params

Param name Description
project_id
required

Project id, name or source_id

Must be a String or an Integer
id
required

Project Line id, reference or source_id

Must be a String or an Integer
source_id
optional

ID in Customer’s source system (optional, max 255 char.)

Must be a String
reference
optional

internal reference - length must be 255 characters maximum and unique in the scope of the company

Must be a String
manufacturer
optional

length must be 255 characters maximum

Must be a String
deliver_at
optional

LI expected delivery date, format Y-m-d

Must be a String
customs
optional

Custom values for the Project Line

An array of Custom Values for the Product.

Each element of this array should have the following format:

{
 field: The Winddle ID or the Name of the Custom Field
 value: The value for this field
}

Not providing a value for a Field will leave it as blank or keep its current value if any has been set.
variants
optional

Array of Winddle variants (name or ID) - must be part of the used product’s variants

Must be an array of any type
template
optional

The workflow to apply on the Project Line when it’s created

A Winddle Workflow (Checkpoints+Roles) templates. Can be either an ID (unique integer) or the name of the template.
template_options
optional

Used to apply template

Must be a Hash
template_options[end_at]
optional

End date for the workflow, default to deliver_at, format Y-m-d

Must be a String
template_options[start_at]
optional

Start date for the workflow, format Y-m-d

Must be a String
template_options[keep_duration]
optional

Default to false - keep duration of existing CPs

Boolean (true/false)
template_options[keep_fixed]
optional

Default to false - keep starting date of fixed CPs

Boolean (true/false)
template_options[milestones]
optional

Milestones due date constraints

Must be an Array of nested elements
template_options[milestones][name]
optional

Name of the milestone

Must be a String
template_options[milestones][due_date]
required

Due date, format YYYY-MM-DD

Must be a String
template_options[milestones][master_checkpoint_index]
optional

Master checkpoint index in the template for the milestone’s reference checkpoint

Must be a Integer
template_options[milestones][master_checkpoint_id]
optional

Master checkpoint ID for the milestone’s reference checkpoint

Must be a Integer
template_options[checkpoints]
optional

Checkpoints duration constraints

Must be an Array of nested elements
template_options[checkpoints][name]
optional

Name of the checkpoint

Must be a String
template_options[checkpoints][duration]
required

Duration in working days

Must be a Integer
template_options[checkpoints][master_checkpoint_index]
optional

Master checkpoint index in the template

Must be a Integer
template_options[checkpoints][master_checkpoint_id]
optional

Master checkpoint ID

Must be a Integer
partners
optional

Array of user & position (optional) to overwrite the list of partners (non-managers)

Must be an array of any type
clear_variants
optional

When set to true, will clear all the variants

Boolean (true/false)
>>>

GET /api/v1/projects/:project_id/line_items/:id/non_filled_positions

Helper to retrieve the list of positions that are currently not filled by partners for this LI

Params

Param name Description
project_id
required

Project id, name or source_id

Must be a String or an Integer
id
required

Project Line id, reference or source_id

Must be a String or an Integer
>>>

PATCH /api/v1/projects/:project_id/line_items/:id/apply_template

Apply an existing workflow template to this line

Params

Param name Description
template
required 		A Winddle Workflow (Checkpoints+Roles) templates. Can be either an ID (unique integer) or the name of the template.
source_line_item_id
optional

Can be set to self to reuse current template, or to the ID of another Project Line to use it as template (will overwrite template param)

Must be a String or an Integer
milestones
optional

Milestones due date constraints

Must be an Array of nested elements
milestones[name]
optional

Name of the milestone

Must be a String
milestones[due_date]
required

Due date, format YYYY-MM-DD

Must be a String
milestones[master_checkpoint_index]
optional

Master checkpoint index in the template for the milestone’s reference checkpoint

Must be a Integer
milestones[master_checkpoint_id]
optional

Master checkpoint ID for the milestone’s reference checkpoint

Must be a Integer
checkpoints
optional

Checkpoints duration constraints

Must be an Array of nested elements
checkpoints[name]
optional

Name of the checkpoint

Must be a String
checkpoints[duration]
required

Duration in working days

Must be a Integer
checkpoints[master_checkpoint_index]
optional

Master checkpoint index in the template

Must be a Integer
checkpoints[master_checkpoint_id]
optional

Master checkpoint ID

Must be a Integer
keep_duration
optional

Default to false - keep duration of existing CPs

Boolean (true/false)
keep_fixed
optional

Default to false - keep starting date of fixed CPs

Boolean (true/false)
start_at
optional

Optional - request a specific starting date for the first CP

Must be a Date
end_at
optional

Default to the project line’s due date, request a specific due date for the last CP

Must be a Date
update_milestones
optional

Default to true, update the milestones of the line item with either the provided dates or the relevant CP’s due dates

Boolean (true/false)
validate_delayed
optional

Default to false, validate all delayed CPs after applying the workflow

Boolean (true/false)
project_id
required

Project id, name or source_id

Must be a String or an Integer
id
required

Project Line id, reference or source_id

Must be a String or an Integer
>>>

PATCH /api/v1/projects/:project_id/line_items/:id/close

Force-close the project line

Params

Param name Description
deliver_at
optional

Real deliver_at of delivery CP (default to current deliver_at), format Y-m-d

Must be a String
>>>

PATCH /api/v1/projects/:project_id/line_items/:id/cancel

Cancel the project line

Params

Param name Description
project_id
required

Project id, name or source_id

Must be a String or an Integer
id
required

Project Line id, reference or source_id

Must be a String or an Integer
>>>

PATCH /api/v1/projects/:project_id/line_items/:id/uncancel

Uncancel the project line

Params

Param name Description
project_id
required

Project id, name or source_id

Must be a String or an Integer
id
required

Project Line id, reference or source_id

Must be a String or an Integer
>>>

DELETE /api/v1/projects/:project_id/line_items/:id

Delete the project line from the project

Params

Param name Description
project_id
required

Project id, name or source_id

Must be a String or an Integer
id
required

Project Line id, reference or source_id

Must be a String or an Integer