wflow-api 0.1.0__py3-none-any.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- wflow_api/__init__.py +20 -0
- wflow_api/auth.py +85 -0
- wflow_api/client.py +130 -0
- wflow_api/errors.py +13 -0
- wflow_api/guards.py +132 -0
- wflow_api/models/__init__.py +128 -0
- wflow_api/models/account.py +127 -0
- wflow_api/models/admin.py +98 -0
- wflow_api/models/common.py +117 -0
- wflow_api/models/documents.py +514 -0
- wflow_api/models/registers.py +165 -0
- wflow_api/models/requests.py +341 -0
- wflow_api/models/storage.py +38 -0
- wflow_api/operation.py +50 -0
- wflow_api/operations/__init__.py +21 -0
- wflow_api/operations/account.py +46 -0
- wflow_api/operations/admin.py +307 -0
- wflow_api/operations/approvals.py +235 -0
- wflow_api/operations/document_files.py +145 -0
- wflow_api/operations/document_properties.py +204 -0
- wflow_api/operations/document_tags.py +60 -0
- wflow_api/operations/documents.py +603 -0
- wflow_api/operations/integrations.py +63 -0
- wflow_api/operations/organization.py +51 -0
- wflow_api/operations/registers.py +2273 -0
- wflow_api/operations/storage_files.py +477 -0
- wflow_api/operations/storage_folders.py +132 -0
- wflow_api/operations/webhooks.py +67 -0
- wflow_api/py.typed +0 -0
- wflow_api-0.1.0.dist-info/METADATA +48 -0
- wflow_api-0.1.0.dist-info/RECORD +33 -0
- wflow_api-0.1.0.dist-info/WHEEL +4 -0
- wflow_api-0.1.0.dist-info/licenses/LICENSE +202 -0
|
@@ -0,0 +1,307 @@
|
|
|
1
|
+
"""Roles, Teams and Users tags: who exists in the workspace, and what they may do."""
|
|
2
|
+
|
|
3
|
+
from wflow_api.client import WflowClient
|
|
4
|
+
from wflow_api.guards import path_segment, query_params, write_json
|
|
5
|
+
from wflow_api.models import (
|
|
6
|
+
OrgSlug,
|
|
7
|
+
Page,
|
|
8
|
+
Paged,
|
|
9
|
+
PageSize,
|
|
10
|
+
Query,
|
|
11
|
+
Role,
|
|
12
|
+
RoleBase,
|
|
13
|
+
RoleUpdate,
|
|
14
|
+
Search,
|
|
15
|
+
Sort,
|
|
16
|
+
Team,
|
|
17
|
+
TeamBase,
|
|
18
|
+
TeamUpdate,
|
|
19
|
+
User,
|
|
20
|
+
UserFull,
|
|
21
|
+
UserUpdate,
|
|
22
|
+
WriteResult,
|
|
23
|
+
)
|
|
24
|
+
from wflow_api.operation import operation
|
|
25
|
+
|
|
26
|
+
|
|
27
|
+
@operation
|
|
28
|
+
async def list_roles(
|
|
29
|
+
client: WflowClient,
|
|
30
|
+
organization: OrgSlug,
|
|
31
|
+
search: Search = None,
|
|
32
|
+
sort: Sort = None,
|
|
33
|
+
query: Query = None,
|
|
34
|
+
pageSize: PageSize = None,
|
|
35
|
+
page: Page = None,
|
|
36
|
+
) -> Paged[RoleBase]:
|
|
37
|
+
"""Roles configured in the workspace — named bundles of rights assignable to users.
|
|
38
|
+
|
|
39
|
+
Fields:
|
|
40
|
+
|
|
41
|
+
- `id` — pass to `get_role`
|
|
42
|
+
- `name`, `description`
|
|
43
|
+
"""
|
|
44
|
+
payload = await client.request(
|
|
45
|
+
"GET",
|
|
46
|
+
f"/api/{organization}/roles",
|
|
47
|
+
params=query_params(search=search, sort=sort, query=query, pageSize=pageSize, page=page),
|
|
48
|
+
)
|
|
49
|
+
return Paged[RoleBase].model_validate(payload or {})
|
|
50
|
+
|
|
51
|
+
|
|
52
|
+
@operation
|
|
53
|
+
async def get_role(client: WflowClient, organization: OrgSlug, id: str) -> Role:
|
|
54
|
+
"""One role in full, by its role id.
|
|
55
|
+
|
|
56
|
+
Get the id from `list_roles`.
|
|
57
|
+
|
|
58
|
+
Fields: beyond those on the list summary —
|
|
59
|
+
|
|
60
|
+
- `users` — each user holding this role, as an id and identity
|
|
61
|
+
- `rights` — the permission strings this role grants, e.g. CanApprove,
|
|
62
|
+
CanCreateDocument, CanManageSettings
|
|
63
|
+
"""
|
|
64
|
+
payload = await client.request("GET", f"/api/{organization}/roles/{path_segment(id)}") or {}
|
|
65
|
+
return Role.model_validate(payload)
|
|
66
|
+
|
|
67
|
+
|
|
68
|
+
@operation
|
|
69
|
+
async def list_teams(
|
|
70
|
+
client: WflowClient,
|
|
71
|
+
organization: OrgSlug,
|
|
72
|
+
search: Search = None,
|
|
73
|
+
sort: Sort = None,
|
|
74
|
+
query: Query = None,
|
|
75
|
+
pageSize: PageSize = None,
|
|
76
|
+
page: Page = None,
|
|
77
|
+
) -> Paged[TeamBase]:
|
|
78
|
+
"""Teams configured in the workspace — groups of users assignable to approval steps.
|
|
79
|
+
|
|
80
|
+
Fields:
|
|
81
|
+
|
|
82
|
+
- `id` — pass to `get_team`
|
|
83
|
+
- `name`, `description`
|
|
84
|
+
- `system` — true for a built-in team rather than one the organization created
|
|
85
|
+
"""
|
|
86
|
+
payload = await client.request(
|
|
87
|
+
"GET",
|
|
88
|
+
f"/api/{organization}/teams",
|
|
89
|
+
params=query_params(search=search, sort=sort, query=query, pageSize=pageSize, page=page),
|
|
90
|
+
)
|
|
91
|
+
return Paged[TeamBase].model_validate(payload or {})
|
|
92
|
+
|
|
93
|
+
|
|
94
|
+
@operation
|
|
95
|
+
async def get_team(client: WflowClient, organization: OrgSlug, id: str) -> Team:
|
|
96
|
+
"""One team in full, by its team id.
|
|
97
|
+
|
|
98
|
+
Get the id from `list_teams`.
|
|
99
|
+
|
|
100
|
+
Fields: beyond those on the list summary —
|
|
101
|
+
|
|
102
|
+
- `users` — each member, as an id and identity
|
|
103
|
+
"""
|
|
104
|
+
payload = await client.request("GET", f"/api/{organization}/teams/{path_segment(id)}") or {}
|
|
105
|
+
return Team.model_validate(payload)
|
|
106
|
+
|
|
107
|
+
|
|
108
|
+
@operation
|
|
109
|
+
async def list_users(
|
|
110
|
+
client: WflowClient,
|
|
111
|
+
organization: OrgSlug,
|
|
112
|
+
search: Search = None,
|
|
113
|
+
sort: Sort = None,
|
|
114
|
+
query: Query = None,
|
|
115
|
+
pageSize: PageSize = None,
|
|
116
|
+
page: Page = None,
|
|
117
|
+
) -> Paged[User]:
|
|
118
|
+
"""The people with access to this workspace.
|
|
119
|
+
|
|
120
|
+
`get_me` answers this for the signed-in user only. Use this to see everyone, for
|
|
121
|
+
example to work out who can approve a document that is waiting. For one user's
|
|
122
|
+
role, team and per-document-type permissions, follow up with `get_user`.
|
|
123
|
+
|
|
124
|
+
Fields:
|
|
125
|
+
|
|
126
|
+
- `id` — pass to `get_user`
|
|
127
|
+
- `identity` — login, first/last/full name and preferred language
|
|
128
|
+
- `created` — when the account was created
|
|
129
|
+
- `hasFullAccess` — full-access role indicator, which overrides per-type detail
|
|
130
|
+
"""
|
|
131
|
+
payload = await client.request(
|
|
132
|
+
"GET",
|
|
133
|
+
f"/api/{organization}/users",
|
|
134
|
+
params=query_params(search=search, sort=sort, query=query, pageSize=pageSize, page=page),
|
|
135
|
+
)
|
|
136
|
+
return Paged[User].model_validate(payload or {})
|
|
137
|
+
|
|
138
|
+
|
|
139
|
+
@operation
|
|
140
|
+
async def get_user(client: WflowClient, organization: OrgSlug, userId: str) -> UserFull:
|
|
141
|
+
"""One user in full, by their user id.
|
|
142
|
+
|
|
143
|
+
Get the id from `list_users`. Same shape `get_me` returns for the signed-in user.
|
|
144
|
+
|
|
145
|
+
Fields: beyond those on the list summary —
|
|
146
|
+
|
|
147
|
+
- `roles`, `teams` — memberships
|
|
148
|
+
- `documentTypes` — per document type: All, OnlyAssigned or FullAccess
|
|
149
|
+
- `rights` — named rights held here, e.g. CanApprove, CanCreateDocument
|
|
150
|
+
"""
|
|
151
|
+
payload = await client.request("GET", f"/api/{organization}/users/{path_segment(userId)}") or {}
|
|
152
|
+
return UserFull.model_validate(payload)
|
|
153
|
+
|
|
154
|
+
|
|
155
|
+
@operation
|
|
156
|
+
async def delete_role(client: WflowClient, organization: OrgSlug, id: str) -> WriteResult:
|
|
157
|
+
"""Delete one role from the workspace.
|
|
158
|
+
|
|
159
|
+
A role carries rights and holders. `get_role` lists both — read it first, because
|
|
160
|
+
everyone under `users` loses what the role granted them.
|
|
161
|
+
|
|
162
|
+
Fields: on the result —
|
|
163
|
+
|
|
164
|
+
- `action` — "deleted"
|
|
165
|
+
- `resource` — "roles"
|
|
166
|
+
"""
|
|
167
|
+
await client.request("DELETE", f"/api/{organization}/roles/{path_segment(id)}")
|
|
168
|
+
return WriteResult(action="deleted", resource="roles")
|
|
169
|
+
|
|
170
|
+
|
|
171
|
+
@operation
|
|
172
|
+
async def delete_team(client: WflowClient, organization: OrgSlug, id: str) -> WriteResult:
|
|
173
|
+
"""Delete one team from the workspace.
|
|
174
|
+
|
|
175
|
+
Teams are what approval templates and document rights are assigned to, so a team in
|
|
176
|
+
use is referenced well beyond its own record. `get_team` lists its members; system
|
|
177
|
+
teams, flagged `system` by `list_teams`, are wflow's own rather than the
|
|
178
|
+
organization's.
|
|
179
|
+
|
|
180
|
+
Fields: on the result —
|
|
181
|
+
|
|
182
|
+
- `action` — "deleted"
|
|
183
|
+
- `resource` — "teams"
|
|
184
|
+
"""
|
|
185
|
+
await client.request("DELETE", f"/api/{organization}/teams/{path_segment(id)}")
|
|
186
|
+
return WriteResult(action="deleted", resource="teams")
|
|
187
|
+
|
|
188
|
+
|
|
189
|
+
@operation
|
|
190
|
+
async def delete_user(client: WflowClient, organization: OrgSlug, userId: str) -> WriteResult:
|
|
191
|
+
"""Remove one person's access to this workspace.
|
|
192
|
+
|
|
193
|
+
Get the id from `list_users`; `get_user` shows the roles, teams and document-type
|
|
194
|
+
permissions that go with them, which is what this takes away.
|
|
195
|
+
|
|
196
|
+
Fields: on the result —
|
|
197
|
+
|
|
198
|
+
- `action` — "deleted"
|
|
199
|
+
- `resource` — "users"
|
|
200
|
+
"""
|
|
201
|
+
await client.request("DELETE", f"/api/{organization}/users/{path_segment(userId)}")
|
|
202
|
+
return WriteResult(action="deleted", resource="users")
|
|
203
|
+
|
|
204
|
+
|
|
205
|
+
@operation
|
|
206
|
+
async def create_role(client: WflowClient, organization: OrgSlug, role: RoleUpdate) -> WriteResult:
|
|
207
|
+
"""Create a role — a named bundle of rights that users and teams can be given.
|
|
208
|
+
|
|
209
|
+
Use `list_roles` first to check the name is not already taken; this creates rather
|
|
210
|
+
than upserts, so a duplicate name gives you two roles that look alike. `users` is a
|
|
211
|
+
list of user ids, from `list_users`.
|
|
212
|
+
|
|
213
|
+
Fields: on the result —
|
|
214
|
+
|
|
215
|
+
- `action` — "created"
|
|
216
|
+
- `resource` — "roles"
|
|
217
|
+
- `id` — the new role's id
|
|
218
|
+
"""
|
|
219
|
+
created = await client.request("POST", f"/api/{organization}/roles", json=write_json(role))
|
|
220
|
+
return WriteResult(action="created", resource="roles", id=created)
|
|
221
|
+
|
|
222
|
+
|
|
223
|
+
@operation
|
|
224
|
+
async def create_team(client: WflowClient, organization: OrgSlug, team: TeamUpdate) -> WriteResult:
|
|
225
|
+
"""Create a team — the group approval steps and document rights are assigned to.
|
|
226
|
+
|
|
227
|
+
Use `list_teams` first to check the name is not already taken; this creates rather
|
|
228
|
+
than upserts, so a duplicate name gives you two teams that look alike. `users` is a
|
|
229
|
+
list of user ids, from `list_users`.
|
|
230
|
+
|
|
231
|
+
Fields: on the result —
|
|
232
|
+
|
|
233
|
+
- `action` — "created"
|
|
234
|
+
- `resource` — "teams"
|
|
235
|
+
- `id` — the new team's id
|
|
236
|
+
"""
|
|
237
|
+
created = await client.request("POST", f"/api/{organization}/teams", json=write_json(team))
|
|
238
|
+
return WriteResult(action="created", resource="teams", id=created)
|
|
239
|
+
|
|
240
|
+
|
|
241
|
+
@operation
|
|
242
|
+
async def update_role(client: WflowClient, organization: OrgSlug, id: str, role: RoleUpdate) -> WriteResult:
|
|
243
|
+
"""Replace one role's name, description, holders and rights.
|
|
244
|
+
|
|
245
|
+
The submitted object replaces the stored role, so a field you leave out can be
|
|
246
|
+
cleared. `users` and `rights` are whole sets: a holder you omit loses the role, and a
|
|
247
|
+
right you omit is taken off everyone who holds it. `get_role` returns both lists in
|
|
248
|
+
full — read it first and send back everything you mean to keep, `users` as the `id` of
|
|
249
|
+
each holder it lists. Get the role id from `list_roles`.
|
|
250
|
+
|
|
251
|
+
Fields: on the result —
|
|
252
|
+
|
|
253
|
+
- `action` — "updated"
|
|
254
|
+
- `resource` — "roles"
|
|
255
|
+
- `id` — the role's id
|
|
256
|
+
"""
|
|
257
|
+
updated = await client.request("PUT", f"/api/{organization}/roles/{path_segment(id)}", json=write_json(role))
|
|
258
|
+
return WriteResult(action="updated", resource="roles", id=updated)
|
|
259
|
+
|
|
260
|
+
|
|
261
|
+
@operation
|
|
262
|
+
async def update_team(client: WflowClient, organization: OrgSlug, id: str, team: TeamUpdate) -> WriteResult:
|
|
263
|
+
"""Replace one team's name, description and membership.
|
|
264
|
+
|
|
265
|
+
Send the name and description along with the membership: a `description` you leave
|
|
266
|
+
out is cleared, not kept, so the full record is the only correct payload. `users` is a
|
|
267
|
+
whole set: a member you omit is removed from the team, and with it from every
|
|
268
|
+
approval step and document right the team carries. `get_team` returns the membership
|
|
269
|
+
in full — read it first and send back everyone you mean to keep, as the `id` of each
|
|
270
|
+
member it lists. Get the team id from `list_teams`.
|
|
271
|
+
|
|
272
|
+
Fields: on the result —
|
|
273
|
+
|
|
274
|
+
- `action` — "updated"
|
|
275
|
+
- `resource` — "teams"
|
|
276
|
+
- `id` — the team's id
|
|
277
|
+
"""
|
|
278
|
+
updated = await client.request("PUT", f"/api/{organization}/teams/{path_segment(id)}", json=write_json(team))
|
|
279
|
+
return WriteResult(action="updated", resource="teams", id=updated)
|
|
280
|
+
|
|
281
|
+
|
|
282
|
+
@operation
|
|
283
|
+
async def update_user(client: WflowClient, organization: OrgSlug, user: UserUpdate) -> WriteResult:
|
|
284
|
+
"""Add a person to this workspace, or replace what an existing person may do.
|
|
285
|
+
|
|
286
|
+
The person is matched by `login`: if no one in this workspace has it, they are added;
|
|
287
|
+
if someone does, their record is replaced by what you send. Either way the result says
|
|
288
|
+
`"updated"`, so it does not tell you which happened — call `get_user` or `list_users`
|
|
289
|
+
first if that matters.
|
|
290
|
+
|
|
291
|
+
`roles`, `teams` and `documentTypes` are whole sets: a membership you leave out is taken
|
|
292
|
+
away, and omitting `documentTypes` can leave the person able to see nothing. Send the
|
|
293
|
+
rest of the record too: whether a field you omit is kept or cleared is not guaranteed.
|
|
294
|
+
|
|
295
|
+
To change an existing person, read them with `get_user` first and send back everything
|
|
296
|
+
you mean to keep. It returns the same data in its own shape: `roles` and `teams` are
|
|
297
|
+
`{"id": …}` references, `documentTypes` is `{"id": …, "permission": …}`, and `login`
|
|
298
|
+
is the one inside its `identity`.
|
|
299
|
+
|
|
300
|
+
Fields: on the result —
|
|
301
|
+
|
|
302
|
+
- `action` — "updated", whether the person was added or changed
|
|
303
|
+
- `resource` — "users"
|
|
304
|
+
- `id` — the user's id
|
|
305
|
+
"""
|
|
306
|
+
updated = await client.request("PUT", f"/api/{organization}/users", json=write_json(user))
|
|
307
|
+
return WriteResult(action="updated", resource="users", id=updated)
|
|
@@ -0,0 +1,235 @@
|
|
|
1
|
+
"""DocumentApprovals and ApprovalsTemplates tags: approval workflows and the templates they run."""
|
|
2
|
+
|
|
3
|
+
from wflow_api.client import WflowClient
|
|
4
|
+
from wflow_api.guards import path_segment, query_params, write_json
|
|
5
|
+
from wflow_api.models import (
|
|
6
|
+
ApprovalsTemplate,
|
|
7
|
+
ApprovalsTemplateFull,
|
|
8
|
+
ApprovalsTemplateTeams,
|
|
9
|
+
ApprovalsTemplateUpdate,
|
|
10
|
+
OrgSlug,
|
|
11
|
+
Page,
|
|
12
|
+
Paged,
|
|
13
|
+
PageSize,
|
|
14
|
+
Query,
|
|
15
|
+
Search,
|
|
16
|
+
Sort,
|
|
17
|
+
WriteResult,
|
|
18
|
+
)
|
|
19
|
+
from wflow_api.models.documents import ApprovalProcess
|
|
20
|
+
from wflow_api.operation import operation
|
|
21
|
+
|
|
22
|
+
|
|
23
|
+
@operation
|
|
24
|
+
async def get_document_approvals(client: WflowClient, organization: OrgSlug, documentId: str) -> ApprovalProcess:
|
|
25
|
+
"""The approval path assigned to one document, and its progress so far.
|
|
26
|
+
|
|
27
|
+
Fields:
|
|
28
|
+
|
|
29
|
+
- `pathName` — the name of the approval template applied
|
|
30
|
+
- `items` — one entry per level, each with the assigned `team` or `identity`,
|
|
31
|
+
its `status` (NotApproved, Approved, Rejected, Returned or None) and, once
|
|
32
|
+
acted on, the `date`
|
|
33
|
+
"""
|
|
34
|
+
return ApprovalProcess.model_validate(
|
|
35
|
+
await client.request("GET", f"/api/{organization}/documents/{path_segment(documentId)}/approvals") or {}
|
|
36
|
+
)
|
|
37
|
+
|
|
38
|
+
|
|
39
|
+
@operation
|
|
40
|
+
async def get_storage_file_approvals(client: WflowClient, organization: OrgSlug, fileId: str) -> ApprovalProcess:
|
|
41
|
+
"""The approval path assigned to one archived file, and its progress so far.
|
|
42
|
+
|
|
43
|
+
Same shape as `get_document_approvals`, for a storage file instead of an approval
|
|
44
|
+
document. Get the id from `list_storage_files`.
|
|
45
|
+
|
|
46
|
+
Fields: see `get_document_approvals`.
|
|
47
|
+
"""
|
|
48
|
+
return ApprovalProcess.model_validate(
|
|
49
|
+
await client.request("GET", f"/api/{organization}/storage/files/{path_segment(fileId)}/approvals") or {}
|
|
50
|
+
)
|
|
51
|
+
|
|
52
|
+
|
|
53
|
+
@operation
|
|
54
|
+
async def list_approval_templates(
|
|
55
|
+
client: WflowClient,
|
|
56
|
+
organization: OrgSlug,
|
|
57
|
+
search: Search = None,
|
|
58
|
+
sort: Sort = None,
|
|
59
|
+
query: Query = None,
|
|
60
|
+
pageSize: PageSize = None,
|
|
61
|
+
page: Page = None,
|
|
62
|
+
) -> Paged[ApprovalsTemplate]:
|
|
63
|
+
"""Approval templates configured in the workspace — the approval paths documents follow.
|
|
64
|
+
|
|
65
|
+
Fields:
|
|
66
|
+
|
|
67
|
+
- `id` — pass to `get_approval_template`
|
|
68
|
+
- `name`
|
|
69
|
+
- `isEmpty` — true when the template defines no approval steps
|
|
70
|
+
"""
|
|
71
|
+
payload = await client.request(
|
|
72
|
+
"GET",
|
|
73
|
+
f"/api/{organization}/approvalstemplates",
|
|
74
|
+
params=query_params(search=search, sort=sort, query=query, pageSize=pageSize, page=page),
|
|
75
|
+
)
|
|
76
|
+
return Paged[ApprovalsTemplate].model_validate(payload or {})
|
|
77
|
+
|
|
78
|
+
|
|
79
|
+
@operation
|
|
80
|
+
async def get_approval_template(client: WflowClient, organization: OrgSlug, templateId: str) -> ApprovalsTemplateFull:
|
|
81
|
+
"""One approval template in full, by its template id.
|
|
82
|
+
|
|
83
|
+
Get the id from `list_approval_templates`.
|
|
84
|
+
|
|
85
|
+
Fields: beyond those on the list summary —
|
|
86
|
+
|
|
87
|
+
- `teams` — each assigned team's id and its `level` in the approval process
|
|
88
|
+
- `accessTeams` — team ids granted access automatically once the template applies
|
|
89
|
+
- `conditionFolders` — storage folder ids this template's conditional assignment
|
|
90
|
+
applies to
|
|
91
|
+
- `validationLockLevel`
|
|
92
|
+
"""
|
|
93
|
+
payload = await client.request("GET", f"/api/{organization}/approvalstemplates/{path_segment(templateId)}") or {}
|
|
94
|
+
return ApprovalsTemplateFull.model_validate(payload)
|
|
95
|
+
|
|
96
|
+
|
|
97
|
+
@operation
|
|
98
|
+
async def delete_approval_template(client: WflowClient, organization: OrgSlug, templateId: str) -> WriteResult:
|
|
99
|
+
"""Delete one approval template — an approval path the workspace can assign.
|
|
100
|
+
|
|
101
|
+
The template is workspace configuration, not one document's approval process: this
|
|
102
|
+
removes the path itself, for everything that would have used it. To take the path off
|
|
103
|
+
a single document, use `delete_document_approval_path`. Get the id from
|
|
104
|
+
`list_approval_templates`.
|
|
105
|
+
|
|
106
|
+
Fields: on the result —
|
|
107
|
+
|
|
108
|
+
- `action` — "deleted"
|
|
109
|
+
- `resource` — "approvalstemplates"
|
|
110
|
+
"""
|
|
111
|
+
await client.request("DELETE", f"/api/{organization}/approvalstemplates/{path_segment(templateId)}")
|
|
112
|
+
return WriteResult(action="deleted", resource="approvalstemplates")
|
|
113
|
+
|
|
114
|
+
|
|
115
|
+
@operation
|
|
116
|
+
async def delete_document_approval_path(client: WflowClient, organization: OrgSlug, documentId: str) -> WriteResult:
|
|
117
|
+
"""Take the approval path off one document.
|
|
118
|
+
|
|
119
|
+
The template it was assigned from is untouched; what goes is this document's approval
|
|
120
|
+
process, including the approvals already recorded on it that
|
|
121
|
+
`get_document_approvals` returns. The document itself stays.
|
|
122
|
+
|
|
123
|
+
Fields: on the result —
|
|
124
|
+
|
|
125
|
+
- `action` — "deleted"
|
|
126
|
+
- `resource` — "documents/approvals"
|
|
127
|
+
"""
|
|
128
|
+
await client.request("DELETE", f"/api/{organization}/documents/{path_segment(documentId)}/approvals")
|
|
129
|
+
return WriteResult(action="deleted", resource="documents/approvals")
|
|
130
|
+
|
|
131
|
+
|
|
132
|
+
@operation
|
|
133
|
+
async def delete_storage_file_approval_path(client: WflowClient, organization: OrgSlug, fileId: str) -> WriteResult:
|
|
134
|
+
"""Take the approval path off one archived file.
|
|
135
|
+
|
|
136
|
+
The same as `delete_document_approval_path`, for a storage file instead of an
|
|
137
|
+
approval document: the template survives, this file's approval process does not. Get
|
|
138
|
+
the id from `list_storage_files`.
|
|
139
|
+
|
|
140
|
+
Fields: on the result —
|
|
141
|
+
|
|
142
|
+
- `action` — "deleted"
|
|
143
|
+
- `resource` — "storage/files/approvals"
|
|
144
|
+
"""
|
|
145
|
+
await client.request("DELETE", f"/api/{organization}/storage/files/{path_segment(fileId)}/approvals")
|
|
146
|
+
return WriteResult(action="deleted", resource="storage/files/approvals")
|
|
147
|
+
|
|
148
|
+
|
|
149
|
+
@operation
|
|
150
|
+
async def set_storage_file_approval_path(
|
|
151
|
+
client: WflowClient, organization: OrgSlug, fileId: str, templateId: str
|
|
152
|
+
) -> WriteResult:
|
|
153
|
+
"""Put one archived file through the approval path a template describes.
|
|
154
|
+
|
|
155
|
+
Get `templateId` from `list_approval_templates`; to take the path off rather than
|
|
156
|
+
swap it, use `delete_storage_file_approval_path`. Read `get_storage_file_approvals`
|
|
157
|
+
first where a process is already running: a file that already has a path may be
|
|
158
|
+
refused or may have its path replaced, so take the old path off with
|
|
159
|
+
`delete_storage_file_approval_path` first rather than relying on either outcome.
|
|
160
|
+
|
|
161
|
+
Fields: on the result —
|
|
162
|
+
|
|
163
|
+
- `action` — "set"
|
|
164
|
+
- `resource` — "storage/files/approvals"
|
|
165
|
+
"""
|
|
166
|
+
await client.request(
|
|
167
|
+
"PUT", f"/api/{organization}/storage/files/{path_segment(fileId)}/approvals/set/{path_segment(templateId)}"
|
|
168
|
+
)
|
|
169
|
+
return WriteResult(action="set", resource="storage/files/approvals")
|
|
170
|
+
|
|
171
|
+
|
|
172
|
+
@operation
|
|
173
|
+
async def update_approval_template(
|
|
174
|
+
client: WflowClient, organization: OrgSlug, template: ApprovalsTemplateUpdate
|
|
175
|
+
) -> WriteResult:
|
|
176
|
+
"""Create an approval template, or replace an existing one's steps.
|
|
177
|
+
|
|
178
|
+
A template is workspace configuration, not one document's process: this reaches
|
|
179
|
+
everything the path is assigned to. Matched by the `id` inside `template`. `teams`,
|
|
180
|
+
`accessTeams` and `conditionFolders` are whole sets — a team you leave out is no
|
|
181
|
+
longer part of the path at any level — and send the rest of the template with them:
|
|
182
|
+
a field you omit, `validationLockLevel` included, is cleared rather than kept, so the
|
|
183
|
+
whole record is the only correct payload.
|
|
184
|
+
`get_approval_template` returns all three — read it first and send back
|
|
185
|
+
everything you mean to keep, leaving out its `isEmpty`, which the read computes and
|
|
186
|
+
this operation does not write. Each entry in `teams` is a team id from `list_teams` plus
|
|
187
|
+
the `level` it approves at.
|
|
188
|
+
|
|
189
|
+
Fields: on the result —
|
|
190
|
+
|
|
191
|
+
- `action` — "updated"
|
|
192
|
+
- `resource` — "approvalstemplates"
|
|
193
|
+
- `id` — the template's id
|
|
194
|
+
"""
|
|
195
|
+
created = await client.request(
|
|
196
|
+
"PUT",
|
|
197
|
+
f"/api/{organization}/approvalstemplates",
|
|
198
|
+
json=write_json(template),
|
|
199
|
+
)
|
|
200
|
+
return WriteResult(action="updated", resource="approvalstemplates", id=created)
|
|
201
|
+
|
|
202
|
+
|
|
203
|
+
@operation
|
|
204
|
+
async def set_document_approval_path(
|
|
205
|
+
client: WflowClient,
|
|
206
|
+
organization: OrgSlug,
|
|
207
|
+
documentId: str,
|
|
208
|
+
templateId: str,
|
|
209
|
+
teams: ApprovalsTemplateTeams | None = None,
|
|
210
|
+
) -> WriteResult:
|
|
211
|
+
"""Put one document through the approval path a template describes.
|
|
212
|
+
|
|
213
|
+
**It does not overwrite an existing path — it refuses.** A document already on a path
|
|
214
|
+
is rejected with an error saying so, so swapping a path means calling
|
|
215
|
+
`delete_document_approval_path` first; this operation only ever sets a path on a document
|
|
216
|
+
that has none. Get `templateId` from `list_approval_templates`.
|
|
217
|
+
|
|
218
|
+
Omit `teams` to apply the template as it is configured: the template's own teams
|
|
219
|
+
appear on the document. Sent, `teams` replaces the template's assignment for this
|
|
220
|
+
document rather than adding to it, so name every level you mean to keep — and read
|
|
221
|
+
`get_document_approvals` back afterwards, because the level a team lands on is not
|
|
222
|
+
guaranteed to be the level you sent.
|
|
223
|
+
|
|
224
|
+
Fields: on the result —
|
|
225
|
+
|
|
226
|
+
- `action` — "set"
|
|
227
|
+
- `resource` — "documents/approvals"
|
|
228
|
+
"""
|
|
229
|
+
# httpx sends no body for json=None; `{}` would bind as teams=null, a different instruction.
|
|
230
|
+
await client.request(
|
|
231
|
+
"PUT",
|
|
232
|
+
f"/api/{organization}/documents/{path_segment(documentId)}/approvals/set/{path_segment(templateId)}",
|
|
233
|
+
json=write_json(teams) if teams is not None else None,
|
|
234
|
+
)
|
|
235
|
+
return WriteResult(action="set", resource="documents/approvals")
|
|
@@ -0,0 +1,145 @@
|
|
|
1
|
+
"""DocumentFiles tag: the files attached to a document, and their content."""
|
|
2
|
+
|
|
3
|
+
from typing import Annotated
|
|
4
|
+
|
|
5
|
+
from pydantic import Field
|
|
6
|
+
|
|
7
|
+
from wflow_api.client import WflowClient
|
|
8
|
+
from wflow_api.guards import path_segment, query_params
|
|
9
|
+
from wflow_api.models import OrgSlug, WriteResult
|
|
10
|
+
from wflow_api.models.common import FileContent
|
|
11
|
+
from wflow_api.models.documents import DocumentFile
|
|
12
|
+
from wflow_api.operation import operation
|
|
13
|
+
|
|
14
|
+
|
|
15
|
+
@operation
|
|
16
|
+
async def list_document_files(client: WflowClient, organization: OrgSlug, documentId: str) -> list[DocumentFile]:
|
|
17
|
+
"""The files attached to one document — the scan or PDF, plus any annexes.
|
|
18
|
+
|
|
19
|
+
Call this before downloading, to find out which file you want: exactly one is the
|
|
20
|
+
main document and the rest are attachments.
|
|
21
|
+
|
|
22
|
+
Fields:
|
|
23
|
+
|
|
24
|
+
- `name` — the file name as stored
|
|
25
|
+
- `main` — true for the document's primary file; `download_document_main_file`
|
|
26
|
+
fetches this one without needing its id
|
|
27
|
+
- `signed`, `stamped` — whether wflow has applied a signature or a stamp
|
|
28
|
+
- `created` — when it was attached
|
|
29
|
+
"""
|
|
30
|
+
payload = await client.request("GET", f"/api/{organization}/documents/{path_segment(documentId)}/files") or []
|
|
31
|
+
return [DocumentFile.model_validate(item) for item in payload]
|
|
32
|
+
|
|
33
|
+
|
|
34
|
+
@operation
|
|
35
|
+
async def download_document_main_file(
|
|
36
|
+
client: WflowClient, organization: OrgSlug, documentId: str, *, max_bytes: int | None = None
|
|
37
|
+
) -> FileContent:
|
|
38
|
+
"""Download the document's primary file — the scan or PDF the document was made from.
|
|
39
|
+
|
|
40
|
+
Use this when you have a document id and want its content without first listing the
|
|
41
|
+
attachments. The file comes back as its own bytes, exactly as wflow stores it.
|
|
42
|
+
|
|
43
|
+
Fields:
|
|
44
|
+
|
|
45
|
+
- `filename` — as wflow reports it, or null when it sends no name
|
|
46
|
+
- `content_type` — MIME type, e.g. "application/pdf"
|
|
47
|
+
- `content` — the file's bytes
|
|
48
|
+
|
|
49
|
+
With `max_bytes` set, a larger file is refused rather than truncated. A document with no
|
|
50
|
+
primary file is reported as such rather than returned empty.
|
|
51
|
+
"""
|
|
52
|
+
return await client.download(
|
|
53
|
+
f"/api/{organization}/documents/{path_segment(documentId)}/files/main/download", max_bytes=max_bytes
|
|
54
|
+
)
|
|
55
|
+
|
|
56
|
+
|
|
57
|
+
@operation
|
|
58
|
+
async def download_document_file(
|
|
59
|
+
client: WflowClient, organization: OrgSlug, fileId: str, *, max_bytes: int | None = None
|
|
60
|
+
) -> FileContent:
|
|
61
|
+
"""Download one specific file attached to a document, by its file id.
|
|
62
|
+
|
|
63
|
+
Get the id from `list_document_files`. For the primary file, `download_document_main_file`
|
|
64
|
+
saves a call. The file comes back as its own bytes, exactly as wflow stores it.
|
|
65
|
+
|
|
66
|
+
Fields:
|
|
67
|
+
|
|
68
|
+
- `filename` — as wflow reports it, or null when it sends no name
|
|
69
|
+
- `content_type` — MIME type, e.g. "application/pdf"
|
|
70
|
+
- `content` — the file's bytes
|
|
71
|
+
|
|
72
|
+
With `max_bytes` set, a larger file is refused rather than truncated.
|
|
73
|
+
"""
|
|
74
|
+
return await client.download(
|
|
75
|
+
f"/api/{organization}/documents/files/{path_segment(fileId)}/download", max_bytes=max_bytes
|
|
76
|
+
)
|
|
77
|
+
|
|
78
|
+
|
|
79
|
+
@operation
|
|
80
|
+
async def delete_document_file(client: WflowClient, organization: OrgSlug, fileId: str) -> WriteResult:
|
|
81
|
+
"""Delete one file attached to a document. The document itself stays.
|
|
82
|
+
|
|
83
|
+
Get the id from `list_document_files`, which also flags the file marked `main`:
|
|
84
|
+
deleting that one leaves the document without the scan or PDF it was made from.
|
|
85
|
+
|
|
86
|
+
Fields: on the result —
|
|
87
|
+
|
|
88
|
+
- `action` — "deleted"
|
|
89
|
+
- `resource` — "documents/files"
|
|
90
|
+
"""
|
|
91
|
+
await client.request("DELETE", f"/api/{organization}/documents/files/{path_segment(fileId)}")
|
|
92
|
+
return WriteResult(action="deleted", resource="documents/files")
|
|
93
|
+
|
|
94
|
+
|
|
95
|
+
@operation
|
|
96
|
+
async def stamp_document_file(client: WflowClient, organization: OrgSlug, documentId: str, fileId: str) -> WriteResult:
|
|
97
|
+
"""Apply wflow's time stamp to one file attached to a document.
|
|
98
|
+
|
|
99
|
+
The stamp goes into the stored file and nothing takes it off again. Only a
|
|
100
|
+
PDF can be stamped; any other file is rejected as an unsupported file type.
|
|
101
|
+
`list_document_files` reports which files already carry one as `stamped`, and a
|
|
102
|
+
document type can stamp automatically — `list_document_types` shows that as `autoStamp`.
|
|
103
|
+
|
|
104
|
+
Fields: on the result —
|
|
105
|
+
|
|
106
|
+
- `action` — "stamped"
|
|
107
|
+
- `resource` — "documents/files"
|
|
108
|
+
"""
|
|
109
|
+
await client.request(
|
|
110
|
+
"PUT", f"/api/{organization}/documents/{path_segment(documentId)}/files/{path_segment(fileId)}/stamp"
|
|
111
|
+
)
|
|
112
|
+
return WriteResult(action="stamped", resource="documents/files")
|
|
113
|
+
|
|
114
|
+
|
|
115
|
+
@operation
|
|
116
|
+
async def upload_document_file(
|
|
117
|
+
client: WflowClient,
|
|
118
|
+
organization: OrgSlug,
|
|
119
|
+
documentId: str,
|
|
120
|
+
filename: str,
|
|
121
|
+
content: bytes,
|
|
122
|
+
main: Annotated[bool | None, Field(default=None, description="Make this the document's primary file")] = None,
|
|
123
|
+
) -> WriteResult:
|
|
124
|
+
"""Attach a file to a document: its bytes, and the `filename` wflow should store it under.
|
|
125
|
+
|
|
126
|
+
The file joins whatever is already attached and nothing existing is touched. `main`
|
|
127
|
+
true instead makes it the document's primary file — the one
|
|
128
|
+
`download_document_main_file` fetches — which displaces the file holding that place
|
|
129
|
+
now; `list_document_files` says which one that is.
|
|
130
|
+
|
|
131
|
+
Fields: on the result —
|
|
132
|
+
|
|
133
|
+
- `action` — "created"
|
|
134
|
+
- `resource` — "documents/files"
|
|
135
|
+
- `id` — the new file's id, which `stamp_document_file`, `download_document_file` and
|
|
136
|
+
`delete_document_file` all take; null if wflow sends no body
|
|
137
|
+
"""
|
|
138
|
+
created = await client.upload(
|
|
139
|
+
"PUT",
|
|
140
|
+
f"/api/{organization}/documents/{path_segment(documentId)}/files/upload",
|
|
141
|
+
filename,
|
|
142
|
+
content,
|
|
143
|
+
params=query_params(main=main),
|
|
144
|
+
)
|
|
145
|
+
return WriteResult(action="created", resource="documents/files", id=created)
|