chore: add project plan, research, evidence, and workflow artifacts

2026-03-10 17:45:26 +00:00
parent 8fc6d7cbc0
commit 14c2a9f94c
17 changed files with 2015 additions and 0 deletions
--- a/.sisyphus/research/sage-x3-api-landscape.md
+++ b/.sisyphus/research/sage-x3-api-landscape.md
@@ -0,0 +1,134 @@
+# Sage X3 API Landscape — Research Findings
+
+## Overview: Three API Types
+
+Sage X3 exposes **three distinct API layers**, each suited to different integration scenarios:
+
+### 1. GraphQL API (Newest — V12+, via Sage X3 Builder)
+
+**Architecture**: Syracuse server → GraphQL endpoint → Node-based schema
+**Auth**: OAuth2 (Authorization Code flow)
+**Best for**: Modern integrations, complex queries, typed schema
+
+**Key Concepts**:
+- **Nodes**: Data models published as GraphQL types (e.g., `SalesInvoice`, `PurchaseOrder`, `Customer`)
+- **Operations/Mutations**: GraphQL mutations linked to X3 functions (subprograms, windows, classes, import templates)
+- **Node Bindings**: Customization of API nodes and properties
+- **Packages**: Organizational units for nodes in the GraphQL schema
+
+**Example Query (Purchasing)**:
+```graphql
+{
+  x3Purchasing {
+    purchaseOrder {
+      query(filter: "{purchaseSite: 'FR011', orderFromSupplier: 'FR053', isClosed: {_ne: 'yes'}}") {
+        edges {
+          node {
+            id
+            purchaseSite { code }
+            receiptSite { code }
+            orderFromSupplier { code { code } }
+            isClosed
+            receiptStatus
+            signatureStatus
+            purchaseOrderLines { query { edges { node { orderedQuantity } } } }
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+**Modules Available**: x3Sales, x3Purchasing, x3Financials, x3CommonData, x3Manufacturing, x3Stock
+
+**Authorization Flow** (OAuth2):
+1. GET `https://api.myregion-sagex3.com/v1/token/authorise` with client_id, scope, redirect_uri
+2. User approves in Sage X3 UI, selects folder(s)
+3. App receives callback with authorization code
+4. Exchange code for access token + refresh token
+
+### 2. REST Web Services (V7+ style — Syracuse/SData)
+
+**Architecture**: Syracuse server → REST endpoints → Classes + Representations
+**Auth**: Basic, Client Certificate (on-prem), OAuth2 (cloud)
+**Best for**: Standard CRUD operations on business objects
+
+**URL Pattern**:
+```
+http://SERVER:PORT/api1/x3/erp/ENDPOINT/CLASS?representation=REPR.$query
+```
+
+**Parameters**:
+- `count=N` — pagination (default 20)
+- `startRecord=N` — pagination offset
+- `orderBy=field asc|desc` — sorting
+- `where=condition` — filtering
+
+**Example**: Query customers
+```
+GET http://server:8124/api1/x3/erp/X3/BPCUSTOMER?representation=BPCUSTOMER.$query&count=50
+```
+
+**Key Entities**: BPCUSTOMER, SINVOICE (sales invoice), SORDER (sales order), PORDER (purchase order), etc.
+
+### 3. SOAP Web Services (Legacy V6 style)
+
+**Architecture**: Syracuse server → SOAP pool → X3 classic programs/subprograms
+**Auth**: Basic (username/password in request), Bearer Token
+**Best for**: Legacy integrations, subprogram calls, complex object manipulation
+
+**WSDL Endpoint**:
+```
+http://SERVER:PORT/soap-wsdl/syracuse/collaboration/syracuse/CAdxWebServiceXmlCC?wsdl
+```
+
+**Operations**: read, save, delete, query, run (subprogram), getDescription
+
+**Call Context**:
+```xml
+<callContext xsi:type="wss:CAdxCallContext">
+   <codeLang xsi:type="xsd:string">ENG</codeLang>
+   <poolAlias xsi:type="xsd:string">POOL_NAME</poolAlias>
+   <poolId xsi:type="xsd:string"></poolId>
+   <requestConfig xsi:type="xsd:string">adxwss.optreturn=JSON&adxwss.beautify=true</requestConfig>
+</callContext>
+```
+
+**Response Format**: XML or JSON (configurable via `adxwss.optreturn`)
+
+**SIH (Sales Invoice) Example Description**:
+- Fields: SALFCY (Sales site), SIVTYP (Type), NUM (Invoice no.), BPCINV (Bill-to customer), CUR (Currency), INVDAT (Date)
+- Methods: READ, CREATE, MODIFY, DELETE, LIST
+- Read key: NUM (Invoice number)
+
+## Authentication Summary
+
+| API Type | On-Premise | Cloud |
+|----------|-----------|-------|
+| GraphQL | OAuth2 | OAuth2 |
+| REST | Basic, Client Cert, OAuth2 | OAuth2 |
+| SOAP | Basic Auth, Bearer Token | OAuth2 |
+
+## Key Business Objects (Common Names)
+
+| Object Code | Description | SOAP Public Name |
+|-------------|-------------|-----------------|
+| SIH | Sales Invoice Header | SIH / WSIH |
+| SIV | Sales Invoice | WSIV |
+| SOH | Sales Order Header | SOH |
+| SOQ | Sales Quote | SOQ |
+| POH | Purchase Order Header | POH |
+| BPC | Business Partner Customer | WSBPC |
+| BPS | Business Partner Supplier | WSBPS |
+| ITM | Item/Product | WITM |
+| STK | Stock | — |
+
+## Integration Architecture Notes
+
+- **Syracuse Server** is the middleware layer for all APIs
+- SOAP uses connection **pools** with configurable channels
+- REST uses **representations** (views of data) and **classes** (business objects)
+- GraphQL uses **nodes** (data models) with **operations** (mutations)
+- **Licensing** controls data volume for SOAP (WSSIZELIMIT per period)
+- On-premise vs Cloud affects auth options and file/DB integration access