mirror of
https://github.com/wekan/wekan.git
synced 2026-11-20 09:45:04 -05:00
#4294 asked for four things. Several triggers and actions, rule variables, renaming in place and rule import/export were built earlier; two parts were still missing. - "I want the assignee to be the creator of the card by default": rules had member actions only. Add and Remove assignee actions take a username, a {creator}/{assignees}/{members} token, the user who triggered the rule, or "*" for every assignee, and write card.assignees. They are durable through Sync like the member actions, with the joinAssignee/unjoinAssignee activities the assignees hook writes. - "give a Rule a default name": Add Rule with an empty title showed an error, and rules.createRule stored the literal "Rule". The title is now optional; the rule is named after its trigger and action ("When ..., then ..."), and the rules list renames it in place. Fixing this found that "Remove all members from the card" iterated the card's assignees while removing from its members: an earlier fix believed assignMember wrote assignees, but both definitions in models/cards.js write members. It removed only members who were also assignees. Remove-all now iterates card.members, in the ordinary and the durable path, and the guards that pinned the wrong collection now read models/cards.js to decide. New text is added in English, pending Transifex. Thanks to xeruf and xet7 ! Fixes #4294.
209 lines
8.1 KiB
Markdown
209 lines
8.1 KiB
Markdown
# Rules (Board Automation / IFTTT) REST API
|
|
|
|
Board automation rules ("IFTTT rules") link a **trigger** (an event on the
|
|
board) to an **action** (what happens to the card/board). The REST API embeds
|
|
the full trigger and action inline, so a rule is self-contained.
|
|
|
|
This API makes the workflow of
|
|
[issue #2674](https://github.com/wekan/wekan/issues/2674) scriptable: add a
|
|
user to a card when it is moved **to** a list, and remove the user again when
|
|
the card is moved **away from** that list.
|
|
|
|
## Summary
|
|
|
|
| HTTP Method | Url | Short Description |
|
|
| :--- | :--- | :--- |
|
|
| `GET` | `/api/boards/:boardId/rules` | List all automation rules of a board |
|
|
| `GET` | `/api/boards/:boardId/rules/:ruleId` | Get one rule (with its trigger and action) |
|
|
| `POST` | `/api/boards/:boardId/rules` | Add an automation rule |
|
|
| `PUT` | `/api/boards/:boardId/rules/:ruleId` | Edit a rule's title, trigger and/or action |
|
|
| `DELETE` | `/api/boards/:boardId/rules/:ruleId` | Remove a rule (and its trigger and action) |
|
|
|
|
All endpoints require a `Bearer` token; write endpoints require board write
|
|
access (BoardAdmin).
|
|
|
|
## Trigger matching and the `*` wildcard
|
|
|
|
The rule engine matches an incoming board activity against **every** matching
|
|
field of the trigger's `activityType` (for example `moveCard` matches on
|
|
`boardId`, `listName`, `oldListName`, `userId`, `swimlaneName`, `cardTitle`).
|
|
A field set to `'*'` matches anything.
|
|
|
|
You only need to supply the fields you want to constrain: any matching field
|
|
missing from the trigger you POST/PUT is stored as the `'*'` wildcard
|
|
automatically. (Before this normalization existed, an API-created trigger
|
|
that omitted a field such as `userId` could never match any activity, so the
|
|
rule silently never fired — the bug reported in issue #2674.)
|
|
|
|
### Trigger `activityType` values
|
|
|
|
| `activityType` | fires when | matching fields |
|
|
| :--- | :--- | :--- |
|
|
| `createCard` | a card is created | `boardId`, `listName`, `userId`, `swimlaneName`, `cardTitle` |
|
|
| `moveCard` | a card is moved to/from a list or swimlane | `boardId`, `listName` (destination), `oldListName` (source), `userId`, `swimlaneName`, `cardTitle` |
|
|
| `archivedCard` / `restoredCard` | a card is archived / unarchived | `boardId`, `userId`, `cardTitle` |
|
|
| `joinMember` / `unjoinMember` | a member is added to / removed from a card | `boardId`, `username`, `userId` |
|
|
| `addChecklist` / `removeChecklist` / `completeChecklist` / `uncompleteChecklist` | checklist events | `boardId`, `checklistName`, `userId` |
|
|
| `addedChecklistItem` / `removedChecklistItem` / `checkedItem` / `uncheckedItem` | checklist item events | `boardId`, `checklistItemName`, `userId` |
|
|
| `addAttachment` / `deleteAttachment` | attachment events | `boardId`, `userId` |
|
|
| `addedLabel` / `removedLabel` | label events | `boardId`, `labelId`, `userId` |
|
|
| `scheduledTrigger` | time-based (due/aging/recurring); see `scheduleKind`, `days`, `atTime` | evaluated by the scheduler, not by activities |
|
|
|
|
For a card moved **to** a list, constrain `listName` (the destination list's
|
|
title). For a card moved **away from** a list, constrain `oldListName` (the
|
|
source list's title) and leave `listName` as `'*'`.
|
|
|
|
### Action `actionType` values
|
|
|
|
`moveCardToTop`, `moveCardToBottom`, `sendEmail`, `setDate`, `updateDate`,
|
|
`removeDate`, `setDateRelative`, `archive`, `unarchive`, `setColor`,
|
|
`addLabel`, `removeLabel`, `addMember`, `removeMember`, `addAssignee`,
|
|
`removeAssignee`, `checkAll`,
|
|
`uncheckAll`, `checkItem`, `uncheckItem`, `addChecklist`, `removeChecklist`,
|
|
`addChecklistWithItems`, `addSwimlane`, `createCard`, `linkCard`,
|
|
`markCardComplete`, `markCardIncomplete`, `sortList`, `moveAllCardsInList`.
|
|
|
|
The member actions take a `username`:
|
|
|
|
* `{"actionType": "addMember", "username": "someuser"}` — add the user to the card
|
|
* `{"actionType": "removeMember", "username": "someuser"}` — remove the user from the card
|
|
* `{"actionType": "removeMember", "username": "*"}` — remove **all** members from the card
|
|
|
|
The assignee actions take the same `username` and act on the card's
|
|
assignees instead of its members:
|
|
|
|
* `{"actionType": "addAssignee", "username": "{creator}"}` — make the card's
|
|
creator its assignee; `{assignees}`, `{members}` and a username work too
|
|
* `{"actionType": "removeAssignee", "username": "*"}` — remove **all** assignees
|
|
|
|
## List rules
|
|
|
|
```shell
|
|
curl -H "Authorization: Bearer TOKEN" \
|
|
-X GET \
|
|
http://localhost:3000/api/boards/BOARDID/rules
|
|
```
|
|
|
|
## Get one rule
|
|
|
|
```shell
|
|
curl -H "Authorization: Bearer TOKEN" \
|
|
-X GET \
|
|
http://localhost:3000/api/boards/BOARDID/rules/RULEID
|
|
```
|
|
|
|
Result example:
|
|
|
|
```json
|
|
{
|
|
"_id": "8gDW2AtwbpNbqSyEw",
|
|
"title": "Remove member when moved away from Doing",
|
|
"trigger": {
|
|
"activityType": "moveCard",
|
|
"listName": "*",
|
|
"oldListName": "Doing",
|
|
"swimlaneName": "*",
|
|
"cardTitle": "*",
|
|
"userId": "*"
|
|
},
|
|
"action": {
|
|
"actionType": "removeMember",
|
|
"username": "someuser"
|
|
}
|
|
}
|
|
```
|
|
|
|
## Add a rule
|
|
|
|
```shell
|
|
curl -H "Authorization: Bearer TOKEN" \
|
|
-H "Content-type: application/json" \
|
|
-X POST \
|
|
http://localhost:3000/api/boards/BOARDID/rules \
|
|
-d '{
|
|
"title": "Add member when moved to Doing",
|
|
"trigger": { "activityType": "moveCard", "listName": "Doing" },
|
|
"action": { "actionType": "addMember", "username": "someuser" }
|
|
}'
|
|
```
|
|
|
|
### Full example: issue #2674 workflow
|
|
|
|
Add the user when a card is moved **to** the list "Doing", remove the user
|
|
again when the card is moved **away from** "Doing":
|
|
|
|
```shell
|
|
# Rule 1: card moved TO "Doing" -> add member
|
|
curl -H "Authorization: Bearer TOKEN" -H "Content-type: application/json" -X POST \
|
|
http://localhost:3000/api/boards/BOARDID/rules \
|
|
-d '{ "title": "Add member on move to Doing",
|
|
"trigger": { "activityType": "moveCard", "listName": "Doing" },
|
|
"action": { "actionType": "addMember", "username": "someuser" } }'
|
|
|
|
# Rule 2: card moved AWAY FROM "Doing" -> remove member
|
|
curl -H "Authorization: Bearer TOKEN" -H "Content-type: application/json" -X POST \
|
|
http://localhost:3000/api/boards/BOARDID/rules \
|
|
-d '{ "title": "Remove member on move from Doing",
|
|
"trigger": { "activityType": "moveCard", "oldListName": "Doing" },
|
|
"action": { "actionType": "removeMember", "username": "someuser" } }'
|
|
```
|
|
|
|
The omitted trigger fields (`listName` in rule 2, `oldListName` in rule 1,
|
|
plus `userId`, `swimlaneName`, `cardTitle`) are stored as `'*'` wildcards.
|
|
|
|
## Edit a rule
|
|
|
|
Any of `title`, `enabled`, `trigger` and `action` may be supplied; a supplied
|
|
trigger or action document replaces the stored fields. When the supplied
|
|
trigger includes an `activityType`, its missing matching fields are defaulted
|
|
to `'*'` too.
|
|
|
|
```shell
|
|
curl -H "Authorization: Bearer TOKEN" \
|
|
-H "Content-type: application/json" \
|
|
-X PUT \
|
|
http://localhost:3000/api/boards/BOARDID/rules/RULEID \
|
|
-d '{ "action": { "actionType": "removeMember", "username": "*" } }'
|
|
```
|
|
|
|
### Pause and resume a rule
|
|
|
|
`enabled: false` pauses the rule without deleting it - its trigger and action
|
|
stay as they are and the rule engine simply skips it - and `enabled: true`
|
|
resumes it. `GET` reports the current `enabled` value of every rule.
|
|
|
|
```shell
|
|
curl -H "Authorization: Bearer TOKEN" \
|
|
-H "Content-type: application/json" \
|
|
-X PUT \
|
|
http://localhost:3000/api/boards/BOARDID/rules/RULEID \
|
|
-d '{ "enabled": false }'
|
|
```
|
|
|
|
## Delete a rule
|
|
|
|
Removes the rule together with its trigger and action documents.
|
|
|
|
```shell
|
|
curl -H "Authorization: Bearer TOKEN" \
|
|
-X DELETE \
|
|
http://localhost:3000/api/boards/BOARDID/rules/RULEID
|
|
```
|
|
|
|
## Python CLI (api.py)
|
|
|
|
The bundled `api.py` exposes the same capability:
|
|
|
|
```shell
|
|
python3 api.py listrules BOARDID
|
|
python3 api.py getrule BOARDID RULEID
|
|
python3 api.py addrule BOARDID 'TITLE' 'TRIGGER_JSON' 'ACTION_JSON'
|
|
python3 api.py editrule BOARDID RULEID 'PATCH_JSON'
|
|
python3 api.py removerule BOARDID RULEID
|
|
|
|
# Issue #2674: remove a user from the card when it is moved away from a list
|
|
python3 api.py addrule BOARDID 'Remove member on move from Doing' \
|
|
'{"activityType":"moveCard","oldListName":"Doing"}' \
|
|
'{"actionType":"removeMember","username":"someuser"}'
|
|
```
|