NAME

OpenXPKI::Server::API2::Plugin::Workflow::create_workflow_instance

COMMANDS

create_workflow_instance

Create a new workflow instance of the given type.

Limitations and requirements:

Each workflow MUST start with a state called INITIAL and MUST have exactly one action. workflow_id and creator are added to the context as virtual values - those can not be changed. creator is set to the username of the current session user, to change this use the SetCreator activity or change the workflow attribute creator directly!

Workflows that fail to complete the INITIAL action are not saved and can not be continued.

Parameters

"workflow" Str - workflow name
"activity" Str - name of the action to execute
This is only required if the workflow has more than one initial action.
"params" HashRef - workflow parameters. Optional, default: {}
"ui_info" Bool - set to 1 to also return detail informations about the workflow that can be used in the UI
"norun" I(persist|detach|watchdog) - if set to persist, the initial context is persisted but the initial action is not run. If set to detach, the initial workflow including its id is returned and the initial action is executed in the background (forked process). It set to watchdog the context is persisted and control is handed over to the watchdog.
"use_lock" HashRef|Str. Optional, default is {}
Create a datapool item as lock using the given namespace and key with the workflow id as value. The workflow is not created and an exception is thrown if a lock with the same key already exists in the namespace.

The lock is commited to the database as soon as the initial action was executed or if norun is set when the next commit occurs. In the meantime the database driver holds a row lock which might have a performance impact. If the workflow crashes during the inital action, the lock will disappear, if the crash happens after the initial action, the lock will remain and point to a broken workflow.

You can define the error handling by setting on_error to:

die - the default, throw an exception
skip - return undef
workflow - return the existing workflow, input is discarded
force - ignore the lock, create new workflow and overwrite lock

Note that force will not stop or modifiy the existing workflow, so the old workflow will loose its relation to the lock id!

The namespace has a default of workflow.lock, so if you dont need to modify neither namespace or error handling you can directly pass the locks key as String instead of using a HashRef.

"tenant" Str. Optional
Assign the new workflow to the given tenant. The value must be a valid tenant for the current session user, if it is not given and tenant mode is turned on, the primary tenant is loaded. Set to the emtpy string to not assign the workflow to any tenant.
"_run_as_system" Bool. Optional
Execute the workflow with the permissions of the system role, disables validation or autodiscovery of the tenant.