2.8 LogiX Public API ✔️
- Piotr - Technical Writer at ilabo (Unlicensed)
- Jan Dabrowski
- Piotr Wierzchowski
Overview
The purpose of the LogiX Business Integrator Component is to enable data exchange between LogiX Applications and ISA-95 Level 4: Business logistics and reporting systems, such as ERP, APS, or CMMS.
The Integrator will ultimately cover the following areas:
Processing orders
Handling materials
Scheduling production events
Processing raw and aggregated KIPs and other data by LogiX applications
Assumptions
Almost every LogiX deployment needs to communicate with ERP systems or other business apps.
Those applications are often COTS or legacy software that are hard to change.
Even for the same app (or a set of apps), there are often various integration scenarios for a single Client.
Goals
Decoupling:
LogiX internal data model, of which semantics is known across LogiX components, from external data models.
LogiX cloud services from implementation of custom integration components, supporting various interfaces, different orchestrations, ETL batch exchanges, and data formats.
Common core message bus and data structure
Security:
Authorizations
DDoS - Request Flood prevention
Events/errors logging
Out-of-the-box observability:
Monitoring
Logging for auditing and debugging
Tracing in case there is a need for deeper problem analysis.
API - General Description
The description is available here: <link>
(attributes of available resource are also described below)
Authentication
There are 2 schemas of authentication available for LogiX Public API:
1. OAuth0 - Client Credentials authentication
In accordance with OpenID Connect specifications, the following parameters are sent to each Client individually:
Authentication base URL
Client ID
Client Secret
You can use them to generate a new token using the following parameters:
Grant Type: client_credentials
Discovery Endpoint: [baseUrl]/.well-known/openid-configuration
Access Token URL: [baseUrl]/connect/token
Scope: api.logix.cloud logix.api
Example Request:
POST /connect/token
CONTENT-TYPE application/x-www-form-urlencoded
client_id=client1&
client_secret=secret&
grant_type=client_credentials&
scope=api.logix.cloud%20logix.api
Example Response:
{
"access_token": "eyJh...",
"expires_in": 3600,
"token_type": "Bearer",
"scope": "api.logix.cloud logix.api"
}2. API Key authentication
If needed, ilabo can create a static API KEY. Each key is assigned to a specific user account, and it’s permissions are controlled accordingly.
With this key attached as a HEADER, you can send any request to the Public API and get a response back, without ever needing to generate an access token (like in the first method).
Example Request:
GET /products?plant=TST
HEADERS:
API-Key: your-api-keyGeneral Assumptions
In API calls, you should use IDs for factories (PlantCode) and production lines (LineCode). You can find those IDs in the ConfigHub app in the Factories tab.
Note: identifying Line just by specifying LineCode in API calls is an exception in general requirement of identifying assets by ISA95 paths More on this topic: Asset identification and classification system in LogiX
If you want to add new activities or modify the existing ones, you should use the HTTP PUT method:
if the activity that you are adding exists, it will be updated.
if the activity that you are adding does not exist, it will be added as a new activity.
Updating via an external system is not allowed only if a specific activity is blocked as Managed by LogiX (it is done by setting a special internal flag in LogiX ). Such blocking occurs automatically when an activity is added or modified through an app that belongs to the LogiX Suite (PackOS or KeepUp).
Changing the statuses of activities that are in the LogiX scheduler can be initiated from outside by invoking right methods on the resources related to specific activities.
Resources
/activities
Read-only use. It returns the activity schedules of all types: scheduled, executed, or historical ones. You can use filters for schedules by providing the LineCode ID and narrowing down the time range of activity (for example, production orders).
/activities/changeovers
Changeovers are always related to production order and they can be created automatically with an order by specifying additional attributes (plannedActivation begin and end).
/activities/cleanings
Dedicated resource is for line cleaning activities.
/activities/orders
Resource to create, update or retrieve information about production orders. It is possible to create at once an Order with correlated Changeover activity by specifying optional Planned Activation dates.
/products
Resource to manage Products registry.