Initiation form

Overview

The Initiation form is a special task that collects user input before a workflow begins execution. When defined in a workflow process, the initiation form presents a form to the user at the moment they start the workflow, allowing them to provide initial data that will be available throughout the workflow’s lifecycle.

The Initiation form is technically a Task node with the reserved name run_config. When the workflow engine detects this task name, it automatically presents the form to the initiating user before starting the workflow execution. This allows workflows to be parameterized and customized based on user input at startup time.

Note

The Initiation form is optional. If your workflow does not require user input before starting, you simply don’t include a task named run_config in your process definition.

Properties

The Initiation form uses the same configuration interface as a Task node, but most properties are not utilized since this task serves a specific pre-execution purpose.

Property	Type	Usage	Description
Name	Text	Required	Must be set to run_config (reserved name). This special name tells the workflow engine to treat this task as the initiation form.
Id	Number	Automatic	Unique identifier automatically generated by the system.
Due date	Days / Hours	Not used	This field is not applicable to the initiation form as the form is presented immediately when starting the workflow.
Repeat	Days / Hours	Not used	This field is not applicable to the initiation form.
Source position	Dropdown	Not applicable	The initiation form does not have source or target positions as it is not connected to other nodes in the workflow diagram. It executes before the workflow starts.
Target position	Dropdown	Not applicable	The initiation form does not have source or target positions as it is not connected to other nodes in the workflow diagram.
Description	Textarea	Optional	Optional field for documenting the purpose of the initiation form and what data it collects.
Form definition	XML Editor	Primary field	This is the main property used in the initiation form. It defines the form fields that will be presented to the user when they start the workflow. The form definition follows the same XML structure as Task node forms. The editor provides three tools accessed via icons above the textarea: - Edit (maximize): Opens the form definition in a popup window for easier editing - Graphical designer: Opens a visual form builder interface - Preview: Shows a preview of how the form will appear to users The editor supports autocomplete functionality. Press Ctrl+Space while typing to display available options and code suggestions.
Assign expression	Script Editor	Required (empty)	While this field is not functionally used for the initiation form, it cannot be left empty due to system validation. The recommended value is to return an empty string: <br>return "";<br>

Caution

Important: The task name must be exactly run_config for the workflow engine to recognize it as an initiation form. Any other name will create a regular task node instead.

Behavior

When a workflow includes an initiation form:

1. The user initiates the workflow (e.g., from a document, folder, or manually)
2. Before the workflow execution begins, the initiation form is presented to the user
3. The user completes the form fields and submits
4. The form field values are stored in the workflow context variables
5. The workflow execution begins at the Start node with the context variables populated

If the workflow does not define an initiation form (no run_config task), the workflow starts immediately without requesting user input.

Form Variables and Context

When a user completes and submits the initiation form, the form field values are automatically saved to the workflow context variables using each field’s name attribute.

For example, a form field defined as:

<input label="Purchase amount" name="purchaseAmount" />

Will create a context variable named purchaseAmount containing an Input object with the value entered by the user. This variable will be accessible throughout the entire workflow execution.

Caution

Important: If a context variable already exists with the same name as a form field, it will be overwritten with the new value when the user submits the initiation form.

Form Definition Example

Here’s an example of an initiation form that collects basic purchase request information:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE workflow-form PUBLIC "-//OpenKM//DTD Workflow Form 1.0//EN"
                                "https://www.openkm.com/dtd/workflow-form-1.0.dtd">
<workflow-form>
  <input label="Requester name" name="requesterName" />
  <input label="Department" name="department" />
  <textarea label="Purchase description" name="description" />
  <input label="Estimated amount" name="amount" />
  <select label="Priority" name="priority">
    <option label="Low" value="low" />
    <option label="Medium" value="medium" />
    <option label="High" value="high" />
  </select>
</workflow-form>

This initiation form will create the following context variables when submitted:

• requesterName - Input object with the requester’s name
• department - Input object with the department name
• description - TextArea object with the purchase description
• amount - Input object with the estimated amount
• priority - Select object with the selected priority value

Assign Expression

As mentioned in the properties table, the Assign expression field must contain a value, but is not used functionally for the initiation form. Use the following simple expression:

return "";

This returns an empty string, satisfying the system’s validation requirement while not affecting the form’s behavior.

Form Definition

Forms are defined using XML syntax according to the OpenKM workflow form specification. The form defines the fields and structure that users will interact with when starting the workflow.

Note

For comprehensive information about form structure, available field types, validation rules, and advanced features, please consult the Workflow forms definition documentation section.

Use Cases

Common scenarios where initiation forms are useful:

• Purchase requests: Collect requester information, department, amount, and description before starting an approval workflow
• Document review: Allow the initiator to specify reviewers, due dates, or review priorities
• Change requests: Gather change details, impact assessment, and priority before routing through approval
• Vacation requests: Collect start date, end date, vacation type, and coverage information
• Project initiation: Capture project name, objectives, stakeholders, and timeline information

Best Practices

• Keep initiation forms focused - only collect essential information needed to start the workflow
• Use clear, descriptive field labels so users understand what information to provide
• Add validation rules to ensure data quality before the workflow starts
• Consider using select fields for standardized data instead of free-text input
• Document the purpose of each field in the Description property
• Test the initiation form thoroughly with representative users to ensure it’s intuitive
• Use the preview function to see how the form will appear before deploying