...
Overview
The purpose of the Logix API LogiX Business Integrator Component is to enable data exchange between LogixApplications andbusiness LogiXApplications andISA-95 Level 4: Business logistics and reporting systems, such as ERP, APS, or CMMS.
The API Integrator will ultimately cover the following areas:
Processing orders
Repository of Handling materials and BOM’s
Scheduling production activitiesRegistering events related to lifecycle of an activity (start/stop/complete)Exposing selected raw data and aggregated KPIs (including OEE metrics, downtimes, reported labor time)
Processing raw and aggregated KIPs and other data by LogiXapplications
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 LogiX internal data model, of which semantics is known across LogixLogiX components, from external data models.
Logix 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: https://gateway.dev.logix.cloud/index.html
Authentication
To access Logix API you need API Key to authenticate.
To obtain your Key you need to contact Ilabo support.
How to use API
1. Location: : <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:
Code Block |
---|
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:
Code Block |
---|
{
"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:
Code Block |
---|
GET /products?plant=TST
HEADERS:
API-Key: your-api-key |
General 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).
3. Registering events
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
...
.
4. Data validation - and “draft” and “released” states
Activities added through API pass through two stage validation
- simple, synchronous validation done while processing request (unvalidated requests are not persisted)
- complex cross-validation done asynchronously. After initially validated request activity is saved in “Draft” State. Then another dedicated service preforms complex validations of activity (i.e. does Logix have all data needed to process production lifecycle of given activity). This is repeated after each change of activity data. If this validation is positive then activity state is changed to “Released” state. If not - activity stays in “Draft” state and relevant information are added to activity:
- “validationErrorCount” attribute is filled
- detailed information about validation errors are available through additional separate endpoint under each activity (/validation-errors)
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).
Expand | ||
---|---|---|
| ||
ID - external identifier of activity, unique within given plant. Identifier must begin and terminate with a digit or letter and can contain ‘_' and '-’ letters inside Type - type of line activity: Changeover, Cleaning, Order, Other PlantCode - factory ID, as described abovecode for Plant (as defined in Logix ConfigHub) LineCode - line ID, as described abovecode for Line (as defined in Logix ConfigHub) plannedExecution - container for dates of planned execution for given activity (orginal as of external system): PlannedStart - planned start date and time PlannedEnd - planned end date and time scheduledExecution - container for dates of scheduled execution for given activity (managed by Logix): ScheduledStart - scheduled start date and time ScheduledEnd - scheduled end date and time actualExecution - container for dates of actual execution for given activity (registered in Logix): ActualStart - start date and time for given activity as it actually happened ActualEnd - end date and time for given activity as it actually happened EstimatedEnd - end date and time for given activity predicted by LogiX taking into account actual performance ExpectedEffort - container for information about planned labor utilization manhours - number of hours (decimal data type) ActualEffort - container for information about actual, reported labor utilization manhours - number of hours (decimal data type) Status - current activity status: Draft - activity not validated Released - activity ready to be started Started - activity in progress Suspended - activity on hold, can be started or completed Completed - activity finished Kind - additional activity classification within given type (eq. kind of changeover: Labeling vs Product change) Description - additional free text to describe acitivty additionalFields - collection of arbitrary name/value pairs to enrich/classify/describe given activity validationErrorCount - Created - date and time of activity creation Modified - date and time of last modification of activity |
...
Expand | ||
---|---|---|
| ||
orderedQuantity: value - scheduled quantity of goods to be produced unit - unit of measurement in which quantity was specified plannedActivation: - optional date and time of corelated changover activity begin - planned start date for changeover end - planned end date for changeover producedQuantity: value - quantity of goods actually produced unit - unit of measurement in which quantity was specified wastedQuantity: value - quantity of wasted products unit - unit of measurement in which quantity was specified productId - identifier of product to be manufactured flowName - optional identifier of Line Configuration as defined in PackOS |
...
Expand | ||
---|---|---|
| ||
Id- unique, external product identifier name - product name ean - optional EAN code of a product additionalFields - a collection of name value pairs which can be freely used for addtitional additional product description lineConfigurations - a collection of design and validated performance for given product on different lines lineCode - code of linefor line (as defined in Logix ConfigHub) designSpeed value - design speed value unit - unit of measurement for speed value validatedSpeed value - validated speed value unit - a unit of measurement for speed value packagingStructures - conversion between packages fromUnit - the name of base unit toUnit - the name of destination unit multiplier - multiplier to convert quantity between Units of Measurement |
...