Meegle API — Setting (Roles)
APIs under this skill: Create Workflow Role, Get Detailed Role Settings, Update Workflow Role Settings, Delete Workflow Role Configuration.
Create Workflow Role
Add a role under the specified work item type. Returns the new Role ID. Permission: Permission Management – Configuration.
When to Use
- When creating a workflow role (e.g. Task, PM, DA) for a work item type
- When configuring member_assign_mode (manual / assign to specified person / assign to creator), is_owner, auto_enter_group, or members (user_key list)
- When you need the returned role ID for Get/Update/Delete Workflow Role or for node/field role bindings
API Spec: create_workflow_role
name: create_workflow_role
type: api
description: >
Add a role under the specified work item type. Returns role ID. role object
includes name, is_owner, auto_enter_group, member_assign_mode, members, is_member_multi, role_alias, lock_scope.
auth:
type: plugin_access_token
header: X-Plugin-Token
user_header: X-User-Key
http:
method: POST
url: https://{domain}/open_api/{project_key}/flow_roles/{work_item_type_key}/create_role
headers:
Content-Type: application/json
X-Plugin-Token: "{{resolved_token}}"
X-User-Key: "{{user_key}}"
path_params:
project_key:
type: string
required: true
description: >
Space ID (project_key) or space domain name (simple_name).
project_key: Double-click space name in Meegle. simple_name: from space URL (e.g. doc).
work_item_type_key:
type: string
required: true
description: Work item type. Obtain via Get work item types in space.
inputs:
role:
type: object
required: true
description: Role configuration.
properties:
id:
type: string
description: Role ID. Optional; if not provided, auto-generated and returned on create.
name:
type: string
description: Role name.
is_owner:
type: boolean
description: Whether this role is the manager for the task.
auto_enter_group:
type: boolean
description: Whether members are automatically added to the group.
member_assign_mode:
type: integer
description: >
1: Add manually; 2: Assign to a specified person by default; 3: Assign to the creator by default.
When 2, members (user_key array) is used.
members:
type: array
items: string
description: Assigned members (user_key). Used when member_assign_mode is 2.
is_member_multi:
type: boolean
description: Restrict to single-person configuration (false) or allow multiple.
role_alias:
type: string
description: Role identifier/alias.
lock_scope:
type: array
description: Lock scope (structure per product).
outputs:
data:
type: string
description: Role ID (e.g. 5727769).
constraints:
- Permission: Permission Management – Configuration
error_mapping:
20006: Invalid param (role id already exists; change the id)
Usage notes
- role.id: Optional; omit to let the server generate and return the role ID. If provided and already exists, 20006 is returned.
- member_assign_mode: 1 = manual add; 2 = assign to specified person (set members with user_key list); 3 = assign to creator by default.
- members: Only meaningful when member_assign_mode is 2; values are user_key (from Meegle, e.g. double-click avatar in Developer Platform).
- data: Use the returned role ID when calling Get Detailed Role Settings, Update Workflow Role Settings, or Delete Workflow Role Configuration, or when binding roles to nodes/fields.
Get Detailed Role Settings
Obtain the configuration of all roles and personnel under the specified work item type. Response follows the RelationDetail structure (id, name, is_owner, role_appear_mode, deletable, auto_enter_group, member_assign_mode, members, is_member_multi). Permission: Permission Management – Process Roles.
When to Use
- When listing all workflow roles (e.g. PM, DA) for a work item type and their settings
- When you need role id, member_assign_mode, members (user_key list), or deletable for Update/Delete Workflow Role or for UI display
- When building role management UIs or syncing role configuration
API Spec: get_detailed_role_settings
name: get_detailed_role_settings
type: api
description: >
Obtain all roles and personnel configuration under the specified work item type.
Returns list per RelationDetail: id, name, is_owner, role_appear_mode, deletable,
auto_enter_group, member_assign_mode, members, is_member_multi.
auth:
type: plugin_access_token
header: X-Plugin-Token
user_header: X-User-Key
http:
method: GET
url: https://{domain}/open_api/{project_key}/flow_roles/{work_item_type_key}
headers:
X-Plugin-Token: "{{resolved_token}}"
X-User-Key: "{{user_key}}"
path_params:
project_key:
type: string
required: true
description: >
Space ID (project_key) or space domain name (simple_name).
project_key: Double-click space name in Meegle. simple_name: from space URL (e.g. doc).
work_item_type_key:
type: string
required: true
description: Work item type. Obtain via Get work item types in space.
outputs:
data:
type: array
description: >
List of RelationDetail. Each has id, name, is_owner, role_appear_mode,
deletable, auto_enter_group, member_assign_mode, members (user_key array),
is_member_multi.
constraints:
- Permission: Permission Management – Process Roles
error_mapping:
1000052062: Project key is wrong (project_key incorrect)
Usage notes
- data items: Use id when updating or deleting a role (Update Workflow Role Settings, Delete Workflow Role Configuration). deletable indicates whether the role can be deleted.
- member_assign_mode and members: Same semantics as Create Workflow Role (1 manual, 2 specified members, 3 creator). role_appear_mode: Display/visibility mode per product.
Update Workflow Role Settings
Update a role under the specified work item type. Identify the role by role_id or role_alias (one required; role_id takes precedence if both are sent). Permission: Permission Management – Process Roles.
When to Use
- When changing role name, is_owner, auto_enter_group, member_assign_mode, members, is_member_multi, role_alias, or lock_scope
- When role_id or role_alias comes from Get Detailed Role Settings
- When member_assign_mode is 2, members must be provided (non-empty)
API Spec: update_workflow_role_settings
name: update_workflow_role_settings
type: api
description: >
Update a role under the specified work item type. One of role_id or role_alias
required (role_id preferred). role object contains updated config.
auth:
type: plugin_access_token
header: X-Plugin-Token
user_header: X-User-Key
http:
method: POST
url: https://{domain}/open_api/{project_key}/flow_roles/{work_item_type_key}/update_role
headers:
Content-Type: application/json
X-Plugin-Token: "{{resolved_token}}"
X-User-Key: "{{user_key}}"
path_params:
project_key:
type: string
required: true
description: >
Space ID (project_key) or space domain name (simple_name).
project_key: Double-click space name in Meegle. simple_name: from space URL (e.g. doc).
work_item_type_key:
type: string
required: true
description: Work item type. Obtain via Get work item types in space.
inputs:
role_id:
type: string
required: false
description: Process role ID from Get Detailed Role Settings. One of role_id or role_alias required; role_id preferred if both sent.
role_alias:
type: string
required: false
description: Role docking identifier from Get Detailed Role Settings. One of role_id or role_alias required.
role:
type: object
required: true
description: Updated role configuration.
properties:
name: { type: string }
is_owner: { type: boolean }
auto_enter_group: { type: boolean }
member_assign_mode: { type: integer }
members: { type: array, items: string }
is_member_multi: { type: boolean }
role_alias: { type: string }
lock_scope: { type: array }
outputs:
data:
type: object
description: Empty on success.
constraints:
- Permission: Permission Management – Process Roles
- One of role_id or role_alias must be provided
- When member_assign_mode is 2, members must be non-empty
error_mapping:
20006: Invalid param (members should not be empty when member_assign_mode is 2)
20006: Invalid param (role_id does not exist; obtain via Get Detailed Role Settings)
Usage notes
- role_id or role_alias: Provide one to identify the role to update; get from Get Detailed Role Settings (data[].id or role_alias). If both are sent, role_id is used.
- role: Same shape as Create Workflow Role (name, is_owner, auto_enter_group, member_assign_mode, members, is_member_multi, role_alias, lock_scope). When member_assign_mode is 2, members must be a non-empty user_key array (20006 otherwise).
Delete Workflow Role Configuration
Delete a role under the specified work item type. Identify the role by role_id or role_alias (one required; role_id takes precedence if both are sent). Permission: Permission Management – Configuration.
When to Use
- When removing a workflow role (e.g. PM, DA) from a work item type
- When role_id or role_alias comes from Get Detailed Role Settings
- Role must not be in use in process template nodes (else 20093)
API Spec: delete_workflow_role_configuration
name: delete_workflow_role_configuration
type: api
description: >
Delete a role under the specified work item type. One of role_id or role_alias
required (role_id preferred). Role cannot be referenced in template nodes.
auth:
type: plugin_access_token
header: X-Plugin-Token
user_header: X-User-Key
http:
method: POST
url: https://{domain}/open_api/{project_key}/flow_roles/{work_item_type_key}/delete_role
headers:
Content-Type: application/json
X-Plugin-Token: "{{resolved_token}}"
X-User-Key: "{{user_key}}"
path_params:
project_key:
type: string
required: true
description: >
Space ID (project_key) or space domain name (simple_name).
project_key: Double-click space name in Meegle. simple_name: from space URL (e.g. doc).
work_item_type_key:
type: string
required: true
description: Work item type. Obtain via Get work item types in space.
inputs:
role_id:
type: string
required: false
description: Process role ID from Get Detailed Role Settings. One of role_id or role_alias required; role_id preferred if both sent.
role_alias:
type: string
required: false
description: Role docking identifier from Get Detailed Role Settings. One of role_id or role_alias required.
outputs:
data:
type: object
description: Empty on success.
constraints:
- Permission: Permission Management – Configuration
- One of role_id or role_alias must be provided
- Role must not be referenced in process template nodes (else 20093)
error_mapping:
20093: Role in use (cannot delete; role is referenced in template nodes)
20006: Invalid param (role_id does not exist or has been deleted; obtain via Get Detailed Role Settings)
Usage notes
- role_id or role_alias: Provide one to identify the role to delete; get from Get Detailed Role Settings. If both are sent, role_id is used.
- 20093: The role is referenced in workflow template nodes and cannot be deleted until those references are removed.
- 20006: The given role_id does not exist or was already deleted; confirm via Get Detailed Role Settings.
1---2name: meegle-api-setting-roles3description: Meegle OpenAPI for workflow roles: create, get, update, delete.4---5
6# Meegle API — Setting (Roles)
7
8APIs under this skill: Create Workflow Role, Get Detailed Role Settings, Update Workflow Role Settings, Delete Workflow Role Configuration.
9
10---
11
12## Create Workflow Role
13
14Add a role under the specified work item type. Returns the new **Role ID**. Permission: Permission Management – Configuration.
15
16### When to Use
17
18- When creating a workflow role (e.g. Task, PM, DA) for a work item type
19- When configuring **member_assign_mode** (manual / assign to specified person / assign to creator), **is_owner**, **auto_enter_group**, or **members** (user_key list)
20- When you need the returned role ID for Get/Update/Delete Workflow Role or for node/field role bindings
21
22### API Spec: create_workflow_role
23
24```yaml
25name: create_workflow_role
26type: api
27description: >
28 Add a role under the specified work item type. Returns role ID. role object
29 includes name, is_owner, auto_enter_group, member_assign_mode, members, is_member_multi, role_alias, lock_scope.
30
31auth:
32 type: plugin_access_token
33 header: X-Plugin-Token
34 user_header: X-User-Key
35
36http:
37 method: POST
38 url: https://{domain}/open_api/{project_key}/flow_roles/{work_item_type_key}/create_role
39 headers:
40 Content-Type: application/json
41 X-Plugin-Token: "{{resolved_token}}"
42 X-User-Key: "{{user_key}}"
43
44path_params:
45 project_key:
46 type: string
47 required: true
48 description: >
49 Space ID (project_key) or space domain name (simple_name).
50 project_key: Double-click space name in Meegle. simple_name: from space URL (e.g. doc).
51 work_item_type_key:
52 type: string
53 required: true
54 description: Work item type. Obtain via Get work item types in space.
55
56inputs:
57 role:
58 type: object
59 required: true
60 description: Role configuration.
61 properties:
62 id:
63 type: string
64 description: Role ID. Optional; if not provided, auto-generated and returned on create.
65 name:
66 type: string
67 description: Role name.
68 is_owner:
69 type: boolean
70 description: Whether this role is the manager for the task.
71 auto_enter_group:
72 type: boolean
73 description: Whether members are automatically added to the group.
74 member_assign_mode:
75 type: integer
76 description: >
77 1: Add manually; 2: Assign to a specified person by default; 3: Assign to the creator by default.
78 When 2, members (user_key array) is used.
79 members:
80 type: array
81 items: string
82 description: Assigned members (user_key). Used when member_assign_mode is 2.
83 is_member_multi:
84 type: boolean
85 description: Restrict to single-person configuration (false) or allow multiple.
86 role_alias:
87 type: string
88 description: Role identifier/alias.
89 lock_scope:
90 type: array
91 description: Lock scope (structure per product).
92
93outputs:
94 data:
95 type: string
96 description: Role ID (e.g. 5727769).
97
98constraints:
99 - Permission: Permission Management – Configuration
100
101error_mapping:
102 20006: Invalid param (role id already exists; change the id)
103```
104
105### Usage notes
106
107- **role.id**: Optional; omit to let the server generate and return the role ID. If provided and already exists, 20006 is returned.
108- **member_assign_mode**: **1** = manual add; **2** = assign to specified person (set **members** with user_key list); **3** = assign to creator by default.
109- **members**: Only meaningful when **member_assign_mode** is **2**; values are **user_key** (from Meegle, e.g. double-click avatar in Developer Platform).
110- **data**: Use the returned role ID when calling Get Detailed Role Settings, Update Workflow Role Settings, or Delete Workflow Role Configuration, or when binding roles to nodes/fields.
111
112---
113
114## Get Detailed Role Settings
115
116Obtain the configuration of all roles and personnel under the specified work item type. Response follows the RelationDetail structure (id, name, is_owner, role_appear_mode, deletable, auto_enter_group, member_assign_mode, members, is_member_multi). Permission: Permission Management – Process Roles.
117
118### When to Use
119
120- When listing all workflow roles (e.g. PM, DA) for a work item type and their settings
121- When you need role **id**, **member_assign_mode**, **members** (user_key list), or **deletable** for Update/Delete Workflow Role or for UI display
122- When building role management UIs or syncing role configuration
123
124### API Spec: get_detailed_role_settings
125
126```yaml
127name: get_detailed_role_settings
128type: api
129description: >
130 Obtain all roles and personnel configuration under the specified work item type.
131 Returns list per RelationDetail: id, name, is_owner, role_appear_mode, deletable,
132 auto_enter_group, member_assign_mode, members, is_member_multi.
133
134auth:
135 type: plugin_access_token
136 header: X-Plugin-Token
137 user_header: X-User-Key
138
139http:
140 method: GET
141 url: https://{domain}/open_api/{project_key}/flow_roles/{work_item_type_key}
142 headers:
143 X-Plugin-Token: "{{resolved_token}}"
144 X-User-Key: "{{user_key}}"
145
146path_params:
147 project_key:
148 type: string
149 required: true
150 description: >
151 Space ID (project_key) or space domain name (simple_name).
152 project_key: Double-click space name in Meegle. simple_name: from space URL (e.g. doc).
153 work_item_type_key:
154 type: string
155 required: true
156 description: Work item type. Obtain via Get work item types in space.
157
158outputs:
159 data:
160 type: array
161 description: >
162 List of RelationDetail. Each has id, name, is_owner, role_appear_mode,
163 deletable, auto_enter_group, member_assign_mode, members (user_key array),
164 is_member_multi.
165
166constraints:
167 - Permission: Permission Management – Process Roles
168
169error_mapping:
170 1000052062: Project key is wrong (project_key incorrect)
171```
172
173### Usage notes
174
175- **data** items: Use **id** when updating or deleting a role (Update Workflow Role Settings, Delete Workflow Role Configuration). **deletable** indicates whether the role can be deleted.
176- **member_assign_mode** and **members**: Same semantics as Create Workflow Role (1 manual, 2 specified members, 3 creator). **role_appear_mode**: Display/visibility mode per product.
177
178---
179
180## Update Workflow Role Settings
181
182Update a role under the specified work item type. Identify the role by **role_id** or **role_alias** (one required; **role_id** takes precedence if both are sent). Permission: Permission Management – Process Roles.
183
184### When to Use
185
186- When changing role name, is_owner, auto_enter_group, member_assign_mode, members, is_member_multi, role_alias, or lock_scope
187- When **role_id** or **role_alias** comes from Get Detailed Role Settings
188- When member_assign_mode is 2, **members** must be provided (non-empty)
189
190### API Spec: update_workflow_role_settings
191
192```yaml
193name: update_workflow_role_settings
194type: api
195description: >
196 Update a role under the specified work item type. One of role_id or role_alias
197 required (role_id preferred). role object contains updated config.
198
199auth:
200 type: plugin_access_token
201 header: X-Plugin-Token
202 user_header: X-User-Key
203
204http:
205 method: POST
206 url: https://{domain}/open_api/{project_key}/flow_roles/{work_item_type_key}/update_role
207 headers:
208 Content-Type: application/json
209 X-Plugin-Token: "{{resolved_token}}"
210 X-User-Key: "{{user_key}}"
211
212path_params:
213 project_key:
214 type: string
215 required: true
216 description: >
217 Space ID (project_key) or space domain name (simple_name).
218 project_key: Double-click space name in Meegle. simple_name: from space URL (e.g. doc).
219 work_item_type_key:
220 type: string
221 required: true
222 description: Work item type. Obtain via Get work item types in space.
223
224inputs:
225 role_id:
226 type: string
227 required: false
228 description: Process role ID from Get Detailed Role Settings. One of role_id or role_alias required; role_id preferred if both sent.
229 role_alias:
230 type: string
231 required: false
232 description: Role docking identifier from Get Detailed Role Settings. One of role_id or role_alias required.
233 role:
234 type: object
235 required: true
236 description: Updated role configuration.
237 properties:
238 name: { type: string }
239 is_owner: { type: boolean }
240 auto_enter_group: { type: boolean }
241 member_assign_mode: { type: integer }
242 members: { type: array, items: string }
243 is_member_multi: { type: boolean }
244 role_alias: { type: string }
245 lock_scope: { type: array }
246
247outputs:
248 data:
249 type: object
250 description: Empty on success.
251
252constraints:
253 - Permission: Permission Management – Process Roles
254 - One of role_id or role_alias must be provided
255 - When member_assign_mode is 2, members must be non-empty
256
257error_mapping:
258 20006: Invalid param (members should not be empty when member_assign_mode is 2)
259 20006: Invalid param (role_id does not exist; obtain via Get Detailed Role Settings)
260```
261
262### Usage notes
263
264- **role_id** or **role_alias**: Provide one to identify the role to update; get from **Get Detailed Role Settings** (data[].id or role_alias). If both are sent, **role_id** is used.
265- **role**: Same shape as Create Workflow Role (name, is_owner, auto_enter_group, member_assign_mode, members, is_member_multi, role_alias, lock_scope). When **member_assign_mode** is **2**, **members** must be a non-empty user_key array (20006 otherwise).
266
267---
268
269## Delete Workflow Role Configuration
270
271Delete a role under the specified work item type. Identify the role by **role_id** or **role_alias** (one required; **role_id** takes precedence if both are sent). Permission: Permission Management – Configuration.
272
273### When to Use
274
275- When removing a workflow role (e.g. PM, DA) from a work item type
276- When **role_id** or **role_alias** comes from Get Detailed Role Settings
277- Role must not be in use in process template nodes (else 20093)
278
279### API Spec: delete_workflow_role_configuration
280
281```yaml
282name: delete_workflow_role_configuration
283type: api
284description: >
285 Delete a role under the specified work item type. One of role_id or role_alias
286 required (role_id preferred). Role cannot be referenced in template nodes.
287
288auth:
289 type: plugin_access_token
290 header: X-Plugin-Token
291 user_header: X-User-Key
292
293http:
294 method: POST
295 url: https://{domain}/open_api/{project_key}/flow_roles/{work_item_type_key}/delete_role
296 headers:
297 Content-Type: application/json
298 X-Plugin-Token: "{{resolved_token}}"
299 X-User-Key: "{{user_key}}"
300
301path_params:
302 project_key:
303 type: string
304 required: true
305 description: >
306 Space ID (project_key) or space domain name (simple_name).
307 project_key: Double-click space name in Meegle. simple_name: from space URL (e.g. doc).
308 work_item_type_key:
309 type: string
310 required: true
311 description: Work item type. Obtain via Get work item types in space.
312
313inputs:
314 role_id:
315 type: string
316 required: false
317 description: Process role ID from Get Detailed Role Settings. One of role_id or role_alias required; role_id preferred if both sent.
318 role_alias:
319 type: string
320 required: false
321 description: Role docking identifier from Get Detailed Role Settings. One of role_id or role_alias required.
322
323outputs:
324 data:
325 type: object
326 description: Empty on success.
327
328constraints:
329 - Permission: Permission Management – Configuration
330 - One of role_id or role_alias must be provided
331 - Role must not be referenced in process template nodes (else 20093)
332
333error_mapping:
334 20093: Role in use (cannot delete; role is referenced in template nodes)
335 20006: Invalid param (role_id does not exist or has been deleted; obtain via Get Detailed Role Settings)
336```
337
338### Usage notes
339
340- **role_id** or **role_alias**: Provide one to identify the role to delete; get from **Get Detailed Role Settings**. If both are sent, **role_id** is used.
341- **20093**: The role is referenced in workflow template nodes and cannot be deleted until those references are removed.
342- **20006**: The given role_id does not exist or was already deleted; confirm via Get Detailed Role Settings.
modbender