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

NameType
idInteger (unique)
nameString (2..100 chars)
source_idString (max 255 chars)
referenceString (unique, max 255 chars)
company_idInteger
archivedBoolean
season_codeString (max 255 chars)
seasonInteger
departure_placeString (max 255 chars)
country_of_originString (max 255 chars)
arrival_placeString (max 255 chars)
payment_conditionsString (max 255 chars)
transportation_modeString (max 255 chars)
incotermString (enum)
project_typeString (enum)
laboratoryString (max 255 chars)
terms_statusString (enum)
terms_validated_atDatetime
created_atDatetime
updated_atDatetime

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, 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
incoterm
optional

Incoterm

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
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:

{
 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
incoterm
optional

Incoterm

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
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:

{
 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/invite

Invite a user on the project

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
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
incoterm
optional

Incoterm

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
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:

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