Skip to content

Commit bf718ed

Browse files
CopilotKnerio
Copilot
and
Knerio
committed
Add comprehensive GLS Action documentation with corrected events model
Co-authored-by: Knerio <96529060+Knerio@users.noreply.github.com>
1 parent adcf16e commit bf718ed

12 files changed

Lines changed: 2414 additions & 36 deletions

File tree

‎README.md‎

Lines changed: 39 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,47 @@
11
# centaurus
2-
The "central" place for all actions
32

4-
# ENV
3+
The "central" place for all actions — a monorepo containing integrations provided by [code0](https://github.com/code0-tech) for the **Hercules** automation platform.
4+
5+
## Available Actions
6+
7+
| Action | Description |
8+
|--------|-------------|
9+
| [GLS](docs/Actions/GLS/overview.md) | GLS ShipIT integration for creating and managing shipments |
10+
11+
## ENV
12+
13+
All actions share the following base environment variables, which connect them to the Hercules/Aquila infrastructure:
14+
515
| ENV Variable | Description | Default Value |
616
|------------------------|------------------------------------------------|---------------------|
717
| `HERCULES_AUTH_TOKEN` | Authentication token for connecting to Aquila. | `""` (empty string) |
818
| `HERCULES_AQUILA_URL` | URL of the Aquila server to connect to. | `"localhost:50051"` |
919
| `HERCULES_ACTION_ID` | Identifier for the action being registered. | `"<action-name>"` |
1020
| `HERCULES_SDK_VERSION` | Version of the Hercules SDK being used. | `"0.0.0"` |
21+
22+
## Quick Start
23+
24+
1. Clone the repository
25+
2. Navigate to the action directory: `cd actions/<action-name>`
26+
3. Copy the example env file: `cp .example.env .env`
27+
4. Fill in your credentials and Hercules connection details in `.env`
28+
5. Start the action: `docker compose up -d`
29+
30+
See the [Installation Guide](docs/Guides/installation.md) for detailed steps.
31+
32+
## Documentation
33+
34+
Full documentation is located in the [`docs/`](docs/) folder:
35+
36+
- [Installation Guide](docs/Guides/installation.md)
37+
- [GLS Action Overview](docs/Actions/GLS/overview.md)
38+
- [GLS Configuration](docs/Actions/GLS/configs.md)
39+
- [GLS Functions](docs/Actions/GLS/functions.md)
40+
- [GLS Types](docs/Actions/GLS/types.md)
41+
- [GLS Events](docs/Actions/GLS/events.md)
42+
- [Common Use Cases](docs/Actions/GLS/use-cases.md)
43+
- [Troubleshooting & Community Support](docs/Actions/GLS/troubleshooting.md)
44+
45+
## Contributing
46+
47+
Contributions are welcome! See [Troubleshooting & Community Support](docs/Actions/GLS/troubleshooting.md#contributing) for guidelines.

‎docs/Actions/GLS/configs.md‎

Lines changed: 101 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -1,21 +1,110 @@
11
---
22
title: Action Configuration
3+
description: All configuration options for the GLS Action, including how to obtain credentials from the GLS Developer Portal.
34
---
45

5-
The GLS action provides following configurations:
6+
# GLS Action Configuration
67

7-
| Config Name | Description | Type | Required |
8-
|-----------------|------------------------------------------------------------------|-------------|----------|
9-
| contact_id | The contact id used in some requests | string | No |
10-
| client_id | The client id used for auth purposes | string | Yes |
11-
| client_secret | The client secret used for auth purposes | string | Yes |
12-
| ship_it_api_url | Gls provides multiple ship it urls, provide yours | string | No |
13-
| auth_url | Gls provides multiple auth urls, provide yours ending in /token | string | No |
14-
| shipper | And default shipper which is replaced in the request if provided | GLS_SHIPPER | No |
8+
The GLS action requires a few credentials to authenticate with the GLS ShipIT API. These are set as **configuration values** in the Hercules admin panel (not as environment variables).
159

10+
---
11+
12+
## Configuration reference
13+
14+
| Config Name | Type | Required | Default | Description |
15+
|-----------------|-------------|----------|---------|-------------|
16+
| `client_id` | string | **Yes** | — | OAuth2 client ID for authenticating with the GLS API |
17+
| `client_secret` | string | **Yes** | — | OAuth2 client secret for authenticating with the GLS API |
18+
| `contact_id` | string | No | `""` | GLS contact ID used in some API requests (see note below) |
19+
| `ship_it_api_url` | string | No | `https://api.gls-group.net/shipit-farm/v1/backend/rs` | GLS ShipIT API base URL |
20+
| `auth_url` | string | No | `https://api.gls-group.net/oauth2/v2/token` | GLS OAuth2 token endpoint — must end in `/token` |
21+
| `shipper` | GLS_SHIPPER | No | — | Default shipper address used when no shipper is provided in the shipment data |
22+
23+
> **`contact_id`:** This identifier is required for certain shipment operations (e.g. end-of-day reports and some services). It is issued by GLS support — contact them directly to request it.
24+
25+
---
26+
27+
## How to obtain your credentials
28+
29+
### Step 1 — Create a GLS Developer account
30+
31+
1. Go to [https://dev-portal.gls-group.net/get-started](https://dev-portal.gls-group.net/get-started)
32+
2. Click **Sign In** and register a new account, or log in with an existing GLS account
33+
3. Complete the registration and verify your email address
34+
35+
### Step 2 — Create an application
36+
37+
1. After logging in, navigate to **My Apps** in the top navigation
38+
2. Click **Create App** (or **New Application**)
39+
3. Fill in the application name and description
40+
4. Select the required API scopes (typically **ShipIT**)
41+
5. Submit the form
42+
43+
### Step 3 — Retrieve your credentials
44+
45+
1. Open the application you just created in **My Apps**
46+
2. Copy the **Client ID** — this is your `client_id`
47+
3. Copy the **Client Secret** — this is your `client_secret`
48+
49+
> Keep the `client_secret` confidential. Do not commit it to source control.
50+
51+
### Step 4 — Get your Contact ID (optional)
52+
53+
The `contact_id` is not available in the developer portal. You must contact **GLS support** directly and ask them to provide you with a Contact ID linked to your GLS contract.
54+
55+
---
56+
57+
## API endpoints
58+
59+
GLS provides different API endpoints depending on your region and environment. The defaults point to the global production API:
60+
61+
| Setting | Default URL |
62+
|---------|-------------|
63+
| `ship_it_api_url` | `https://api.gls-group.net/shipit-farm/v1/backend/rs` |
64+
| `auth_url` | `https://api.gls-group.net/oauth2/v2/token` |
65+
66+
If you are using a regional or sandbox endpoint, update these values accordingly. Always ensure `auth_url` ends with `/token`.
67+
68+
---
69+
70+
## Authentication flow
71+
72+
The GLS Action authenticates using **OAuth2 client credentials**:
73+
74+
```
75+
GLS Action
76+
│
77+
├── POST {auth_url}
78+
│ body: grant_type=client_credentials
79+
│ client_id=<your-client-id>
80+
│ client_secret=<your-client-secret>
81+
│
82+
│◄── { access_token, expires_in }
83+
│
84+
└── All subsequent API calls include:
85+
Authorization: Bearer <access_token>
86+
```
87+
88+
Tokens are **cached** and automatically refreshed 60 seconds before they expire. You do not need to manage token lifecycle manually.
89+
90+
---
91+
92+
## Default shipper
93+
94+
The optional `shipper` config allows you to set a **default sender address** that is applied to all shipments when no shipper is explicitly provided in the shipment data. This is useful when all your shipments originate from the same address.
1695

17-
For you to receive that credentials you need to follow this guide: https://dev-portal.gls-group.net/get-started#sign-in
96+
The value must be a valid `GLS_SHIPPER` object:
1897

19-
You can receive the client id and secret under "My Apps" after creating one.
98+
```json
99+
{
100+
"Address": {
101+
"Name1": "My Company GmbH",
102+
"CountryCode": "DE",
103+
"City": "Berlin",
104+
"Street": "Hauptstrasse",
105+
"ZIPCode": "10115"
106+
}
107+
}
108+
```
20109

21-
The Contact id needs to be retrieved from GLS support, so you need to contact them and ask for it.
110+
See [Types — GLS_SHIPPER](./types#GLS_SHIPPER) for the full field reference.

‎docs/Actions/GLS/events.md‎

Lines changed: 174 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,174 @@
1+
---
2+
title: GLS Action Events
3+
description: Events emitted by the GLS Action — what they are, how they trigger flows in Aquila, and what future events are planned.
4+
---
5+
6+
# GLS Action Events
7+
8+
In the Hercules platform, **events** are notifications emitted **by an action** that trigger flows in Aquila. They are the opposite of functions: instead of a flow calling the action, the action pushes data to Aquila, which starts any flows that are listening for that event type.
9+
10+
---
11+
12+
## How events work
13+
14+
```
15+
External world (e.g. GLS webhook / polling)
16+
│
17+
│ something happens (parcel delivered, shipment arrived, ...)
18+
▼
19+
GLS Action
20+
│
21+
│ sdk.dispatchEvent(eventType, projectId, payload)
22+
▼
23+
Aquila
24+
│
25+
│ routes event to all flows listening for eventType
26+
▼
27+
Your Flow starts
28+
│
29+
│ event payload available as flow input
30+
▼
31+
Flow nodes execute (functions, conditions, etc.)
32+
```
33+
34+
An event carries a **payload** — the data associated with what happened (e.g. shipment details, tracking ID, status). Flows that subscribe to an event type receive this payload as their starting input.
35+
36+
---
37+
38+
## Current status
39+
40+
> **The GLS Action does not currently emit any events.**
41+
>
42+
> The GLS action presently only exposes **functions** (called by flows) and registers **data types** and **configuration**. Event support — where the action proactively notifies Aquila of changes — is **planned for a future release**.
43+
44+
---
45+
46+
## Planned events
47+
48+
The following events are candidates for future implementation. Once added, each will allow you to build flows that react automatically to GLS shipment lifecycle changes.
49+
50+
### `gls.shipment.arrived`
51+
52+
Emitted when a parcel arrives at a GLS depot or is scanned into the GLS network.
53+
54+
**Trigger mechanism:** The action would periodically poll the GLS tracking API (or receive a GLS webhook) and emit this event for each new scan.
55+
56+
**Payload type (planned):** `GLS_TRACKING_EVENT`
57+
58+
```
59+
GLS Action (polling / webhook listener)
60+
│
61+
│ detects new scan for tracked parcel
62+
▼
63+
sdk.dispatchEvent("gls.shipment.arrived", projectId, {
64+
TrackID: "12345678",
65+
Status: "IN_TRANSIT",
66+
Location: "MUC-HUB",
67+
Timestamp: "2025-06-01T10:30:00Z"
68+
})
69+
│
70+
▼
71+
Aquila → triggers all flows subscribed to "gls.shipment.arrived"
72+
```
73+
74+
---
75+
76+
### `gls.shipment.delivered`
77+
78+
Emitted when a parcel is confirmed delivered to the recipient.
79+
80+
**Payload type (planned):** `GLS_TRACKING_EVENT`
81+
82+
```
83+
sdk.dispatchEvent("gls.shipment.delivered", projectId, {
84+
TrackID: "12345678",
85+
Status: "DELIVERED",
86+
DeliveredAt: "2025-06-02T14:15:00Z",
87+
SignedBy: "J. Doe"
88+
})
89+
```
90+
91+
---
92+
93+
### `gls.shipment.failed`
94+
95+
Emitted when a delivery attempt fails (e.g. recipient not home, address problem).
96+
97+
**Payload type (planned):** `GLS_TRACKING_EVENT`
98+
99+
```
100+
sdk.dispatchEvent("gls.shipment.failed", projectId, {
101+
TrackID: "12345678",
102+
Status: "DELIVERY_FAILED",
103+
Reason: "RECIPIENT_NOT_HOME",
104+
NextAttempt: "2025-06-03"
105+
})
106+
```
107+
108+
---
109+
110+
### `gls.shipment.returned`
111+
112+
Emitted when a parcel is returned to sender after failed delivery attempts.
113+
114+
---
115+
116+
## How events are implemented (SDK reference)
117+
118+
When events are added to the GLS Action, they will follow this pattern from the Hercules SDK:
119+
120+
### 1. Register the flow type (event definition)
121+
122+
```typescript
123+
sdk.registerFlowTypes({
124+
identifier: "gls.shipment.arrived",
125+
editable: false,
126+
inputType: "GLS_TRACKING_EVENT",
127+
linkedDataTypes: ["GLS_TRACKING_EVENT"],
128+
name: [{ code: "en-US", content: "GLS Shipment Arrived" }],
129+
description: [{
130+
code: "en-US",
131+
content: "Triggered when a GLS parcel arrives at a depot or is scanned."
132+
}]
133+
})
134+
```
135+
136+
### 2. Dispatch the event when it occurs
137+
138+
```typescript
139+
sdk.dispatchEvent(
140+
"gls.shipment.arrived", // must match registered flow type identifier
141+
projectId, // which project to notify
142+
payload // data payload (must match inputType)
143+
)
144+
```
145+
146+
### 3. User builds a flow triggered by the event
147+
148+
In the Hercules UI, users create a flow with **"GLS Shipment Arrived"** as the trigger. When the GLS action dispatches this event, Aquila starts the flow and provides the payload (e.g. `TrackID`, `Status`, `Location`) as the flow's input.
149+
150+
---
151+
152+
## Flow type settings
153+
154+
Flow types can expose **settings** that allow users to configure how an event filters or behaves. For example, a future `gls.shipment.arrived` event might let users specify:
155+
156+
| Setting | Type | Description |
157+
|---------|------|-------------|
158+
| `trackId` | string | Only trigger for a specific parcel |
159+
| `statusFilter` | string[] | Only trigger for specific status codes |
160+
161+
Settings are defined in the `settings` array of `HerculesFlowType` and are configurable per-flow in the Hercules UI.
162+
163+
---
164+
165+
## Difference between events and functions
166+
167+
| | Events | Functions |
168+
|-|--------|-----------|
169+
| **Direction** | Action → Aquila | Flow → Action |
170+
| **Who initiates** | The action (proactively) | The flow (on demand) |
171+
| **Purpose** | React to something that happened externally | Perform an operation and return a result |
172+
| **SDK method** | `registerFlowTypes` + `dispatchEvent` | `registerFunctionDefinitions` |
173+
| **Example** | Parcel delivered → trigger notification flow | Create a shipment and return the label |
174+
| **Current GLS status** | ❌ Not yet implemented | ✅ 26 functions available |

0 commit comments

Comments
 (0)