OpenXPKI::Client::UI::Workflow

Generic UI handler class to render a workflow into gui elements. It first present a description of the workflow generated from the initial states description and a start button which creates the instance. Due to the workflow internals we are unable to fetch the field info from the initial state and therefore a workflow must not require any input fields at the time of creation. A brief description is given at the end of this document.

UI Methods

init_index

Requires parameter wf_type and shows the intro page of the workflow. The headline is the value of type followed by an intro text as given as workflow description. At the end of the page a button names "start" is shown.

This is usually used to start a workflow from the menu or link, e.g.

    workflow!index!wf_type!change_metadata

init_start

Same as init_index but directly creates the workflow and displays the result of the initial action. Normal workflows will result in a redirect using the workflow id, volatile workflows are displayed directly. This works only with workflows that do not require any initial parameters.

init_load

Requires parameter wf_id which is the id of an existing workflow. It loads the workflow at the current state and tries to render it using the __render_from_workflow method. In states with multiple actions wf_action can be set to select one of them. If those arguments are not set from the CGI environment, they can be passed as method arguments.

init_context

Requires parameter wf_id which is the id of an existing workflow. Shows the context as plain key/value pairs - usually called in a popup.

init_attribute

Requires parameter wf_id which is the id of an existing workflow. Shows the assigned attributes as plain key/value pairs - usually called in a popup.

init_info

Requires parameter wf_id which is the id of an existing workflow. It loads the process information to be displayed in a modal popup, used mainly from the workflow search / result lists.

Render form for the workflow search. #TODO: Preset parameters

init_result

Load the result of a query, based on a query id and paging information

init_export

Like init_result but send the data as CSV download, default limit is 500!

init_pager

Similar to init_result but returns only the data portion of the table as partial result.

init_history

Render the history as grid view (state/action/user/time)

init_mine

Filter workflows where the current user is the creator, similar to workflow search.

init_task

Outstanding tasks, filter definitions are read from the uicontrol file

init_log

Load and display the technical log file of the workflow

action_index

instance creation

If you pass wf_type, a new workflow instance of this type is created, the inital action is executed and the resulting state is passed to __render_from_workflow.

generic action

The generic action is the default when sending a workflow generated form back to the server. You need to setup the handler from the rendering step, direct posting is not allowed. The cgi environment must present the key wf_token which is a reference to a session based config hash. The config can be created using __register_wf_token, recognized keys are:

wf_fields

An arrayref of fields, that are accepted by the handler. This is usually a copy of the field list send to the browser but also allows to specify additional validators. At minimum, each field must be a hashref with the name of the field:

    [{ name => fieldname1 }, { name => fieldname2 }]

Each input field is mapped to the contextvalue of the same name. Keys ending with empty square brackets "fieldname[]" are considered to form an array, keys having curly brackets "fieldname{subname}" are merged into a hash. Non scalar values are serialized before they are submitted.

wf_action

The name of the workflow action that should be executed with the input parameters.

wf_handler

Can hold the full name of a method which is called to handle the current request instead of running the generic handler. See the __delegate_call method for details.

If there are errors, an error message is send back to the browser, if the workflow execution succeeds, the new workflow state is rendered using __render_from_workflow.

action_handle

Execute a workflow internal action (fail, resume, wakeup, archive). Requires the workflow and action to be set in the wf_token info.

action_load

Load a workflow given by wf_id, redirects to init_load

action_select

Handle requests to states that have more than one action. Needs to reference an exisiting workflow either via "wf_token" or "wf_id" and the action to choose with "wf_action". If the selected action does not require any input parameters (has no fields) and does not have an ui override set, the action is executed immediately and the resulting state is used. Otherwise, the selected action is preset and the current state is passed to the __render_from_workflow method.

action_search

Handler for the workflow search dialog, consumes the data from the search form and displays the matches as a grid.

action_bulk

Receive a list of workflow serials (wf_id) plus a workflow action (wf_action) to execute on those workflows. For each given serial the given action is executed. The resulting state for each workflow is shown in a grid table. Methods that require additional parameters are not supported yet.

internal methods

__render_from_workflow ( { wf_id, wf_info, wf_action } )

Internal method that renders the ui components from the current workflow state. The info about the current workflow can be passed as a workflow info hash as returned by the get_workflow_info api method or simply the workflow id. In states with multiple action, the wf_action parameter can tell the method to proceed with this state.

activity selection

If a state has multiple available activities, and no activity is given via wf_action, the page includes the content of the description tag of the state (or the workflow) and a list of buttons rendered from the description of the available actions. For actions without a description tag, the action name is used. If a user clicks one of the buttons, the call gets dispatched to the action_select method.

activity rendering

If the state has only one available activity or wf_action is given, the method loads the list of input fields from the workflow definition and renders one form field per parameter, exisiting context values are filled in.

The type attribute tells how to render the field, accepted basic html types are

    text, hidden, password, textarea, select, checkbox

TODO: stuff below not implemented yet!

For select and checkbox you need to pass suitable options using the source_list or source_class attribute as described in the Workflow manual.

TODO: Meta definitons, custom config

custom handler

You can override the default rendering by setting the uihandle attribute either in the state or in the action defintion. A handler on the state level will always be called regardless of the internal workflow state, a handler on the action level gets called only if the action is selected by above means.

__get_action_buttons

For states having multiple actions, this helper renders a set of buttons to dispatch to the next action. It expects a workflow info structure as single parameter and returns a ref to a list to be put in the buttons field.

__render_input_field

Render the UI code for a input field from the server sided definition. Does translation of labels and mangles values for multi-valued componentes.

This method might dynamically create additional "helper" fields on-the-fly (usually of type hidden) and may thus return a list with several field definitions.

The first returned item is always the one corresponding to the workflow field.

__delegate_call

Used to delegate the rendering to another class, requires the method to dispatch to as string (class + method using the :: notation) and a ref to the args to be passed. If called from within an action, the name of the action is passed as additonal parameter.

__render_result_list

Helper to render the output result list from a sql query result. adds exception/paused label to the state column and status class based on proc and wf state.

__render_list_spec

Create array to pass to UI from specification in config file

__render_fields

__render_workflow_info

Render the technical info of a workflow (state, proc_state, etc). Expects a wf_info structure and optional a wfdetail_config, will fallback to the default display if this is not given.

Expects the userid of a creator and the field definition.

If the field has yaml_template set, the template is parsed with the value of the creator given as key creator in the parameter hash. If the resulting data structure is a hash and has a non-empty key value, it is used as value for the field.

If the field has template set, the result of this template is used as tooltip for the field, the literal value given as creator is used as the visible value. If the namespace of the item is certid, the value will be created as link pointing to the certificate details popup.

If neither one is set, the "creator()" method from the "Metadata" Plugin is used as default renderer.

In case the template does not provide a usable value, the tooltip will show an error message, depending on weather the creator string has a namespace tag or not.

__render_task_list

Expects a hash that defines a workflow query and output rules for a tasklist as defined in the uicontrol section.

__check_for_validation_error

Uses last_reply to check if there was a validation error. If a validation error occured, the field_errors hash is returned and the status variable is set to render the errors in the form view. Returns undef otherwise.

example workflow config

State with default rendering

    <state name="DATA_LOADED">
        <description>I18N_OPENXPKI_WF_STATE_CHANGE_METADATA_LOADED</description>
        <action name="changemeta_update" resulting_state="DATA_UPDATE"/>
        <action name="changemeta_persist" resulting_state="SUCCESS"/>
    </state>
    ...
    <action name="changemeta_update"
        class="OpenXPKI::Server::Workflow::Activity::Noop"
        description="I18N_OPENXPKI_ACTION_UPDATE_METADATA">
        <field name="metadata_update" />
    </action>
    <action name="changemeta_persist"
        class="OpenXPKI::Server::Workflow::Activity::PersistData">
    </action>

When reached first, a page with the text from the description tag and two buttons will appear. The update button has I18N_OPENXPKI_ACTION_UPDATE_METADATA as label an after pushing it, a form with one text field will be rendered. The persist button has no description and will have the action name changemeta_persist as label. As it has no input fields, the workflow will go to the next state without further ui interaction.

State with custom rendering

    <state name="DATA_LOADED" uihandle="OpenXPKI::Client::UI::Workflow::Metadata::render_current_data">
    ....
    </state>

Regardless of what the rest of the state looks like, as soon as the state is reached, the render_current_data method is called.

Action with custom rendering

    <state name="DATA_LOADED">
        <description>I18N_OPENXPKI_WF_STATE_CHANGE_METADATA_LOADED</description>
        <action name="changemeta_update" resulting_state="DATA_UPDATE"/>
        <action name="changemeta_persist" resulting_state="SUCCESS"/>
    </state>

    <action name="changemeta_update"
        class="OpenXPKI::Server::Workflow::Activity::Noop"
        uihandle="OpenXPKI::Client::UI::Workflow::Metadata::render_update_form"
        description="I18N_OPENXPKI_ACTION_UPDATE_METADATA_ACTION">
        <field name="metadata_update"/>
    </action>

While no action is selected, this will behave as the default rendering and show two buttons. After the changemeta_update button was clicked, it calls the render_update_form method. Note: The uihandle does not affect the target of the form submission so you either need to properly setup the environment to use the default action (see action_index) or set the wf_handler to a custom method for parsing the form data.