API TUTORIAL – CREATE CONSTRUCTIBLES

Intro

This document provides a step-by-step guide on how to create an assembly using the produuz.it API V2. The assembly creation involves several steps, including project and batch creation, finding an assembly design, and making a call to the assemblies endpoint with the required UUIDs. The workflow for modules is similar.

INFO

The base URL for the produuz.it API V2 is: https://produuz.it/api/v2/

Step 1: Project Creation/Retrieval

ALL RETRIEVAL

First of all, if you don't have the project uuid, you have to find it based on your data. You can fetch all the projects and find it yourself:

Endpoint: /api/v2/company/projects/

Method: GET.
Request Body: Empty.
Response: List of project objects.

Example Response Payload

json

[
  {
    "ifc_parsing_setup": "b3f44b0e-2e75-45ad-8a5d-148f70883fe1",
    "btl_parsing_setup": null,
    "uuid": "0549be70-e2f5-4227-86a1-bfdb229e5460",
    "created": "2023-10-19T09:04:07.222371Z",
    "modified": "2023-10-19T09:04:07.222393Z",
    "name": "TEST_HOUSE",
    "client_name": "connectinq",
    "project_number": "test_1",
    "super_project": "Test_Street",
    "phases": ["Phase_1"],
    "meta": {},
    "delivery_date": null,
    "start_date": null,
    "archived": false
  },
  {
    //... other project
  },
  {
    //... other project
  }
]

[
  {
    "ifc_parsing_setup": "b3f44b0e-2e75-45ad-8a5d-148f70883fe1",
    "btl_parsing_setup": null,
    "uuid": "0549be70-e2f5-4227-86a1-bfdb229e5460",
    "created": "2023-10-19T09:04:07.222371Z",
    "modified": "2023-10-19T09:04:07.222393Z",
    "name": "TEST_HOUSE",
    "client_name": "connectinq",
    "project_number": "test_1",
    "super_project": "Test_Street",
    "phases": ["Phase_1"],
    "meta": {},
    "delivery_date": null,
    "start_date": null,
    "archived": false
  },
  {
    //... other project
  },
  {
    //... other project
  }
]

FILTERED RETRIEVAL

Also it's possible to make a query to filter them based on your params:

Endpoint: /api/v2/company/projects/?name=my_project

This will return also a list, even if there is only one project that matches the query.

CREATION

If the project does not exist, you should create it. To create a project:

Endpoint: /api/v2/company/projects/

Method: POST.
Request Body: JSON object with project details.
Response: Project details including the project UUID.

Example Request Payload

json

{
  "name": "TEST_HOUSE",
  "super_project": "Test_Street",
  "client_name": "connectinq",
  "project_number": "test_1",
  "delivery_date": null,
  "start_date": null,
  "standard_library": false
}

{
  "name": "TEST_HOUSE",
  "super_project": "Test_Street",
  "client_name": "connectinq",
  "project_number": "test_1",
  "delivery_date": null,
  "start_date": null,
  "standard_library": false
}

Example Response Payload

json

{
  "ifc_parsing_setup": "b3f44b0e-2e75-45ad-8a5d-148f70883fe1",
  "btl_parsing_setup": null,
  "uuid": "0549be70-e2f5-4227-86a1-bfdb229e5460",
  "created": "2023-10-19T09:04:07.222371Z",
  "modified": "2023-10-19T09:04:07.222393Z",
  "name": "TEST_HOUSE",
  "client_name": "connectinq",
  "project_number": "test_1",
  "super_project": "Test_Street",
  "phases": ["Phase_1"],
  "meta": {},
  "delivery_date": null,
  "start_date": null,
  "archived": false
}

{
  "ifc_parsing_setup": "b3f44b0e-2e75-45ad-8a5d-148f70883fe1",
  "btl_parsing_setup": null,
  "uuid": "0549be70-e2f5-4227-86a1-bfdb229e5460",
  "created": "2023-10-19T09:04:07.222371Z",
  "modified": "2023-10-19T09:04:07.222393Z",
  "name": "TEST_HOUSE",
  "client_name": "connectinq",
  "project_number": "test_1",
  "super_project": "Test_Street",
  "phases": ["Phase_1"],
  "meta": {},
  "delivery_date": null,
  "start_date": null,
  "archived": false
}

(may contain more data in some cases)

In the "uuid" param of the response you have your new project UUID.

Note that you get a list of available "phases" in the project.

If you are looking for standard libraries (only for later assembly_design retrieval), you have to change the endpoint to: /api/v2/company/standard_libraries/ But the workflow is still the same.

Step 2: Batch Creation/Retrieval

In this step, it's important to make clear some ideas about produuz.it batches:

An assembly/module needs always a batch. It's not possible to work without batches. So, if the company wants to work without batches, placeholding batches are created.
The phase is string. The default Phase_1 can be set for simplicity.
The production line is set to the batch, not to the assembly/module itself. So at least one batch per desired production line will be needed in a project. (Ex: BATCH_PL1, BATCH_PL2, BATCH_PL3,…).

Of course the company can freely organize phases and batches at their own taste.

RETRIEVAL

To retrieve batches, use the following endpoint:

Endpoint: /api/v2/constructibles/batches/?project=<project_uuid>

Method: GET.
Request Body: Empty.
Response: List of batches including uuids.

CREATION

To create a batch object, use the following endpoint:

Endpoint: /api/v2/constructibles/batches/

Method: POST.
Request Body: JSON object with batch details including the project UUID.
Response: Batch details including the batch UUID.

Example Request Payload

json

{
  "project": "0549be70-e2f5-4227-86a1-bfdb229e5460",
  "phase": "Phase_1",
  "name": "Batch_1"
}

{
  "project": "0549be70-e2f5-4227-86a1-bfdb229e5460",
  "phase": "Phase_1",
  "name": "Batch_1"
}

Example Response Payload

json

{
  "project": "0549be70-e2f5-4227-86a1-bfdb229e5460",
  "production_line": null,
  "uuid": "94d9c646-8e2d-4ac0-b073-aff1aed2b3d7",
  "created": "2023-10-19T09:24:12.082495Z",
  "modified": "2023-10-19T09:24:12.082514Z",
  "name": "Batch_1",
  "phase": "Phase_1",
  "priority": 0,
  "show_in_viewer": true,
  "start_date": null,
  "delivery_date": null,
  "pl_ordering": 0,
  "company_calculated_time": 0,
  "use_ct_schedule": false,
  "task_subset": ""
}

{
  "project": "0549be70-e2f5-4227-86a1-bfdb229e5460",
  "production_line": null,
  "uuid": "94d9c646-8e2d-4ac0-b073-aff1aed2b3d7",
  "created": "2023-10-19T09:24:12.082495Z",
  "modified": "2023-10-19T09:24:12.082514Z",
  "name": "Batch_1",
  "phase": "Phase_1",
  "priority": 0,
  "show_in_viewer": true,
  "start_date": null,
  "delivery_date": null,
  "pl_ordering": 0,
  "company_calculated_time": 0,
  "use_ct_schedule": false,
  "task_subset": ""
}

UPDATING

Any of the received fields of the batch object can be passed in the POST create request. Also they can be later updated alone with a PUT request. So for example, if you want to update the batch with a new production line, you can make the following request:

Endpoint: /api/v2/constructibles/batches/94d9c646-8e2d-4ac0-b073-aff1aed2b3d7/

Method: PUT.
Request Body: partial JSON object.
Response: Full batch.

Example Request Payload

json

{
    "production_line": “b6e25a9c-bf2f-4838-ac1d-a204932a698e”
}

{
    "production_line": “b6e25a9c-bf2f-4838-ac1d-a204932a698e”
}

And remember that you could also pass the production line in the creation POST request.

Step 3: Assembly Design Retrieval

Find an assembly design to reference, either from the current project or another project. An standard library is considered also a project. So for standard panels you need to pass the standard library uuid as a project uuid also.

Endpoint: /v2/constructibles/assembly_designs/?project=<project_uuid_or_stdlib_uuid>

Method: GET to retrieve assembly designs.

Query Parameters: Project UUID if filtering by project.
Response: List of assembly designs with UUIDs.

If needed, you can also add the name query filter to get a shorter list:

Endpoint: /api/v2/constructibles/assembly_designs/?project=<project_uuid>&name=<design_name>

Step 4: Assembly Creation

You are ready to create an assembly once you have:

design : Assembly design UUID.
batch : Batch UUID.

Also you may want to add:

client_order_id : Order ID coming from external management system.
scheduled_prod_date : Scheduled date for the production.
priority : Integer that represent the priority of the assembly in the batch, or in the day for companies that manage production by date.

Make a call to the assemblies endpoint with the data:

Endpoint: /api/v2/constructibles/assemblies/

Method: POST.
Request Body: JSON object with at least basic data.
Response: The full assembly json objet.

Example Request Payload

json

{
  "batch": "94d9c646-8e2d-4ac0-b073-aff1aed2b3d7",
  "design": "b715f3b3-7007-47d2-872b-20eb46d383a7",
  "scheduled_prod_date": "2023-10-19",
  "client_order_id": "or863-12"
}

{
  "batch": "94d9c646-8e2d-4ac0-b073-aff1aed2b3d7",
  "design": "b715f3b3-7007-47d2-872b-20eb46d383a7",
  "scheduled_prod_date": "2023-10-19",
  "client_order_id": "or863-12"
}

Example Response Payload

json

{
  "batch": "94d9c646-8e2d-4ac0-b073-aff1aed2b3d7",
  "module": null,
  "design": "b715f3b3-7007-47d2-872b-20eb46d383a7",
  "uuid": "8f43556f-ee33-4aaf-b0b8-028f3d3d46dd",
  "created": "2023-06-03T22:58:49.281997Z",
  "modified": "2023-06-05T08:02:21.160681Z",
  "status": "waiting",
  "stations_status": {},
  "meta": {},
  "priority": 48,
  "scheduled_prod_date": "2023-10-19",
  "client_order_id": "or863-12",
  "parent_assembly": null
}

{
  "batch": "94d9c646-8e2d-4ac0-b073-aff1aed2b3d7",
  "module": null,
  "design": "b715f3b3-7007-47d2-872b-20eb46d383a7",
  "uuid": "8f43556f-ee33-4aaf-b0b8-028f3d3d46dd",
  "created": "2023-06-03T22:58:49.281997Z",
  "modified": "2023-06-05T08:02:21.160681Z",
  "status": "waiting",
  "stations_status": {},
  "meta": {},
  "priority": 48,
  "scheduled_prod_date": "2023-10-19",
  "client_order_id": "or863-12",
  "parent_assembly": null
}

Bulk Create

Constructibles can be created by a single request:

Endpoint: /api/v2/constructibles/actuals/bulk_create/

Method: POST.
Request Body: JSON object with constructible creation payload. (Admits single object object array).
Response: List of statuses for each constructible creation attempt.

Custom schemas to be passed as URL query params.

Custom schema 1 (hm_sap)

This schema will attempt to create the constructible and get-or-create its related objects (project, batches, production lines, …). Expects the following props:

project : Project number. Will pick this project, or create if does not exist.
projectname : Will be used only if project creation is needed.
stdlib_number: Standard library number. Will pick this stdlib to fetch the design. Don't pass this param, or pass it as null if the design is project specific.
article : Assembly/Module design name. Will be used to get the design from the project. Will be created if needed for later file uploads through the web interface.
ordernr : Used to fill the client_order_id in our system (a client order ID that comes from an external management system).
meta : Used to fill the client_meta in our system. This meta is shown in the design detail and can be used for customizations.
operations : This is a list of objects. The nr code has to match the Client ID of the Production Line in produuz.it. If no PL is found, PL is not set. Otherwise the first match will be used. The matched operation is used:
- workcenter : This Production line name is ignored since the nr is enough to fetch the correct PL.
- date : This will be used as the "scheduled_prod_date" for the constructible, the expected date for production from the client.

Endpoint: /api/v2/constructibles/actuals/bulk_create/?schema=hm_sap

Example Request Payload

json

[
  {
    "ordernr": "123",
    "article": "MW-D11-R",
    "project": "23-555",
    "projectname": "Example_Name",
    "stdlib_number": "std123456",
    "meta": {
      "project": "23-555",
      "wbs": ""
    },
    "operations": [
      {
        "nr": "30",
        "workcenter": "WAND",
        "date": "2023-10-08T14:32:17.232Z"
      }
    ]
  }
  // { another object },
  // { another object }
]

[
  {
    "ordernr": "123",
    "article": "MW-D11-R",
    "project": "23-555",
    "projectname": "Example_Name",
    "stdlib_number": "std123456",
    "meta": {
      "project": "23-555",
      "wbs": ""
    },
    "operations": [
      {
        "nr": "30",
        "workcenter": "WAND",
        "date": "2023-10-08T14:32:17.232Z"
      }
    ]
  }
  // { another object },
  // { another object }
]

Example Response Payload

json

[
  {
    "client_order_id": "3321",
    "result": "created",
    "uuid": "the-uuid-v4",
    "level": "assembly",
    "created_project": false,
    "created_design": false,
    "created_batch": true
  },
  {
    "client_order_id": "3322",
    "result": "failed",
    "detail": "Something went wrong here"
  }
  // { ...third object }
]

[
  {
    "client_order_id": "3321",
    "result": "created",
    "uuid": "the-uuid-v4",
    "level": "assembly",
    "created_project": false,
    "created_design": false,
    "created_batch": true
  },
  {
    "client_order_id": "3322",
    "result": "failed",
    "detail": "Something went wrong here"
  }
  // { ...third object }
]

API TUTORIAL – CREATE CONSTRUCTIBLES ​

Intro ​

Step 1: Project Creation/Retrieval ​

ALL RETRIEVAL ​

FILTERED RETRIEVAL ​

CREATION ​

Step 2: Batch Creation/Retrieval ​

RETRIEVAL ​

CREATION ​

UPDATING ​

Step 3: Assembly Design Retrieval ​

Step 4: Assembly Creation ​

Bulk Create ​

Custom schema 1 (hm_sap) ​

API TUTORIAL – CREATE CONSTRUCTIBLES

Intro

Step 1: Project Creation/Retrieval

ALL RETRIEVAL

FILTERED RETRIEVAL

CREATION

Step 2: Batch Creation/Retrieval

RETRIEVAL

CREATION

UPDATING

Step 3: Assembly Design Retrieval

Step 4: Assembly Creation

Bulk Create

Custom schema 1 (hm_sap)