set_substitutes()

Sets the substitutes for any number of users or roles in a workflow organisation via wfm.SetSubstitutes. Each entry in the substitutes mapping fully replaces the existing substitute list for the respective user/role; passing an empty iterable clears all substitutes for that entry.

1. Signature

  • Sync

  • Async

ecm.workflow.set_substitutes(
    organisation: str | ECMOrganisation,
    substitutes: Mapping[ECMOrganisationObjectIdLike, Iterable[ECMOrganisationObjectIdLike]],
) -> None
await ecm.workflow.set_substitutes(
    organisation: str | ECMOrganisation,
    substitutes: Mapping[ECMOrganisationObjectIdLike, Iterable[ECMOrganisationObjectIdLike]],
) -> None

The type alias ECMOrganisationObjectIdLike stands for str | ECMOrganisationObject | ECMOrganisationObjectRef — that is, anywhere a GUID is expected, you can also pass an organisation-object instance or reference directly.

2. Parameters

Parameter Type Default Description

organisation

str | ECMOrganisation

—

Organisation ID as a string or an ECMOrganisation instance.

substitutes

Mapping[ECMOrganisationObjectIdLike, Iterable[ECMOrganisationObjectIdLike]]

—

Mapping user/role ID → [substitute IDs]. Both keys and values may be GUID strings, ECMOrganisationObject, or ECMOrganisationObjectRef instances. An empty iterable clears all substitutes for that entry.

3. Return value

None. Raises an exception when the server job returns an error code.

4. Examples

4.1. Set substitutes for a single user

  • Sync

  • Async

org = ecm.workflow.active_organisation()
ecm.workflow.set_substitutes(
    org,
    {"265EF9703E9F430589884976339F0B42": ["46E29564BC464929A0A2ECA5387B4855"]},
)
org = await ecm.workflow.active_organisation()
await ecm.workflow.set_substitutes(
    org,
    {"265EF9703E9F430589884976339F0B42": ["46E29564BC464929A0A2ECA5387B4855"]},
)

4.2. Multiple substitutes via object instances

  • Sync

  • Async

org = ecm.workflow.active_organisation()
users = {o.name: o for o in ecm.workflow.organisation_objects(org)}

ecm.workflow.set_substitutes(
    org,
    {users["Root"]: [users["USER_WITH_RIGHTS"], users["USER_WITHOUT_RIGHTS"]]},
)
org = await ecm.workflow.active_organisation()
users = {o.name: o for o in await ecm.workflow.organisation_objects(org)}

await ecm.workflow.set_substitutes(
    org,
    {users["Root"]: [users["USER_WITH_RIGHTS"], users["USER_WITHOUT_RIGHTS"]]},
)

4.3. Clear substitutes

Pass an empty iterable to remove all substitutes for a user/role:

  • Sync

  • Async

org = ecm.workflow.active_organisation()
ecm.workflow.set_substitutes(org, {"265EF9703E9F430589884976339F0B42": []})
org = await ecm.workflow.active_organisation()
await ecm.workflow.set_substitutes(org, {"265EF9703E9F430589884976339F0B42": []})

5. Notes

  • Any number of users/roles can be updated in a single call.

  • The substitute list is fully replaced (not a delta operation).

  • The change is visible afterwards via the Stellvertreter attribute on organisation_objects() (comma-separated GUID list).

6. See also