Skip to main content

Projects

A Project is linked to a Customer. It has its life cycle (aka workflow) and can be assigned a set of Documents and linked to some Events. The actual prices of a Project are those of its current active Sales Document.

Project methods​

Returns a list of all Projects matching some specified search criteria.

Method​

GET/api/externals/v1/projects

Arguments​

  • winLangID (long): Windows Language Identifier of the resulting data
  • storeID (long): ID of the Store owning the searched Projects
  • contactID (long): ID of the Contact owning the searched Projects
  • contactInternalCode (string): Internal code of the Contact owning the searched Projects
  • internalCode (string): Internal code of the searched Projects
  • code (string): Code of the searched Projects
  • shortCode (string): Short code (6 digits) of the searched Projects
  • keyword (string): Searched keyword
  • minDate (datetime): Minimum date of the searched Projects
  • maxDate (datetime): Maximum date of the searched Projects
  • dateKind (string): Type of date used by the minDate and/or maxDate arguments. Allowed values: "CreationDate", "LastModificationDate"
  • idsOnly (boolean, true): If true, returns only a set of Project IDs
  • detailedView (boolean, false): If true, returns additional information about the matching Projects (e.g. "afterSalesServiceProjects", "consumerProjects", "clonedProject", "statistics", "attachments")

Body​

(none)

Response​

The search service returns a JSON message with the list of items matching the specified search criteria:

{
  "projects": [
    {
      "id": long, 
      "storeID": long,
      "contactID": long,
      "internalCode": string,
      "sellerUserID": long,
      "code": string,
      "shortCode": string,
      "description": string,
      "date": datetime,
      "deliveryDate": datetime,
      "reference": string,
      "status": string,  // (See "Project status possible values" below)
      "notes": string,
      "afterSalesServiceProjects": [ // List of eventual After sales service sub-projects
        {
          "id": long,
          "storeID": long,
          "internalCode": string
        }
      ],
      "parentProject": {	// Eventual Parent project (for After sales services projects only)
        "id": long,
        "storeID": long,
        "internalCode": string
      },
      "consumerProjects": [ // List of eventual Consumer sub-projects (for Promoter projects only)
        {
          "id": long,
          "storeID": long,
          "internalCode": string
        }
      ],
      "promoterProject": {	// Eventual Parent Promoter project
        "id": long,
        "storeID": long,
        "internalCode": string
      },
      "clonedProject": {	// Eventual clone project (for Web projects only)
        "id": long,
        "storeID": long,
        "internalCode": string
      },
      "originalProject": {	// Eventual Web model project (for cloned projects only)
        "id": long,
        "storeID": long,
        "internalCode": string
      },
      "statistics": {
        "workflowLastStatusID": long,
        "workflowLastStatusDescription": string,
        "workflowLastStatusCreationDate": datetime,
        "workflowLastCommercialStatusID": long,
        "workflowLastCommercialStatusDescription": string,
        "workflowLastCommercialStatusCreationDate": datetime,
        "totalPrice": double,
        "totalPriceIT": double,
        "totalDueIT": double,   // ONLY present on “projects/{projectID}”
        "totalPaidIT": double,  // ONLY present on “projects/{projectID}”
        "currencyCode": string,
        "lastDocumentTypeID": long,
        "lastDocumentID": long,
        "lastDocumentCreationDate": datetime,
        "lastDocumentModificationDate": datetime
      },
      "attachments": [
        {
          "id": long,
          "url": string,
          "description": string,
          "fileTypeID": int,
          "fileAssociateTypeID": int,
          "isAttachedToLastDocument": bool,   // Indicates whether the File is directly attached to the Project itself or to its Last Document
          "creationDate": datetime
        }
      ],
      "creationDate": datetime,
      "modificationDate": datetime,
      "isExhibition": bool,
      "isTest": bool
 }
  ],
  "winLangID": long,
  "success": boolean,
  "message": string,
  "rowCount": long
}

Project status possible values​

The project "status" field can take several values:

StatusDescription
""Active / In progress
"A"Cancelled
"B"Blocked
"C"Closed
"W"Pending
"Z"Archived
"M"Archived for 2 years
warning

When a project has been archived for 2 years (standard setting), its documents are not directly accessible. Therefore, information related to the documents ("statistics") will not be included in the response. To access these documents, you must unarchive the project from the project details page by clicking the "Change Project Status" button. (cf. Project Status)

Details​

Returns the details of the Project which projectID is provided in the URL.

Method​

GET/api/externals/v1/projects/{projectID}

Arguments​

  • projectID (long): (provided in the path): ID of the Project to be returned
  • winLangID (long): Windows Language Identifier of the resulting data
  • detailedView (boolean, false): If true, returns additional information about the matching Project (e.g. "afterSalesServiceProjects", "consumerProjects", "clonedProject", "statistics", "attachments")

Body​

(none)

Response​

Same format as the one returned by the « Project search » method.

Create​

Creates a new Project with the specified information.

Method​

POST/api/externals/v1/projects

Arguments​

(none)

Body​

{
  "storeID": long,        // ID of the Store owning the Project to be created
  "contactID": long,      // ID of the Contact owning the Project to be created
  "internalCode": string,
  "sellerUserID": long,   // ID of the User that is the seller of the new Project
  "description": string,  // Name of the project
  "date": datetime,
  "deliveryDate": datetime,
  "reference": string,    // Not currently used by the interface
  "notes": string         // Only used for Web-driven projects or Promoter projects.
}

Response​

{
  "projectID": long, 	// When successful, the created projectID
  "success": boolean,
  "message": string,
  "rowCount": long
}

Update​

Updates the Project which projectID is provided in the URL with the specified information.

Method​

PUT/api/externals/v1/projects/{projectID}

Arguments​

  • projectID (long): (provided in the path): ID of the Project to be updated

Body​

{
  "internalCode": string,
  "sellerUserID": long,		
  "description": string,
  "date": datetime,
  "deliveryDate": datetime,
  "reference": string,
  "notes": string
}

Response​

{
  "projectID": long, 	// When successful, the updated projectID
  "success": boolean,
  "message": string,
  "rowCount": long
}

Clone​

Clones the specified WEB project to another given store.

Method​

PUT/api/externals/v1/projects/{projectID}/cloneToStore

Arguments​

  • projectID (long): ID of the WEB Project to be cloned
  • storeID (long): ID of the destination Store for the cloned Project

Body​

(none)

Response​

{
  "success": boolean,
  "message": string,
  "rowCount": long,
  "projectID": long  // When successful, the created projectID
}

Cancel​

Asks for the cancellation of the Project which projectID is provided in the URL.

Method​

DELETE/api/externals/v1/projects/{projectID}

Arguments​

  • projectID (long): (provided in the path): ID of the Project to be cancelled

Body​

{
  "cancellationNotes": string,	// Comment about the project cancellation
  "cancellationReasonID": string	// ID of the cancellation reason (cf. “Project cancellation reasons” for available values)
}

Response​

{
  "projectID": long, 		// When successful, the cancelled projectID
  "success": boolean,
  "message": string,
  "rowCount": long
}

Cancellation reasons​

Returns the list of available Reasons why a Project could be cancelled.

Method​

GET/api/externals/v1/projects/{cancellationReasons}

Arguments​

  • winLangID (long): Windows Language Identifier of the resulting data

Body​

(none)

Response​

{		
  "cancellationReasons": [
    { 
      "id": long, 			// ID of the Cancellation reason
      "description": string
    }
  ],
  "winLangID": long,
  "success": boolean,
  "message": string,
  "rowCount": long
}

Projects additional methods​

Attachment creation​

Adds an attachment to a project which projectID is provided in the URL.

Method​

POST/api/externals/v1/projects/{projectID}/attachments

Arguments​

  • projectID (long): (provided in the path): ID of the Project owning the attachement to be added
  • attachmentName (string): Name of the attachment to be added with the extension

Body​

The attachment file directly passed as an array of bytes.

Response​

{
  "projectID": long,
  "attachID": long,
  "success": boolean,
  "message": string,
  "rowCount": long
}

Attachment deletion​

Removes the attachment which attachmentID is provided in the URL from the project which projectID is provided in the URL.

Method​

DELETE/api/externals/v1/projects/{projectID}/attachements/{attachmentID}

Arguments​

  • projectID (long): (provided in the path): ID of the Project owning the attachement to be removed
  • attachmentID (long): (provided in the path): ID of the attachment to be removed

Body​

(none)

Response​

{
  "projectID": long,
  "attachID": long,
  "attachPath": string,
  "canRemoveFromDisk": boolean,
  "success": boolean,
  "message": string,
  "rowCount": long
}

Comment creation​

Adds an comment to a project which projectID is provided in the URL.

Method​

POST/api/externals/v1/projects/{projectID}/comment

Arguments​

  • projectID (long): (provided in the path): ID of the Project owning the attachement to be added
  • comment (string): The comment to be added to the project

Body​

(none)

Response​

{
  "projectID": long,
  "success": boolean,
  "message": string,
  "rowCount": long
}

Documents​

Returns a list of all Documents owned by the Project which projectID is provided in the URL and matching some specified search criteria.

Method​

GET/api/externals/v1/projects/{projectID}/documents

Arguments​

  • projectID (long): (provided in the path): ID of the Project owning the searched Documents
  • winLangID (long): Windows Language Identifier of the resulting data
  • documentTypeID (long): ID of the Document type of the searched Documents
  • internalCode (string): Internal code of the searched Documents
  • keyword (string): Searched keyword
  • minDate (datetime): Minimum date of the searched Documents
  • maxDate (datetime): Maximum date of the searched Documents
  • dateKind (string): Type of date used by the minDate and/or maxDate arguments. Allowed values: "CreationDate", "LastModificationDate"
  • idsOnly (boolean, true): If true, returns only a set of Document IDs
  • detailedView (boolean, false): If true, returns additional information about the matching Documents (e.g. "documentLines", "styles", "payments", "attachments")

Body​

(none)

Response​

Same format as the one returned by the « Document search » method.

Events​

Returns a list of all Events owned by the Project which projectID is provided in the URL and matching some specified search criteria.

Method​

GET/api/externals/v1/projects/{projectID}/events

Arguments​

  • projectID (long): (provided in the path): ID of the Project owning the searched Events
  • winLangID (long): Windows Language Identifier of the resulting data
  • eventTypeActionKind (int): Kind of the Event Type of the searched Events
  • keyword (string): Searched keyword
  • minDate (datetime): Minimum date of the searched Events
  • maxDate (datetime): Maximum date of the searched Events
  • dateKind (string): Type of date used by the minDate and/or maxDate arguments. Allowed values: "CreationDate", "LastModificationDate"
  • idsOnly (boolean, true): If true, returns only a set of Event IDs
  • detailedView (boolean, false): If true, returns additional information about the matching Events

Body​

(none)

Response​

Same format as the one returned by the « Event search » method.

Survey update​

Updates the External Survey of the project which ID is specified.

Method​

PUT/api/externals/v1/projects/{projectID}/survey

Arguments​

  • projectID (long): (provided in the path): ID of the Project owning the searched Events

Body​

{
  "survey": string
}

Response​

{
  "success": boolean,
  "message": string,
  "rowCount": long
}

Project workflow methods​

Workflow history​

Returns the full Workflow history for the specified Project, including eventually cancelled transitions.

Method​

GET/api/externals/v1/projects/{projectID}/workflow

Arguments​

  • projectID (long): (provided in the path): ID of the concerned Project
  • winLangID (long): Windows Language Identifier of the resulting data

Body​

(none)

Response​

The service returns a JSON message with the list of all workflow transitions passed by the specified project. The current/active workflow status can be found by searching for the only item with the "isTheCurrentStatus" tag set to true:

{
  "projectID": long,
  "workflowTransitions": [
    { 
      "id": long,                     // ID of the Workflow transition
      "description": string,
      "sequence": long,               // Transition sequence number
      "statusID": long,
      "statusDescription": string,
      "commercialStatusID": long,
      "commercialStatusDescription": string,
      "statusSequenceID": long,
      "isTheCurrentStatus": bool,     // True only for the Active/Current Workflow status
      "creationDate": datetime,
      "isCancelled": bool,            // True only if the transition was cancelled
      "cancellationDate": datetime    // Only if the transition was cancelled
    }
  ],
  "winLangID": long,
  "success": boolean,
  "message": string,
  "rowCount": long
}

Workflow next transitions​

Returns the list of available Workflow transitions that can be executed for the specified Project, assuming its current Workflow status.

Method​

GET/api/externals/v1/projects/{projectID}/workflow/nextTransitions

Arguments​

  • projectID (long): (provided in the path): ID of the concerned Project
  • winLangID (long): Windows Language Identifier of the resulting data

Body​

(none)

Response​

The service returns a JSON message with the list of items matching the specified search criteria:

{
  "projectID": long,
  "workflowTransitions": [
    { 
      "id": long, 			// ID of the Workflow transition
      "description": string,
      "statusID": long,			// ID of the related destination Workflow status
      "statusDescription": string,
      "commercialStatusID": long,
      "commercialStatusDescription": string,
      "statusSequenceID": long
    }
  ],
  "winLangID": long,
  "success": boolean,
  "message": string,
  "rowCount": long
}

Workflow transition execution​

Tries to execute the specified Workflow transition for the given Project. May fail if the current Workflow status of the project doesn't allow this transition.

Method​

PUT/api/externals/v1/projects/{projectID}/workflow/{workflowTransitionID}

Arguments​

  • projectID (long): (provided in the path): ID of the Project to be updated
  • workflowTransitionID (long): (provided in the path): ID of the Workflow transition to be executed on the Project
  • winLangID (long): Windows Language Identifier of the resulting data

Body​

(none)

Response​

{
  "winLangID": long,
  "success": boolean,
  "message": string,
  "rowCount": long,
  "projectID": long,
  "workflowTransitionID": long
}

Workflow status cancellation​

Cancels (when possible) the current Workflow status of the specified Project.

Method​

DELETE/api/externals/v1/projects/{projectID}/workflow

Arguments​

  • projectID (long): (provided in the path): ID of the Project which Workflow status is to be cancelled

Body​

(none)

Response​

{
  "success": boolean,
  "message": string,
  "rowCount": long,
  "projectID": long
}