🔍 Contents
-
Prerequisites
-
Authentication
-
Overview of Endpoints
-
Creating & Updating Activities
-
Managing Descriptions
-
Managing Planning Data
-
Retrieving Status History
-
Technical Notes
-
Tips & Best Practices
-
FAQ
📋 Prerequisites
-
🔐 API credentials (Username + Password for HTTP Basic Auth)
-
📄 API YAML file for use with Swagger or code generators
-
🧪 A tool for executing API calls (Swagger, Postman, Power Automate, script)
🔑 Authentication
Authentication is performed via HTTP Basic Auth:
Authorization: Basic <Base64-encoded-username:password>
🔗 Overview of Endpoints
Managing Activities
| Method | Path | Description |
|---|---|---|
| GET | /exchange/processactivities |
Retrieve a list of all activities in a board |
| POST | /exchange/processactivities |
Create a new activity |
| GET | /exchange/processactivities/{id} |
Retrieve an activity in detail |
| PUT | /exchange/processactivities/{id} |
Update an activity |
| DELETE | /exchange/processactivities/{id} |
Delete an activity |
📸 Screenshot: Endpoints in Swagger UI
Managing Descriptions
| Method | Path |
|---|---|
| GET | /exchange/processactivities/{id}/description |
| PUT | /exchange/processactivities/{id}/description |
Managing Planning Data
| Method | Path |
|---|---|
| GET | /exchange/processactivities/{id}/planning |
| PUT | /exchange/processactivities/{id}/planning |
Status History
| Method | Path |
|---|---|
| GET | /exchange/processactivities/{id}/status-history |
Retrieving Metadata
| Method | Path |
|---|---|
| GET | /exchange/processboard-categories |
| GET | /exchange/processboard-labels |
| GET | /exchange/processboards/{id} |
📌 Creating an Activity (POST)
Example body:
{
"title": "Complete process step",
"category": "UUID-of-category",
"team": "UUID-of-team",
"responsiblePerson": "UUID-of-person",
"labels": ["UUID-of-label"]
}
✨ Tip: Use labels for flexible filtering in dashboards.
✏️ Updating an Activity (PUT)
Send only the fields that need to be changed.
Example:
{
"title": "Adjusted title",
"category": "new-category-UUID"
}
⚠️ Note: If the phase is changed, new start and end dates are automatically set.
📝 Managing Descriptions
Retrieve:
GET /exchange/processactivities/{id}/description
Update:
PUT /exchange/processactivities/{id}/description
Content-Type: text/html
Example:
<p>New description in HTML format</p>
🗓 Managing Planning Data
Planning specifies which phases were planned for which dates.
Example:
{
"planings": [
{
"phase": "UUID-OF-PHASE",
"plannedEndDate": "2025-08-30"
}
]
}
📊 Retrieving Status History
GET /exchange/processactivities/{id}/status-history
Returns a list of status changes.
📌 Technical Notes
-
Required fields:
title,category,team,responsiblePerson -
Planning supports multiple phases per activity
-
Categories & labels must be retrieved via metadata endpoints
-
API actions are logged under the user
"API-USER"
✨ Tips & Best Practices
-
Use UUIDs from
/processboards/{id}for labels, categories, phases -
Keep planning data up to date for accurate monitoring
-
Use structured titles for easy identification
-
Test your API calls in Swagger or Postman before production use
❓ FAQ
Which fields are required when creating an activity?
→ title, category, team, responsiblePerson
How do I find out which labels or categories are available?
→ Use the endpoints /processboard-labels and /processboard-categories
Can I change planning data later?
→ Yes, via the PUT endpoint /processactivities/{id}/planning
How is the progress of an activity documented?
→ Through phase planning and, if applicable, status changes
Can I delete activities?
→ Yes, with DELETE /exchange/processactivities/{id}