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
Name | Type |
---|---|
id | Integer (unique) |
name | String (2..100 chars) |
source_id | String (max 255 chars) |
reference | String (unique, max 255 chars) |
deliver_at | Date |
locked | Boolean |
cancelled | Boolean |
manufacturer | String (max 255 chars) |
incoterms | String (enum) |
freight_type | String (enum) |
locked | Boolean |
total_price (read-only) | Float |
total_quantity (read-only) | Integer |
created_at | Datetime |
updated_at | Datetime |
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 Fieldname
: name of the Custom FIeldvalue
: value for this Project Line, if anyupdated_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:
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: [ |
price_quantity optional |
See LineItem::PriceQuantity |
locked optional |
True means no CP params can be updated (default to false) Boolean (true/false) |
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:
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 |
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/lock
Lock the project line workflow changes on Winddle.com
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/unlock
Unlock the project line workflow changes on Winddle.com
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/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 |