OpenAPI - Transfer orders (part 3/4) - Migrate from Web API to OpenAPI

This article is part of a series - click to read part 1, part 2 and part 4.

Overview

The Web API (deprecated) is soon to be retired. We strongly recommend organizations to migrate their usage to our the Onix Work OpenAPI today.

Onix Work OpenAPI provides flexible APIs for interacting with the Onix Work system. This results in simpler requests, faster response times, improved security, and better support.

Here’s the guide for developers on migrating from the Web API for transfering or creating orders.

Reference links for Web API documentation on transfering orders:

Model mapping

The Web API’s ERPOrder contains all the information to create an order, order lines, number order lines and update all their properties.

Model mapping notes:

  • ERPOrder (Web API) model is similar to OrderInfo (OpenAPI) model, except OrderInfo (OpenAPI) does not contain order lines information: Orderlines field (ERPOrderline type).
  • ERPOrderline (Web API) model is similar to OrderLineInfo (OpenAPI) model, except OrderInfo (OpenAPI) has type field and does not contain:
    • SerialNumber: default serial number for the current order line.
    • BatchNo: default batch number for the current order line.
    • ERPSerials: information to number the current order line.
    • ERPFields: information for the Web API system can update respective fields, usually properties and form properties, but those fields must be predefined and very limited.
  • ERPSerials (Web API) is similar to OrderLineItemSerialInfo (OpenAPI) used in items field in OrderLineItemsInfo model. This is used for numbering the current order line.
  • ERPFields (Web API) is used for predefined fields. OpenAPI does not support this field. Use endpoint update properties and form properties in part 2 instead.
    If you have trouble migrating this field, please Contact Support.

Mapping table for ERPOrder (Web API) into OrderInfo (OpenAPI) model:

Web API Field OpenAPI Field Comment
ERPOrderID erpOrderId Identical values.
ERPOrderDate erpOrderDate A significant difference in date format:
Web API date format: yyyy.MM.dd, e.g.: 2024.01.31
OpenAPI date format: yyyy-MM-dd, e.g.: 2024-01-31
ERPCustomerOrderNo erpCustomerOrderNo Identical values.
WorkflowStatusId workflowStatusId Identical values.
ERPCustomerId erpCustomerId Identical values.
ERPCustomerDescription erpCustomerDescription Identical values.
ERPCustomerAddress erpCustomerAddress Identical values.
ERPCustomerPostalCode erpCustomerPostalCode Identical values.
ERPCustomerWeb erpCustomerWeb Identical values.
ERPCustomerOrgNumber erpCustomerOrgNumber Identical values.
ERPCustomerCountryCode erpCustomerCountryCode Identical values.
ERPCustomerContactId erpCustomerContactId Identical values.
ERPCustomerContactName erpCustomerContactName Identical values.
ERPSupplierId erpSupplierId Identical values.
ERPSupplierDescription erpSupplierDescription Identical values.
ERPSupplierContactId erpSupplierContactId Identical values.
ERPSupplierContactName erpSupplierContactName Identical values.
Source source Identical values.
OpenAPI support additional value: 3 — Manually.
Orderlines - See the mapping table for ERPOrderline below.

Mapping table for ERPOrderline (Web API) model into OrderLineInfo (OpenAPI).
Note: OpenAPI supports additional field type when creating/updating order lines.
Continuing from the field Orderlines in above table:

Web API Field OpenAPI Field Comment
ERPArticleNo erpArticleNo Identical values.
Quantity quantity Identical values.
ExternalLineNo externalLineNo Identical values.
WorkflowStatusId workflowStatusId Identical values.
ERPParent parentOrderLineImportId Identical values.
ERPInternalId orderLineImportId Identical values.
BatchNo *N/A* OpenAPI does not support this field when creating/updating an order line**.**
This field in Web API is used as the default value in numbering items in an order line.
Use numbering requests instead.
SerialNumber *N/A* OpenAPI does not support this field when creating/updating an order line**.**
This field in Web API is used as the default value in numbering items in an order line.
Use numbering requests instead.
CertificateString certificateString Identical values.
TypeInfo model Identical values.
ERPTypeInfo erpModel Identical values.
WLL wll Identical values.
Comment comment Identical values.
JobComment jobComment Identical values.
ERPSerials - See the mapping table for ERPSerials below.
ERPFields - OpenAPI does not support this field.
See the information for ERPFields below.

The ERPFields (Web API) is used to update order line form properties with a fixed set of keys, but its support is limited and and there is no equivalent model in OpenAPI.

OpenAPI provides PropertyInfo and FormPropertyKeyValueInfo[] for updating respective properties and form properties in place of ERPFields (Web API) in a more intuitive way.

We strongly suggest switching to OpenAPI for a more flexible and powerful way to update properties and form properties using two endpoints:

  • POST /v1/order-lines/properties to update the order line’s properties.
  • POST /v1/order-lines/form-properties to update the order line’s form properties.

Examples

Here’s an example that shows how to create an order using the Web API, combining information from different sections:

{
  "ERPOrderID": "ERP_Order/0001",
  "ERPCustomerOrderNo": "ERP_CustomerOrder/0001",
  "ERPCustomerId": "ERP_Customer/0382",
  "Orderlines": [
    {
      "ERPArticleNo": "ERP_Product/0001",
      "Quantity": 5,
      "ERPInternalId": "ERP_OrderLine/0001",
      "TypeInfo": "OL1: ERP model",
      "ERPTypeInfo": "OL1: ERP erpModel",
      "WLL": "OL1: WLL",
      "Comment": "OL1: My Comment",
      "JobComment": "OL1: My job comment",
      "ERPSerials": [
        {
          "SerialNumber": "EQ.ERP.01",
          "BatchNo": "B2024.01",
          "ProdYear": "2024"
        },
        {
          "SerialNumber": "EQ.ERP.02",
          "BatchNo": "B2024.01",
          "ProdYear": "2024"
        },
        {
          "SerialNumber": "EQ.ERP.03",
          "BatchNo": "B2024.01",
          "ProdYear": "2024"
        },
        {
          "SerialNumber": "EQ.ERP.04",
          "BatchNo": "B2024.01",
          "ProdYear": "2024"
        },
        {
          "SerialNumber": "EQ.ERP.05",
          "BatchNo": "B2024.01",
          "ProdYear": "2024"
        }
      ],
      "ERPFields": [
        {
          "Field": "FE_AntallProvetS",
          "Value": "field value"
        }
      ]
    }
  ]
}

Note that OpenAPI does not supportERPFields field.
The above request is combined from all examples in all other sections. It can split into 5 requests (steps) in OpenAPI:

  1. Create the order using the endpoint POST /v1/orders. Notice that the importId field is required in.
{
  "importId": "ERP_Import/0001",
  "erpOrderId": "ERP_Order/0001",
  "erpCustomerOrderNo": "ERP_CustomerOrder/0001",
  "erpCustomerId": "ERP_Customer/0382"
}
  1. Create order lines by making a request for each order line using the endpoint:
    POST /v1/order-lines
{
  "orderImportId": "ERP_Import/0001",
  "orderLineImportId": "ERP_OrderLine/0001",
  "erpArticleNo": "ERP_Product/0001",
  "quantity": 5,
  "model": "OL1: ERP model",
  "erpModel": "OL1: ERP erpModel",
  "wll": "OL1: WLL",
  "comment": "OL1: My Comment",
  "jobComment": "OL1: My job comment"
}
  1. Numbering order lines by making a request for each order line using the endpoint:
    POST /v1/order-lines/items
{
  "orderImportId": "ERP_Import/0001",
  "orderLineImportId": "ERP_OrderLine/0001",
  "items": [
    {
      "serialNumber": "EQ.ERP.01",
      "batchNo": "B2024.01",
      "prodYear": "2024"
    },
    {
      "serialNumber": "EQ.ERP.02",
      "batchNo": "B2024.01",
      "prodYear": "2024"
    },
    {
      "serialNumber": "EQ.ERP.03",
      "batchNo": "B2024.01",
      "prodYear": "2024"
    },
    {
      "serialNumber": "EQ.ERP.04",
      "batchNo": "B2024.01",
      "prodYear": "2024"
    },
    {
      "serialNumber": "EQ.ERP.05",
      "batchNo": "B2024.01",
      "prodYear": "2024"
    }
  ]
}
  1. Update properties for order lines by making a request for each order line using the endpoint:
    POST /v1/order-lines/properties
{
  "orderImportId": "ERP_Import/0001",
  "orderLineImportId": "ERP_OrderLine/0001",
  "properties": [
    {
      "key": "ApiKey_Proofload",
      "value": "Test value"
    },
    {
      "key": "ApiKey_DateOfTest",
      "value": "2024.31.01"
    }
  ]
}
  1. Update form properties for order lines by making a request for each order line using the endpoint:
    POST /v1/order-lines/form-properties
{
  "orderImportId": "ERP_Import/0001",
  "orderLineImportId": "ERP_OrderLine/0001",
  "properties": [
    {
      "key": "ApiKey_Proofload",
      "value": "Test value"
    },
    {
      "key": "ApiKey_DateOfTest",
      "value": "2024.31.01"
    }
  ]
}

And that concludes the process – you’ve successfully created an entire order.

Related articles

  • OpenAPI - Get started
  • Part 1: create and update an order, an order line and numbering an order line.
  • Part 2: update an order line’s properties and form properties.
  • Part 3: how to migrate from Web API to OpenAPI.
  • Part 4: create and update grouped order lines.

If you encounter any issues or have questions, kindly describe your concern and:

  • Send an email to support@onix.com; OR
  • Create a topic in Q&A to receive assistance from all Community members.