OpenAPI - Transfer orders (part 2/3) - Update order line's properties and form properties

khoa.nguyen · February 5, 2024, 3:28pm

This article is divided into three parts, read part 1 and part 3 here.

Update an order line’s properties.

API overview


Endpoint	`POST /v1/orders-lines/properties`
Description	Update an order line’s properties.
Usage	Make requests to this endpoint to update the order line’s properties. Only matched properties are updated; the rest is ignored. The rule is described in field `PropertyInfo` fields table. The order line’s properties come from the product’s properties or manually created by users on Onix Work. This endpoint does not support creating new properties. Note: Attempting to call this request for an order line when the workflow status on either itself or its order is marked as “Closed” will result in an error.
Return	Returns a boolean value indicating the success of the updating process.

Request parameters and body

The corresponding request body type can be found at the Swagger page (see OpenAPI overview), model OrderLinePropertiesInfo for the main request body and OrderLineItemSerialInfo for the properties model.

There are two ID pairs:

orderId and orderImportId.
orderLineId and orderLineImportId.

Despite those fields being nullable, the system requires the request body must contains at least one field for each pair.

Field precedence for ID pairs:

orderId has higher priority than orderImportId.
orderLineId has higher priority than orderLineImportId.

When a higher priority field is present, the lower priority field will be ignored.

When a field value is null, it follows the rules explained in section API requests and responses, if no specific rules are mentioned.

Field	Type	Required	Description
`orderId`	`int`	No*	The Onix Work system’s order ID. Either `orderId` or `orderImportId` must be provided. See field precendence above.
`orderImportId`	`string`	No*	Constraint: length ≤ 50. Your system’s order ID. Either `orderId` or `orderImportId` must be provided. See field precendence above.
`orderLineId`	`int`	No*	The Onix Work system’s order line ID. Either `orderLineId` or `orderLineImportId` must be provided. See field precendence above.
`orderLineImportId`	`string`	No*	Constraint: length ≤ 50. Your system’s order line ID. Either `orderLineId` or `orderLineImportId` must be provided. See field precendence above.
`properties`	`PropertyInfo[]`	Yes	Constraint: length > 0. The list of the order line’s properties. Only matched properties are updated; the rest are ignored. See the table below for more information and the properties update rule.

Response

Status code	Response body	Description
`200`	A boolean.	Indicate if the update process was successful or not.
`400`	The system’s standard error response object.	See an examples of error responses in section API requests and responses.

Examples

Let’s use the orderId and orderLineId to update properties for the order line that’s just created in part 1:

orderId: 546804.
orderLineId: 3998608.

You can also use orderImportId and orderLineImportId instead.
First, let’s examine the properties of the product that the order line has been using for better visualization:

Currently, there are two properties “Color” and “Actual diameter (mm)”, and the “Color” property has “White” as the default value. That means our order line also has two properties with the same values.

To update the order line’s properties, make a request with the request body below, with languageCode is English (see OpenAPI terminology):

{
  "orderId": 546804,
  "orderLineId": 3998608,
  "properties": [
    {
      "languageCode": 1,
      "description": "Color",
      "value": "Red"
    },
    {
      "languageCode": 1,
      "description": "Actual diameter (mm)",
      "value": "0.5"
    }
  ]
}

The system responsed with status code of 200, the response body indicates where the request was successful or not:

true

The properties have been updated successfully. Let’s check the results in Onix Work by navigating to the order we have just been created in part 1 and click on the tab “Order lines” then “Properties” of the order line.

The properties have updated according to the request. Let’s go to the next step: update the order line’s form properties.

Update an order line’s form properties.

API overview

A	B
Endpoint	`POST /v1/orders-lines/form-properties`
Description	Update an order line’s form properties.
Usage	Make requests to this endpoint to update the order line’s form properties. Only matched properties are updated; the rest is ignored. The rule is described in field `FormPropertyKeyValueInfo` fields table. The order line’s form properties come from the product’s form properties or manually created by users on Onix Work. Make a request to this endpoint: `GET /v1/company/form-properties` to get a full list of available and editable form properties. Note: Attempting to call this request for an order line when the workflow status on either itself or its order is marked as “Closed” will result in an error.
Return	Returns a boolean value indicating the success of the updating process.

Request parameters and body

The corresponding request body type can be found at the Swagger page (see OpenAPI overview), model OrderLineFormPropertiesInfo for the main request body and FormPropertyKeyValueInfo for the properties model.

There are two ID pairs:

orderId and orderImportId.
orderLineId and orderLineImportId.

Despite those fields being nullable, the system requires the request body must contains at least one field for each pair.

Field precedence for ID pairs:

orderId has higher priority than orderImportId.
orderLineId has higher priority than orderLineImportId.

When a higher priority field is present, the lower priority field will be ignored.

When a field value is null, it follows the rules explained in section API requests and responses, if no specific rules are mentioned.

Field	Type	Required	Description
`orderId`	`int`	No*	The Onix Work system’s order ID. Either `orderId` or `orderImportId` must be provided. See field precendence above.
`orderImportId`	`string`	No*	Constraint : length ≤ 50. Your system’s order ID. Either `orderId` or `orderImportId` must be provided. See field precendence above.
`orderLineId`	`int`	No*	The Onix Work system’s order line ID. Either `orderLineId` or `orderLineImportId` must be provided. See field precendence above.
`orderLineImportId`	`string`	No*	Constraint : length ≤ 50. Your system’s order line ID. Either `orderLineId` or `orderLineImportId` must be provided. See field precendence above.
`properties`	`FormPropertyKeyValueInfo[]`	Yes	Constraint: length > 0. The list of the order line’s form properties. See the table below for more information.

Model FormPropertyKeyValueInfo fields table:

Field	Type	Required	Description
`key`	`string`	Yes	Constraint : length ≤ 50. The form property’s key – corresponding with the key field in endpoint: `GET /v1/company/form-properties`
`value`	`string`	No	Constraint : length ≤ 100. The form property’s value.

Response

Status code	Response body	Description
`200`	A boolean.	Indicate if the update process was successful or not.
`400`	The system’s standard error response object.	See an examples of error responses in section API requests and responses.

Examples

Let’s use the orderId and orderLineId to update properties for the order line that’s just created in part 1:

orderId: 546804.
orderLineId: 3998608.

You can also use orderImportId and orderLineImportId instead.
First, let’s examine the form of the product that the order line has been using for better visualization:

There are one form and four properties, and only “Proofload” and “Date of test” can be updated. Typically, developers should check all available form properties using the endpoint:

GET /v1/company/form-properties

The results of this endpoint allow developers to find the suitable keys which can be used to update the form properties. The key for those two properties above is:

ApiKey_Proofload: “Proofload” property.
ApiKey_DateOfTest: “Date of test” property.

Use them and make a request with the request body below:

{
  "orderId": 546804,
  "orderLineId": 3998608,
  "properties": [
    {
      "key": "ApiKey_Proofload",
      "value": "Test value"
    },
    {
      "key": "ApiKey_DateOfTest",
      "value": "2024.31.01"
    }
  ]
}

The system responsed with status code of 200, the response body indicates where the request was successful or not:

true

The properties have been updated successfully. Let’s check the results in Onix Work by navigating to the order we have just been created and click on the tab “Order lines” then “Forms” of the order line.

Notice that the value of “Proofload” and “Date of test” updated accordingly to the request.

That completes the entire process of creating or updating an order. If you are currently using the Web API (deprecated), consider migrating to OpenAPI. Please refer to part 3 for more information.

Topic	Replies	Views
Version 1.9.1.0 - Release date: 15.03.2024 OpenAPI changelogs official , openapi	84	March 13, 2024
The new Properties management Knowledge base onix-work , official	107	December 19, 2023
How to update certificates created from the Orders module when you cannot recall the order Knowledge base onix-work	156	December 12, 2023
Manage Base documents in Orders, Products and Settings modules Knowledge base onix-work , official	141	December 19, 2023
Deliver equipment with documents in Orders module Knowledge base onix-work , official	121	December 19, 2023

OpenAPI - Transfer orders (part 2/3) - Update order line's properties and form properties

Update an order line’s properties.

API overview

Request parameters and body

Response

Examples

Update an order line’s form properties.

API overview

Request parameters and body

Response

Examples

Related articles

Related Topics