Skip to content

Commit 08b262b

Browse files
MertenDMertenD
committed
Add documentation for custom activities
1 parent ea45ee2 commit 08b262b

5 files changed

Lines changed: 242 additions & 3 deletions

File tree

‎public/assets/custom-node/final-process.png‎

22.2 KB
Loading

‎public/assets/custom-node/my-activities-png.PNG‎

-34.8 KB
Binary file not shown.

‎src/content/docs/custom-Activities/0-how-they-work.mdx‎

Lines changed: 86 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,86 @@
1+
---
2+
title: How Custom Activities Work
3+
description: Architecture, communication pattern, and error handling for custom activities at runtime.
4+
---
5+
6+
This document explains **what happens inside the engine** when a running workflow reaches a *custom activity* and how your service must react.
7+
8+
---
9+
## 1 – Sequence Overview
10+
11+
1. **Process instance arrives at the custom node**.
12+
The engine pauses execution and prepares an HTTP request for your service.
13+
2. **Engine → Your endpoint** (HTTP POST). The payload contains:
14+
- `responsePath` – URL to call when the activity succeeds.
15+
- `errorResponsePath` – URL to call when the activity fails.
16+
- `flowElementInstanceId` – Correlates replies with the running instance.
17+
- `data` – All process variables referenced by this activity.
18+
3. **Your service immediately returns `200 OK`** to acknowledge receipt and avoid time‑outs.
19+
4. **Your service performs its business logic** (e.g. calls an external API).
20+
5. **Your service → `responsePath`** (HTTP POST) on success, sending:
21+
```json
22+
{
23+
"flowElementInstanceId": "<id>",
24+
"data": {
25+
"<variableName>": "<value>",
26+
"...": "..."
27+
}
28+
}
29+
```
30+
6. **Engine resumes the workflow**. New/updated variables are now available to downstream nodes.
31+
7. **Error handling** – If something goes wrong call **`errorResponsePath`** instead:
32+
```json
33+
{
34+
"flowElementInstanceId": "<id>",
35+
"errorMessage": "<human‑readable error>"
36+
}
37+
```
38+
The incident is logged and shown in the monitoring UI.
39+
40+
This process is equivalent with manual activities, where the engine waits for user input. The only difference is that the engine does not wait for a human to respond, but for your service to call back.
41+
42+
---
43+
## 2 – Payload Reference
44+
45+
| Field | Direction | Type | Description |
46+
| --- | --- | --- | --- |
47+
| `responsePath` | Engine → Service | `string (URL)` | Callback for successful completion. |
48+
| `errorResponsePath` | Engine → Service | `string (URL)` | Callback for error reporting. |
49+
| `flowElementInstanceId` | Both ways | `string` | Uniquely identifies this node execution. |
50+
| `data` | Engine → Service | `object` | Key–value map of all variables the node needs. |
51+
| `data` | Service → Engine | `object` | Key–value map with **only** the variables you want to create or update. |
52+
| `errorMessage` | Service → Engine | `string` | Human‑readable reason for failure (error path only). |
53+
54+
---
55+
## 3 – Best Practices
56+
57+
- **Respond fast** – Return `200 OK` before you start lengthy work. The engine handles the callback asynchronously.
58+
- **Idempotency** – Your callback endpoints may be retried; make them safe to call twice.
59+
- **Error detail** – Keep `errorMessage` concise yet actionable. Users will see it in the monitoring UI.
60+
61+
---
62+
## 4 – Example Timeline
63+
64+
```text
65+
┌─────────────────────────────┐
66+
│ Workflow Engine │
67+
└──────────────┬──────────────┘
68+
│ POST /my‑activity
69+
│ body: {responsePath, errorResponsePath, ...}
70+
┌──────────────▼──────────────┐
71+
│ Your Service │
72+
└──────────────┬──────────────┘
73+
│ 200 OK (immediate)
74+
│
75+
│ [Business logic]
76+
│
77+
│ POST responsePath — success
78+
│ or
79+
│ POST errorResponsePath — failure
80+
┌──────────────▼──────────────┐
81+
│ Workflow Engine │
82+
└─────────────────────────────┘
83+
```
84+
85+
With this flow in mind you can reliably integrate any external system or custom logic into your automated processes.
86+

‎src/content/docs/custom-Activities/1-create-custom-activity.mdx‎

Lines changed: 155 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,155 @@
1+
---
2+
title: Creating Custom Activities
3+
description: How to develop, configure, and deploy custom manual or automatic activities for your process flows.
4+
---
5+
6+
It is possible to create your own activities that can be used in the editor and then executed on your own server when they are reached in the process. These activities can be either **manual tasks**—made available to users in their worklists for processing—or **automatic activities**, which run immediately without user interaction.
7+
8+
In this walk‑through we build an automatic **ChatGPT** activity. In the editor you will be able to supply a *system prompt* and a *user input*. At runtime the node calls the OpenAI API and writes ChatGPT’s reply back into the workflow. The sample process lets a user enter a topic, asks ChatGPT to explain it, and finally shows the explanation to the user.
9+
10+
![Final Process Preview](/assets/custom-node/final-process.png)
11+
12+
## Step 1 – General Details
13+
14+
Open **`Shop → Create Activity`**. The wizard shows all steps you will complete.
15+
16+
![Step 1 – Introduction](/assets/custom-node/step-1.png)
17+
18+
In the second screen provide the basic metadata:
19+
20+
1. **Display name** shown in the editor
21+
2. **Short description** for the shop
22+
3. **Icon name** (see the catalogue at [Lucide.dev](https://lucide.dev/icons/))
23+
4. **Execution mode** – *Manual* (user works on a form your server renders) or *Automatic* (logic runs on your server without user input)
24+
5. **Detailed description** (Markdown allowed)—use this to document what the node does and how to configure it.
25+
26+
![Step 2 – General Information](/assets/custom-node/step-2.png)
27+
28+
## Step 2 – Editor Options
29+
30+
Define which **configuration fields** the editor should show when someone drops your activity onto the canvas. The values entered there are sent to your server at runtime.
31+
32+
![Step 3 – Editor Options](/assets/custom-node/step-3-1.png)
33+
34+
Click **Add new Option** to insert a field. The list below the button lets you configure each option; the preview on the right shows how the panel will appear in the editor.
35+
36+
![Step 3 – Options Example](/assets/custom-node/step-3-2.png)
37+
38+
Available option types:
39+
40+
| Type | Purpose |
41+
| --- | --- |
42+
| **Text** | Static explanatory text shown between fields. |
43+
| **Input / Textarea** | Single‑line or multi‑line text input. |
44+
| **Select / Select with custom** | Drop‑down list. You can nest further options that appear depending on the selected value. *Select with custom* additionally lets the editor user type their own value. Tip: use `{availableVariables}` as an option value to let users pick any existing process variable. |
45+
| **Checkbox** | Boolean switch; nested options can depend on its state. |
46+
| **Variable Name Input** | Text field where the editor user defines the **target variable** that will receive the node’s output. |
47+
| **Separator** | Horizontal rule to visually group fields. |
48+
| **Row** | Container that arranges child options side by side. |
49+
50+
> **Important**   Every option needs a *label*—internally the label is used as its key.
51+
52+
## Step 3 – Set Up Your Server Endpoint
53+
54+
Tell the wizard where the workflow engine should send the webhook when the node runs.
55+
56+
![Step 4 – Endpoint Setup](/assets/custom-node/step-4-2.png)
57+
58+
The next page offers **downloadable code templates** (ZIP) already wired with your chosen options:
59+
60+
- **Automatic mode** – Node.js and Python stubs implementing an API endpoint that responds to the engine.
61+
- **Manual mode** – A Next.js component that receives the instance data and renders a simple UI.
62+
63+
Make sure you adjust the endpoint URL inside the template if necessary and to implement your business logic.
64+
65+
![Step 4 – Code Samples](/assets/custom-node/step-4-3.png)
66+
67+
### Payload contract
68+
69+
Your server receives the option values **plus** three technical fields:
70+
71+
| Field | Meaning |
72+
| --- | --- |
73+
| `responsePath` | POST your success payload here. |
74+
| `errorResponsePath` | POST error details here. |
75+
| `flowElementInstanceId` | Correlates your reply with the running activity. |
76+
77+
💡 Always return **HTTP 200 OK immediately** to avoid workflow timeouts.
78+
79+
### Example – ChatGPT server (Node.js)
80+
81+
```javascript
82+
const express = require('express');
83+
const axios = require('axios');
84+
const app = express();
85+
86+
app.use((req, res, next) => {
87+
res.header('Access-Control-Allow-Origin', '*');
88+
res.header('Access-Control-Allow-Methods', 'GET, POST, PUT, DELETE, OPTIONS');
89+
res.header('Access-Control-Allow-Headers', 'Content-Type, Authorization');
90+
if (req.method === 'OPTIONS') return res.sendStatus(200);
91+
next();
92+
});
93+
app.use(express.json());
94+
95+
app.post('/call', async (req, res) => {
96+
// 1 — acknowledge immediately
97+
res.sendStatus(200);
98+
99+
const { responsePath, errorResponsePath, flowElementInstanceId } = req.body;
100+
const { openAIAPIKey, prompt, additionalData, outputs } = req.body.data;
101+
const outputVar = outputs.outputVariableName;
102+
103+
try {
104+
const openAiResp = await axios.post(
105+
'https://api.openai.com/v1/chat/completions',
106+
{
107+
model: 'gpt-4o',
108+
messages: [
109+
{ role: 'system', content: prompt },
110+
{ role: 'user', content: additionalData },
111+
],
112+
},
113+
{
114+
headers: {
115+
'Content-Type': 'application/json',
116+
Authorization: `Bearer ${openAIAPIKey}`,
117+
},
118+
},
119+
);
120+
121+
await axios.post(responsePath, {
122+
flowElementInstanceId,
123+
data: { [outputVar]: openAiResp.data.choices[0].message.content },
124+
});
125+
} catch (err) {
126+
await axios.post(errorResponsePath, {
127+
flowElementInstanceId,
128+
errorMessage: `ChatGPT call failed: ${err.message}`,
129+
});
130+
}
131+
});
132+
133+
app.listen(process.env.PORT || 3030, () =>
134+
console.log('ChatGPT node listening …'),
135+
);
136+
```
137+
138+
## Step 4 – Use the Activity
139+
140+
Once saved, the activity appears for everyone under **Shop**. The detail page shows its metadata and an option preview. Click **➕ Add to Editor** to make it available in the **Editor**. Your own created nodes are listed under **My Activities** and your saved nodes for the editor can be managed under **Saved Activities**.
141+
142+
![Step 5 – Shop Detail](/assets/custom-node/details-in-shop.png)
143+
144+
In the sample workflow below, a previous node stores the user‑entered topic in the variable `{input}`. The ChatGPT node reads this value via the **Additional Data** field.
145+
146+
![Step 6 – Editor Usage](/assets/custom-node/create-process-2.png)
147+
148+
Finally, the process shows ChatGPT’s reply (`{chatGPTAnswer}`) to the user in an info‑text task.
149+
150+
![Step 7 – Display Result](/assets/custom-node/create-process-3.png)
151+
152+
---
153+
154+
By following these steps you can package any custom logic—whether a simple webhook or a complex external service—into reusable activities for your processes.
155+

‎src/content/docs/index.mdx‎

Lines changed: 1 addition & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -2,8 +2,6 @@
22
title: Project Overview
33
---
44

5-
import Image from 'next/image';
6-
75
This document serves as the introduction and overview of a Process Aware Information System (PAIS) that integrates gamification to enhance user engagement and streamline process management.
86

97
The system provides a platform that combines an editor for modeling business processes with BPMN 2.0 with an execution engine that runs these processes in real-time. Monitoring tools offer insights into process performance and user activity, ensuring continuous improvement and alignment with business objectives.
@@ -12,6 +10,6 @@ Accounts within the system enable long-term tracking of rewards, potentially int
1210

1311
The monitoring section provides a snapshot of functionality and user interaction with the system, offering a real-world reflection of processes and their effectiveness.
1412

15-
<Image src="./../assets/project-overview.svg" alt="Project Overview Mockup" width={800} height={450} />
13+
![Project Overview Mockup](/assets/project-planning.svg)
1614

1715
The image above illustrates the interface users interact with, showcasing the process modeling and execution environments, as well as the gamification elements that promote user engagement through rewards and a sense of progression.

0 commit comments

Comments
 (0)