start_process()

Creates a workflow process instance and starts it in one call. Internally runs wfm.CreateProcessInstance (returning the ProcessId) followed by wfm.StartProcess. Returns the ID of the new process.

1. Signature

  • Sync

  • Async

ecm.workflow.start_process(
    user: ECMOrganisationObjectIdLike,
    workflow: str | ECMWorkflow,
    client_type: str | ECMClientType,
    organisation: str | ECMOrganisation | None = None,
    *,
    variables: Mapping[str, str | RawWorkflowVariable] | None = None,
    documents: Iterable[ECMWorkspaceDocument] | None = None,
) -> str
await ecm.workflow.start_process(
    user: ECMOrganisationObjectIdLike,
    workflow: str | ECMWorkflow,
    client_type: str | ECMClientType,
    organisation: str | ECMOrganisation | None = None,
    *,
    variables: Mapping[str, str | RawWorkflowVariable] | None = None,
    documents: Iterable[ECMWorkspaceDocument] | None = None,
) -> str

2. Parameters

Parameter Type Default Description

user

str | ECMOrganisationObject | ECMOrganisationObjectRef

—

The workflow-organisation user — not the security user GUID. Look it up via ecm.workflow.organisation_objects().

workflow

str | ECMWorkflow

—

The workflow to start: an ECMWorkflow, a family GUID, or a workflow model name. A bare string that looks like a GUID (32 hex chars) is treated as a family id, otherwise as a model name (resolved via workflow_by_name()).

client_type

str | ECMClientType

—

Client type as an ECMClientType, a GUID, or a name. Mandatory — the server rejects an empty client type; there is no "all clients" value.

organisation

str | ECMOrganisation | None

None

Defaults to the active organisation when None (also for any internal name resolution).

variables

Mapping[str, str | RawWorkflowVariable] | ECMWorkflowModel | None

None

Workflow input variables — either a mapping (string values as <WFVar><String>…</String></WFVar>; for non-string variables, a RawWorkflowVariable with pre-serialised XML, see value-format notes below) or a typed model instance from workflow_model_by_name() (recommended — it serialises itself).

documents

Iterable[ECMWorkspaceDocument] | None

None

Documents to place into the workflow file’s workspace.

2.1. ECMWorkspaceDocument

  • id (int) — document ID

  • type (int) — object type ID of the document

  • location (int, default 1) — 1 = SDREL, 2 = system archive

  • moveable (bool, default True) — may move between info area and workspace

  • deleteable (bool, default False) — may delete from the file

  • in_workspace (bool, default True) — True = in workspace (workflow default), False = in info area

3. Return value

The ProcessId (str) of the newly started process.

4. Errors

  • ECMMissingArgumentException — no client type given

  • ECMNotFoundException — a workflow or client-type name does not exist

  • ECMWrongStateException — a workflow or client-type name is ambiguous

5. Examples

5.1. Shortest path: by model name, active organisation

process_id = ecm.workflow.start_process(
    user=user,
    workflow="test",                 # workflow model name
    client_type="#OSECM_Client#",    # client-type name
)
print(process_id)

5.2. With input variables and a document

from ecmind_blue_client.ecm import ECMWorkspaceDocument, RawWorkflowVariable

process_id = ecm.workflow.start_process(
    user=user,
    workflow="test",
    client_type="#OSECM_Client#",
    variables={
        "StringVar": "Hello",
        # scalars (incl. numbers/dates/times) go in as <String> — the server converts
        "IntegerVar": RawWorkflowVariable("<WFVar><String>42</String></WFVar>"),
    },
    documents=[ECMWorkspaceDocument(id=4711, type=131073)],
)

5.3. Full discover-then-start flow

client_type = next(
    ct for ct in ecm.workflow.client_types() if ct.name == "#OSECM_Client#"
)
wf = ecm.workflow.workflow_by_name("test", user, client_type)
process_id = ecm.workflow.start_process(user=user, workflow=wf, client_type=client_type)

6. Variable value formats

Formats verified against the enaio® server, for RawWorkflowVariable:

  • Scalars (string, integer, float, date, time) are sent as <WFVar><String>VALUE</String></WFVar> — the server converts them. Typed tags such as <Integer> are rejected.

  • Datetime expects a Unix epoch timestamp inside the <String>.

  • Lists are not wrapped in <WFVar>: <List><ListItem Id="GUID" Selection="0"><STRING>VALUE</STRING></ListItem></List> (upper-case <STRING> member tag).

  • Records use <Record><Member Name="…​">…​</Member></Record> and must set every member the record type declares.

7. Notes on the server response

  • ClientTypeId must be exactly one GUID on the server. An empty value is rejected with GUID 'ClientTypeId' is not set, and a multi-GUID list as an invalid GUID — there is no "all clients" value (verified empirically against the enaio® test server).

  • wfm.StartProcess always places supplied documents into the workflow file’s workspace.

8. See also