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.

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
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)
incoterms	String (enum)
order_type	String
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
incoterms: dat, dap, exw, fca, fas, fob, cfr, cif, cip, cpt, ddp, ddu, dpu

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 the owner 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 Field
name: name of the Custom FIeld
value: value for this Project, if any
updated_at: Datetime of the update for the value, if any

Supported Formats

JSON XML

>>>

GET /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	Winddle ID of a warehouse Must be a String or an Integer
incoterms optional	Incoterms Must be one of: `dat`, `dap`, `exw`, `fca`, `fas`, `fob`, `cfr`, `cif`, `cip`, `cpt`, `ddp`, `ddu`, `dpu`.
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
order_type optional	Order type Must be a String
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: `{ 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.
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
incoterms_place optional	Incoterms place Must be a String

>>>

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	Winddle ID of a warehouse Must be a String or an Integer
incoterms optional	Incoterms Must be one of: `dat`, `dap`, `exw`, `fca`, `fas`, `fob`, `cfr`, `cif`, `cip`, `cpt`, `ddp`, `ddu`, `dpu`.
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
order_type optional	Order type Must be a String
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: `{ 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.
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
incoterms_place optional	Incoterms place Must be a String

>>>

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/uncancel

Uncancel the project and unarchive it

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