Projects
Manage my company projects (create, list, update, delete...)
Description
The main function/purpose of Projects is to link together multiple Project Lines.
Project in themselves are mostly used to describe the context of a Project Line, by setting things such as the incoterms, the supplier, the final customer, etc.
In most cases, a Project Line is completely specified by its Project name/reference, the Product it uses and its Delivery Date.
Usually, a Project in Winddle will represent an “Order” or a “Design/Conception project”. The appropriate project_type
may be selected to differentiate them.
Params format (creation/update)
For this resource, all the params can be included in a key project
.
For instance, creating a Project in XML (POST /api/v1/projects):
<project>
<name>TestProject</name>
<reference>TestProject-001</reference>
<line-items>
<line-item>
<deliver-at>2015-01-01</deliver-at>
<product>ExistingProduct</product>
</line-item>
</line-items>
</project>
Please note the extra line-item
key in the line-items
array.
In JSON, the root key is not necessary and the following body would be accepted:
{
"name": "TestProject",
"reference": "TestProject-001",
"line_items": [{
"deliver_at": "2015-01-01",
"product": "ExistingProduct"
}]
}
Project base fields
Name | Type |
---|---|
id | Integer (unique) |
name | String (2..100 chars) |
source_id | String (max 255 chars) |
reference | String (unique, max 255 chars) |
company_id | Integer |
archived | Boolean |
season_code | String (max 255 chars) |
season | Integer |
warehouse | String (max 255 chars) |
warehouse_code | String (max 255 chars) |
departure_place | String (max 255 chars) |
country_of_origin | String (max 255 chars) |
arrival_place | String (max 255 chars) |
payment_conditions | String (max 255 chars) |
transportation_mode | String (max 255 chars) |
incoterm | String (enum) |
project_type | String (enum) |
laboratory | String (max 255 chars) |
terms_status | String (enum) |
terms_validated_at | Datetime |
created_at | Datetime |
updated_at | Datetime |
Project enum values
- term_status: preparing, pending, validated
- project_type: order, development, mixed
- incoterm: dat, dap, exw, fca, fas, fob, cfr, cif, cip, cpt, ddp, ddu
Project associated resources
Company
The field company_id
will contain the id of the company owning this Project.
It is the same company as the Project’s project manager(s) company.
Supplier, Final Customer, Factory and Forwarder
Each of those fields are Contacts (of companies, not users). The contact must be visible to the project’s company.
Winddle offers an API shortcut to create a contact just from its name using the params supplier_name
, forwarder_name
, final_customer_name
and factory_name
. If a contact with the same name already exists, it will be used instead of creating a new one.
To clear the value in the field, send a true value in the name of the field with an added _clear
(ex: forwarder_clear
).
Project Manager(s)
There are two possible project managers for a Project:
- The
owner
, who creates the Project - The
buyer
(shown as ‘Project Manager’ on Winddle), who is set to the same value as theowner
field by default but can be changed at any time.
Both of those users have full control over the project and its project lines.
Project lines
A Project can have multiple project lines.
Please see the Project/LineItems service for more details on the project lines 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.
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, if anyupdated_at
: Datetime of the update for the value, if any
Supported Formats
JSON XMLGET /api/v1/projects/export
Params
Param name | Description |
---|---|
fields optional |
List of fields to export Must be an array of any type |
filter optional |
Filter to apply on the list of Projects Param for filters |
export_checkpoints optional |
Export CP information as well (simple = just a date, detailed = 4 columns) Must be one of:none , simple , detailed .
|
GET /api/v1/projects/export_delayed
Params
Param name | Description |
---|---|
fields optional |
List of fields to export Must be an array of any type |
filter optional |
Filter to apply on the list of Projects Param for filters |
export_checkpoints optional |
Export CP information as well (simple = just a date, detailed = 4 columns) Must be one of:none , simple , detailed .
|
GET /api/v1/projects
Retrieve the basic details of projects and the workflow/fields of its project lines
As a normal Winddle user, this service will return all the Projects that the user is directly working on as a partner.
As a Product owner, this service will return all the Projects of the token owner’s company, regardless of whether the token owner’s is a partner or not.
Params
Param name | Description |
---|---|
filter optional |
Filters to apply on the list of Project Lines to return Param for filters |
GET /api/v1/projects/:id
Retrieve the details of a project as well as the basic details of its project lines
Params
Param name | Description |
---|---|
id required |
Project id, name or source_id Must be a String or an Integer |
partial optional |
Partial data for line_items key? (default to false) Boolean (true/false) |
adjust optional |
If true, adjust the dates to take into account delays (default to false) Boolean (true/false) |
POST /api/v1/projects
Create a new Project
The project company and owner (Project Manager) will be set to the current token’s owner / company.
It’s possible to create multiple project lines with this service.
See the Project/LineItems service for a description of the necessary fields necessary to create a Project Line.
Invitations
When creating a Project, 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).
It’s equivalent to inviting them on each project lines individually.
Params
Param name | Description |
---|---|
name required |
Project name Must be a String |
owner optional |
Project’s main project manager (owner), if not set, default to current user. Has to be an employee of the Project’s company. A Winddle User. Can be either a user ID (unique integer) or a user Email. |
line_items optional |
An array of Project Line to be created and attached to the new project (at least one) Must be an array of any type |
source_id optional |
ID in Customer’s source system (optional, max 255 char.) Must be a String |
reference optional |
Project reference Must be a String |
season optional |
Project season Must be a String or an Integer |
warehouse optional |
Warehouse (name) Must be a String |
warehouse_code optional |
Warehouse (code) Must be a String |
incoterm optional |
Incoterm Must be one of:dat , dap , exw , fca , fas , fob , cfr , cif , cip , cpt , ddp , ddu .
|
departure_place optional |
Departure place Must be a String |
country_of_origin optional |
Country of origin Must be a String |
arrival_place optional |
Arrival place Must be a String |
transportation_mode optional |
Transportation mode Must be a String |
payment_conditions optional |
Payment conditions Must be a String |
project_type optional |
Project type Must be one of:order , development , mixed .
|
laboratory optional |
Laboratory Must be a String |
final_customer optional |
Must be a String or an Integer |
final_customer_name optional |
Final Customer name when there are no matching Winddle Company Contact Must be a String |
final_customer_clear optional |
Reset the final customer Boolean (true/false) |
factory optional |
Must be a String or an Integer |
factory_name optional |
Factory name when there are no matching Winddle Factory Contact Must be a String |
factory_clear optional |
Reset the factory Boolean (true/false) |
supplier_name optional |
Supplier name when there are no matching Winddle Contact Must be a String |
supplier optional |
Must be a String or an Integer |
supplier_clear optional |
Reset the supplier Boolean (true/false) |
forwarder_name optional |
Forwarder name when there are no matching Winddle Contact Must be a String |
forwarder optional |
Must be a String or an Integer |
forwarder_clear optional |
Reset the forwarder Boolean (true/false) |
buyer optional |
Project’s secondary project manager. Has to be an employee of the Project’s company A Winddle User. Can be either a user ID (unique integer) or a user Email. |
customs optional |
Custom values for the Project 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. |
invoice_version optional |
{id: id of a temp attachment or invoice version, temp: true if temp attachment, type: standard or proformat} Must be a Hash |
PUT /api/v1/projects/:id
Update a project details (one or more attributes)
Params
Param name | Description |
---|---|
id required |
Project id, name or source_id Must be a String or an Integer |
name optional |
Project name Must be a String |
owner optional |
Project’s main project manager (owner). Has to be an employee of the Project’s company. A Winddle User. Can be either a user ID (unique integer) or a user Email. |
source_id optional |
ID in Customer’s source system (optional, max 255 char.) Must be a String |
reference optional |
Project reference Must be a String |
season optional |
Project season Must be a String or an Integer |
warehouse optional |
Warehouse (name) Must be a String |
warehouse_code optional |
Warehouse (code) Must be a String |
incoterm optional |
Incoterm Must be one of:dat , dap , exw , fca , fas , fob , cfr , cif , cip , cpt , ddp , ddu .
|
departure_place optional |
Departure place Must be a String |
country_of_origin optional |
Country of origin Must be a String |
arrival_place optional |
Arrival place Must be a String |
transportation_mode optional |
Transportation mode Must be a String |
payment_conditions optional |
Payment conditions Must be a String |
project_type optional |
Project type Must be one of:order , development , mixed .
|
laboratory optional |
Laboratory Must be a String |
final_customer optional |
Must be a String or an Integer |
final_customer_name optional |
Final Customer name when there are no matching Winddle Company Contact Must be a String |
final_customer_clear optional |
Reset the final customer Boolean (true/false) |
factory optional |
Must be a String or an Integer |
factory_name optional |
Factory name when there are no matching Winddle Factory Contact Must be a String |
factory_clear optional |
Reset the factory Boolean (true/false) |
supplier_name optional |
Supplier name when there are no matching Winddle Contact Must be a String |
supplier optional |
Must be a String or an Integer |
supplier_clear optional |
Reset the supplier Boolean (true/false) |
forwarder_name optional |
Forwarder name when there are no matching Winddle Contact Must be a String |
forwarder optional |
Must be a String or an Integer |
forwarder_clear optional |
Reset the forwarder Boolean (true/false) |
buyer optional |
Project’s secondary project manager. Has to be an employee of the Project’s company A Winddle User. Can be either a user ID (unique integer) or a user Email. |
customs optional |
Custom values for the Project 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. |
invoice_version optional |
{id: id of a temp attachment or invoice version, temp: true if temp attachment, type: standard or proformat} Must be a Hash |
PATCH /api/v1/projects/:id/archive
Archive a project
Params
Param name | Description |
---|---|
id required |
Project id, name or source_id Must be a String or an Integer |
patch /api/v1/projects/:id/cancel
Cancel all the project lines and archive the project
Params
Param name | Description |
---|---|
id required |
Project id, name or source_id Must be a String or an Integer |
PATCH /api/v1/projects/:id/unarchive
Unarchive a project
Params
Param name | Description |
---|---|
id required |
Project id, name or source_id Must be a String or an Integer |
DELETE /api/v1/projects/:id
Destroy a project permanently from Winddle
Params
Param name | Description |
---|---|
id required |
Project id, name or source_id Must be a String or an Integer |
PATCH /api/v1/projects/:id/join
Join a project
Params
Param name | Description |
---|---|
id required |
Project id, name or source_id Must be a String or an Integer |
PATCH /api/v1projects/:id/leave
Leave a project
Params
Param name | Description |
---|---|
id required |
Project id, name or source_id Must be a String or an Integer |
PATCH /api/v1/projects/:id/validate
Validate the PO terms
Params
Param name | Description |
---|---|
invoice_version optional |
{id: id of a temp attachment or invoice version, temp: true if temp attachment, type: standard or proformat} Must be a Hash |
PATCH /api/v1/projects/:id/confirm
Validate the order delivery schedule