Overview

Each use case for integrating automatic order creation comes with specific conditions and parameters. This guide presents a basic example of creating orders using data from an external source. It serves as a starting point, allowing you to adapt filtering, sorting, and other customization options based on your specific needs through the Operations1 API.

Background

Operations1 streamlines workers' tasks by delivering instructions and checklists tailored to specific products or machines that are assembled, inspected, or maintained. External systems manage order-related data—including customer, production, and maintenance details—for these products and machines.

To facilitate a connection to leading systems and Operations1 offers a classification system that assigns characteristics (e.g., material, product numbers, or asset numbers) to relevant content. This enables the integration to identify necessary documents for each order, retrieve their Operations1 internal IDs, create specific orders, and attach the corresponding documents.

Once executed, the order is fully prepared for processing by the worker without requiring manual intervention.

This guide illustrates the process using a CSV file as the data source for order information.

Process description

The example is divided into three main steps:

1. Extracting order data: Extract relevant information such as order title, start and end dates, order number, and included products.
2. Selecting relevant documents: Identify and retrieve all relevant documents associated with the included products.
3. Creating orders in Operations1: Utilize the Operations1 API to create orders and assign the relevant documents.

For demonstration purposes, the data source is a CSV file, but this could be any input channel from a leading system.

Execution steps

Setup

The example uses environment variables stored in a .env file for configuration. To run the script, ensure you have:

• API access to Operations1.
• An authentication token.
• A class containing product keys, linked to the corresponding documents.

Helper Functions

A helper module (helpers.py) manages API interactions and configurations. It contains:

• API Class: Stores configuration details.
• handle_rate_limiting: Manages API rate limiting (documentation).
• paginate_request: Handles pagination for API calls (documentation).
• read_orders_from_csv: Reads CSV files into a list object.

API Functions

Another module handles Operations1 API calls:

• get_class_characteristic_ids: Retrieves internal ID values for specific product keys.
• get_documents: Fetches documents associated with a specific product ID.
• create_order: Creates an order in Operations1 and assigns the relevant documents.

Program Initialization

Before processing the dataset:

1. The configuration is read from the .env file and stored in an API object.
2. The file name containing the example data needs to be set.

Extract order information

CSV File Structure

The example CSV file follows this structure:

order_number;order_title;order_description;order_startdate;order_enddate;product  
001;Customer Order 001;Customer ACME ltd.;2025-01-22T14:40:00.000Z;2025-01-26T14:40:00.000Z;OPS01  
001;Customer Order 001;Customer ACME ltd.;2025-01-22T14:40:00.000Z;2025-01-26T14:40:00.000Z;OPS02  
002;Customer Order 002;Customer Operations1;2025-01-22T14:40:00.000Z;2025-01-26T14:40:00.000Z;OPS01  
003;Customer Order 003;Customer ACME ltd.;2025-01-22T14:40:00.000Z;2025-01-26T14:40:00.000Z;OPS03

Each row consists of six columns:

• order_number: Identifier from the leading system.
• order_title: Name of the order.
• order_description: Additional details, such as customer name.
• start_date & end_date: Defines the order timeframe.
• product: Identifies which product-specific documents should be added.

Each row represents one product. If multiple products exist within an order, the order parameters remain consistent across lines.

Data Import

The program reads the CSV row by row, creating an order structure as follows:

{
   "order_number":"001",
   "order_title":"Customer Order 001",
   "order_description":"Customer ACME ltd.",
   "order_startdate":"2025-01-22T14:40:00.000Z",
   "order_enddate":"2025-01-26T14:40:00.000Z",
   "products":[
      "OPS01",
      "OPS02"
   ]
}

This represents an order containing two products.

Identify relevant documents

Once order information is collected, the program retrieves all associated documents for the specified products. It first maps product keys to class characteristics. This is achieved by searching the product class (defined in the configured in .env) for the product keys in the order with the "List class characteristics" API call in the helpers.py module, which returns this structure:

{
   "OPS01":437,
   "OPS02":438
}

An array is built out of the found charateristic IDs:

[437, 438]

Now for each of these product IDs the relevant documents get listed with the "List documents" with in the function in the helpers.py module and their document IDs stored into an array:

[
   1090,
   1133,
   1095
]

Create Orders in Operations1

The final step calls the create_order function, sending the extracted order data to the Operations1 API. This includes the order details and filtered document IDs. The API function "Create an order" requires at least the documentId and optional additional parameters for each document (i.e. if the latest version of the document should be used):

{
  "useLatestDocument": true,
  "documentId": 12
}

See the documentation for details.

The complete payload for an order then looks like this:

{
   "name":"Order 001 | Customer Order 001",
   "description":"Customer ACME ltd.",
   "startDate":"2025-01-22T14:40:00.000Z",
   "dueDate":"2025-01-26T14:40:00.000Z",
   "orderDocumentAssignments":[
      {
         "useLatestDocument":true,
         "documentId":1090
      },
      {
         "useLatestDocument":true,
         "documentId":1133
      },
      {
         "useLatestDocument":true,
         "documentId":1095
      }
   ]
}

Once submitted, the order is created in the system and is ready for processing.

Conclusion

This guide provides a structured approach to automating order creation using external data sources and the Operations1 API. By extending this example, you can further customize the process to suit your specific business requirements, like:

• Various sources for the order data: ERP, MES, etc. and channels: CSV, REST, etc.
• Apply complex filtering: logic over multiple product keys, variants, etc.
• Additional information: user assignment, custom order ID as reference from the leading system, etc.
• Different environments: script,cloud applications (i.e. PowerAutomate), etc.

Here is the complete recipe: