74 lines
3.7 KiB
Markdown
74 lines
3.7 KiB
Markdown
# Component: External System Gateway
|
|
|
|
## Purpose
|
|
|
|
The External System Gateway manages predefined integrations with external systems (e.g., MES, recipe managers) and database connections. It provides the runtime for invoking external API methods and executing database operations from scripts at site clusters.
|
|
|
|
## Location
|
|
|
|
Site clusters (executes calls directly to external systems). Central cluster (stores definitions, brokers inbound requests from external systems to sites).
|
|
|
|
## Responsibilities
|
|
|
|
### Definitions (Central)
|
|
- Store external system definitions in the configuration database: connection details, API method signatures (parameters and return types).
|
|
- Store database connection definitions: server, database, credentials.
|
|
- Deploy definitions uniformly to all sites (no per-site overrides). Deployment requires **explicit action** by a user with the Deployment role.
|
|
- Managed by users with the Design role.
|
|
|
|
### Execution (Site)
|
|
- Invoke external system API methods as requested by scripts (via Script Execution Actors and Alarm Execution Actors).
|
|
- Provide raw MS SQL client connections (ADO.NET) by name for synchronous database access.
|
|
- Submit cached database writes to the Store-and-Forward Engine for reliable delivery.
|
|
- Sites communicate with external systems **directly** (not routed through central).
|
|
|
|
### Integration Brokering (Central)
|
|
- Receive inbound requests from external systems (e.g., MES querying machine values).
|
|
- Route requests to the appropriate site via the Communication Layer.
|
|
- Return responses to the external system.
|
|
|
|
## External System Definition
|
|
|
|
Each external system definition includes:
|
|
- **Name**: Unique identifier (e.g., "MES", "RecipeManager").
|
|
- **Connection Details**: Endpoint URL, authentication, protocol.
|
|
- **Retry Settings**: Max retry count, fixed time between retries (used by Store-and-Forward Engine).
|
|
- **Method Definitions**: List of available API methods, each with:
|
|
- Method name.
|
|
- Parameter definitions (name, type).
|
|
- Return type definition.
|
|
|
|
## Database Connection Definition
|
|
|
|
Each database connection definition includes:
|
|
- **Name**: Unique identifier (e.g., "MES_DB", "HistorianDB").
|
|
- **Connection Details**: Server address, database name, credentials.
|
|
- **Retry Settings**: Max retry count, fixed time between retries (for cached writes).
|
|
|
|
## Database Access Modes
|
|
|
|
### Synchronous (Real-time)
|
|
- Script calls `Database.Connection("name")` and receives a raw ADO.NET `SqlConnection`.
|
|
- Full control: queries, updates, transactions, stored procedures.
|
|
- Failures are immediate — no buffering.
|
|
|
|
### Cached Write (Store-and-Forward)
|
|
- Script calls `Database.CachedWrite("name", "sql", parameters)`.
|
|
- The write is submitted to the Store-and-Forward Engine.
|
|
- Payload includes: connection name, SQL statement, serialized parameter values.
|
|
- If the database is unavailable, the write is buffered and retried per the connection's retry settings.
|
|
|
|
## Dependencies
|
|
|
|
- **Configuration Database (MS SQL)**: Stores external system and database connection definitions.
|
|
- **Store-and-Forward Engine**: Handles buffering for failed external system calls and cached database writes.
|
|
- **Communication Layer**: Routes inbound external system requests from central to sites.
|
|
- **Security & Auth**: Design role manages definitions.
|
|
- **Configuration Database (via IAuditService)**: Definition changes are audit logged.
|
|
|
|
## Interactions
|
|
|
|
- **Site Runtime (Script/Alarm Execution Actors)**: Scripts invoke external system methods and database operations through this component.
|
|
- **Store-and-Forward Engine**: Failed calls and cached writes are routed here for reliable delivery.
|
|
- **Deployment Manager**: Receives updated definitions as part of system-wide artifact deployment (triggered explicitly by Deployment role).
|