Skip to main content
Version: 10.0

Stages and Workflows

The steps of the form processing workflow ("stages") can be defined by a JSON file. This file is named "stages.json" and can be provided as part of your template definition.

Note: "Stages" require a Server version 7.2.* or higher AND an App version 7.3 or higher!

JSON File

​

The JSON file serves as the "configuration file" for stages and workflows initialized by clicking the toolbar button "Approve".

Unless a stages.json file is provided, the Form Definition is processed in "stage 1" with all default settings.

The JSON file consists of two objects: stages and workflows.

The stage definition must include a next definition, specifying what should happen if a stage is approved (Form.Status == Approved). The form will progress to the next stage when all defined workflows of the current stage have successfully completed, or it will finish if only one stage is defined.

{
    "stages": {
        "stage_1": {
            "first": true,
            "label": "Stage 1",
            "appKioskMode": false,
            "next": {
                "stage": "stage_2",
                "workflows": ["wf_pdf","wf_cond1" "wf_email1", "wf_grp1", "wf_excel" ],
                "buttonLabel": "Approve Stage 1: {{field_id}}",
                "dialogTitle": "Approve dialog title",
                "dialogMessage": "Message text of the approve dialog - Finishing {{field_id}}"
            },
            "stateChanges": {
                "Group": {
                    "workflows": [ "wf_email1" ]
                }
            }
        },
        "stage_ ...": {

        },
        "stage_final": {
            "label": "Stage final",
            "next": {
                "workflows": [ "wf_archive" ]
            }
        }
    },
    "workflows": {
        "wf_pdf": {
            "type": "pdf",
            "create": true
        },
        "wf_email1": {
            "type": "email",
            "to": "office@icomedias.com",
            "subject": "New HybridForms process created ",
            "body": "A new HybridForms process was created.",
            "erroraction": "ignore",
            "errorfeedback": "Notification could not be sent",
            "errornotify": "admin@icomedias.com",
            "filename": "email-filename.pdf",
            "attachPDF": true,
            "attachImages": true,
            "attachimage":"form-logo.png"
        },
        "wf_email2" : {
            "type": "email",
            "to": "office@icomedias.com",
            "subject": "A new form",
            "template": "mailtemplate.txt"
        },
        "wf_grp1": {
            "type": "setgroup",
            "group": "icoad\\ag-sachbearbeiter"
        },
         "wf_current_grp": {
            "type": "setcurrentgroup",
            "group": "icoad\\ag-mitarbeiter"
        },
        "wf_archive": {
            "type": "setstatus",
            "status": "Archived"
        },
        "wf_current_archived": {
            "type": "setcurrentstatus",
            "status": "Archived"
        },
        "wf_cond1": {
            "type": "condition",
            "condition": "{field} != True"
        },
        "wf_newValue": {
            "type": "setfield",
            "field": "fieldID",
            "value": "new Value"
        },
        "wf_newCheckboxValue": {
            "type": "setfield",
            "field": "fieldID",
            "value": "{true}"
        },
        "wf_newRadioboxValue": {
            "type": "setfield",
            "field": "fieldID",
            "value": "{null}"
        },
        "wf-newform": {
            "type": "newform",
            "title": "{Title}",
            "template": "bc40e199-e8a1-4a4f-9b53-a5e8f16154c0",
            "status": "Edit",
            "stage": "S1",
            "owner": "user@hybridforms.net",
            "group": "hf-group",
            "fields": {
                "name" : "{name_textfield}",
                "date": "{work_date}"
            }
        },
        "wf_owner": {
            "type": "setowner",
            "owner": "{fieldValueUPN}"
        },
        "wf_current_owner": {
            "type": "setcurrentowner",
            "owner": "{Editor}"
        },
        "wf_excel": {
            "type": "createexcel",
            "template": "excel_template.xlsx",
            "filename": "form.xlsx",
            "errorNotify": "admin@icomedias.com",
            "errorFeedback": "Fehler beim Erzeugen des Excel"
        }
    }
}
Note

Workflows executed by finishing a "one-stage" Form Item must be defined inside a stages.json as well, simply skip the entry "stage" inside the "next" object.

"S1": {
    "first": true,
    "label": "Default Stage",
    "next": {
        "workflows": ["wf_email"]
    }
}

If the stage enging is enabled, the App kiosk mode is disabled by default. The App kiosk mode could be activated for a specific stage.

Note

Stages and workflows can also be created and edited in the Admin UI. Go to the FormDefinition template, in the section "stages" click the "Edit"-button. Edit Stages in Admin UIDark Edit Stages in Admin UI

Stage Object

​

Configure a stage object by specifying a custom name (e.g. "stage_1" ) and the values for the keys label, next, stagechanges and once first.

Info

The key-value pairs label, next and first are required and first must be unique.

PropertyTypeHow to useDescription
firstBoolean"first": trueSpecify the stage where to start.
labelString"label": "Stage 1"Set the ID/name of the stage used in your form for conditions.
appKioskModeBoolean"appKioskMode": falseDe/activate App Kiosk Mode button for this stage. App Kiosk Mode must be enabled for form (App Kiosk Mode). Default value is true.
nextObject"next": { }Define the options of the workflows initialized by finishing the stage.
../stageString"next": {"stage":"stage_final"}Set the stage processed next.
../workflowsJSON Array"next": {"workflows": ["wf_pdf","wf_cond1" "wf_email1", "wf_grp1"] }Specify the workflows invoked by finishing the stage.
../buttonLabelString"next": {"buttonLabel":"Approve Stage 1: {{field_id}}"}For better usability define an appropriate label of the "Approve" button in the form toolbar for each stage. {{field_id}} placeholder gets replaced by list data value.
../dialogTitleString"next": {"dialogTitle": "Approve dialog title"}Specify the title of the approve dialog for each stage. {{field_id}} placeholder gets replaced by list data value.
../dialogMessageString"next": {"dialogMessage": "Message text of the approve dialog"}Specify the approve dialog message text for each stage. {{field_id}} placeholder gets replaced by list data value.
stateChangesObject"stateChanges": { "Group": {"workflows": [ "wf_email1" ] } }Define the workflows invoked by changing the form's status in the stage's life cycle.

Workflow Object

​

Define all your workflows invoked by stage or status changes.

These workflows can be used multiple times and can be of different types: conditions, requests, emails sent or changes of the Form Item meta data (e.g the owner or the assigned group).

Note

The workflows are processed in order of the JSON array position. A workflow of "type": "condition" is applied to all following workflows until a new condition is defined. in the example {"workflows": ["wf_pdf","wf_cond1", "wf_email1", "wf_grp1"]} the condition of the workflow "wf_cond1" controls the execution of workflow "wf_email1" and "wf_group".

Workflow Definitions

​

Common​

Common options for every workflow option typically include type specifications and error handling mechanisms (such as retries, logging, and notifications).

type - required​

Set the type of the workflow, further properties are available depending on the type.
How to use:
"type": "pdf"
Type: string

errorAction​

Define the action in case the workflow fails: "ignore" skips the failed workflow and proceeds as defined, "status=Edit[, stage]" stops any workflow execution and sets the Form Item status (and optionally the form stage) to the specified status. "fields" sets the specified fields to the specified values.
How to use:
"errorAction": "ignore / status=Edit[, stage] / fields={fieldname: fieldvalue, ...}"
Type: string

errorFeedback​

Provide an error message (List page feedback dialog).
How to use:
"errorFeedback": "Email dispatch failed."
Type: string

errorNotify​

Provide an email address for an error notification email.
How to use:
"errorNotify": "admin@domain.net"
Type: string

errorNotifySubject​

Provide an email subject for an error notification email.
How to use:
"errorNotifySubject": "Workflow error"
Type: string

errorNotifyTemplate​

Provide an email template file for more complex error notification email content.
How to use:
"errorNotifyTemplate": "errortemplate.txt"
Type: string

type: pdf​

create​

Set option to false, if you want to prevent PDF creation at this time of workflow processing.
How to use:
"create": false
Type: boolean

type: copypdf​

target​

Specify a filename to which the form.pdf is copied and stored as an attached document to the Form Item.
How to use:
"target": "stage2.pdf"
Type: string

type: condition​

condition​

Define the condition to evaluate. Test for equality (==) or inequality (!=), please use uppercase for testing boolean values (True / False). To check if a form field value is null or empty compare the form field to a fake (i.e. not existing) form field.
How to use:
"condition": "{field} != True"
Type: string

type: createexcel​

Creates an excel with data of the form based on an excel template file that contains form field replacers. These replacers are contained in double curly braces, eg: {{field_id}}, in an excel cell.

filename​

Provide a filename for the excel output file.
How to use:
"filename": "form.xlsx"
Type: string

template​

Provide the filename of the excel template that is included in the FormDefinition template files.
How to use:
"template": "excel_template.xlsx"
Type: string

type: email​

templateFile - required​

Provide an email template file for more complex email content. Mustache templating engine is used to set form fields and variables. Read more
How to use:
"templateFile ": "mailtemplate.txt"
Type: string

to - required​

Set the recipient's email address(es). Multiple addresses can be separated by a comma.
How to use:
"to": "{email-address1},{email-address2}"
Type: string

attachDocuments​

Attach the named documents made avaliable by the App feature "Documents" to the email using a regex pattern.
How to use:
"attachDocuments": "^stage2.pdf$, ^uploadedDocument.docx$"
Type: string

attachimage​

Attach an image from the Form Template and make it available for reference inside your mailtemplate.txt.
How to use:
"attachimage": "form-logo.png"
Type: string

attachImages​

Attach all images (photos/sketches etc) contained in the form.
How to use:
"attachImages": true
Type: boolean

attachPDF​

Set the value to true to attach the form.pdf to the email.
How to use:
"attachPDF": true
Type: boolean

attachTemplateFiles​

Attach files from the Form Template to the email.
How to use:
"attachTemplateFiles": ["Example.pdf"]
Type: Array

bcc​

Set additional email address(es) not shown in header.
How to use:
"bcc": "{email-address1},{email-address2}"
Type: string

body​

Provide a short email body message. You can include values of form fields.
How to use:
"body": "A new form {title} has been approved"
Type: string

bodyFile​

Provide an email template file for more complex email content.
How to use:
"bodyFile ": "mailtemplate.txt"
Type: string

cc​

Set additional email address(es).
How to use:
"cc": "{email-address1},{email-address2}"
Type: string

filename​

Rename the form.pdf file attached to the email, note: this does not affect the stored form.pdf.
How to use:
"filename": "attachFile.pdf"
Type: string

from​

Set sender Address.
How to use:
"from": "{email-address1}"
Type: string

subject​

Provide a subject line.
How to use:
"subject": "HybridForms: Form Approved"
Type: string

type: newform​

fields​

Specify the form fields and the values inherited by the new form.
How to use:
"fields": {"name" : "{name_textfield}", "date": "{work_date}",...}
Type: { [key: string]: string }

group​

Specify the group of the new form if the new form should be assigned to a diffenet group.
How to use:
"group": "hf-group"
Type: string

owner​

Specify the owner of the new form if the new form should be assigned to a diffenet editor.
How to use:
"owner": "user@hybridforms.net"
Type: string

stage​

Specify the stage of the new form.
How to use:
"stage": "S3"
Type: string

status​

Specify the status of the new form.
How to use:
"status": "Edit"
Type: string

template​

Specify the template id of the new form if the created form is not of the same type.
How to use:
"template": "bc40e199-e8a1-4a4f-9b53-a5e8f16154c0"
Type: string

title​

The new form inherits the title of the current form.
How to use:
"title": "{Title}"
Type: string

type: request​

clientId​

ClientId for ADFS/Windows AD authentication.
How to use:
"clientId": "exampleId"
Type: string

clientSecret​

ClientSecret for ADFS/Windows AD authentication.
How to use:
"clientSecret": "exampleSecret"
Type: string

fields​

List of fields to set in the form using values from the body returned by the called service.
How to use:
"fields": {"fld1":"result_data_fld1",...}
Type: { [key: string]: string }

headers​

List of additional http headers to set when calling the service.
How to use:
"headers": {"X-Access-Token":"1234",...}
Type: { [key: string]: string }

impersonate​

Set the value to true to call the service authenticated as the user submitting the form.
How to use:
"impersonate": false
Type: boolean

message​

Template for the history entry in case the success condition is not met.
How to use:
"message": "Status code '{result_returnCode}' returned by service. Error: {result_message}"
Type: string

metaData​

MetadataAddress for OpenID authentication configuration.
How to use:
"metaData": "https://adfs.example.com/adfs/.well-known/openid-configuration"
Type: string

password​

Password for ADFS/Windows AD authentication.
How to use:
"password": "examplePassword"
Type: string

requestType​

Define the request method ("POST" or "GET").
How to use:
"requestType": "POST"
Type: string

resourceId​

Set the ADFS/AzureAD identity of the called service for impersonation.
How to use:
"resourceId": "ClientID"
Type: boolean

success​

Conditional expression to verify successful completion. Fields from a Json or XML body returned by the service can be referenced.
How to use:
"success": "{result_returnCode}==0"
Type: string

timeout​

Timeout in seconds for calling the specified service. Default 100 seconds.
How to use:
"timeout": 300
Type: number

url​

Specify the URL to connect to.
How to use:
"url": "....."
Type: string

userName​

Username for ADFS/Windows AD authentication.
How to use:
"userName": "exampleUser"
Type: string

type: xmlrequest​

Send XML formated data to the service.

clientId​

ClientId for ADFS/Windows AD authentication.
How to use:
"clientId": "exampleId"
Type: string

clientSecret​

ClientSecret for ADFS/Windows AD authentication.
How to use:
"clientSecret": "exampleSecret"
Type: string

fields​

List of fields to set in the form using values from the body returned by the called service.
How to use:
"fields": {"fld1":"result_data_fld1",...}
Type: { [key: string]: string }

headers​

List of additional http headers to set when calling the service.
How to use:
"headers": {"X-Access-Token":"1234",...}
Type: { [key: string]: string }

impersonate​

Set the value to true to call the service authenticated as the user submitting the form.
How to use:
"impersonate": false
Type: boolean

message​

Template for the history entry in case the success condition is not met.
How to use:
"message": "Status code '{result_returnCode}' returned by service. Error: {result_message}"
Type: string

metaData​

MetadataAddress for OpenID authentication configuration.
How to use:
"metaData": "https://adfs.example.com/adfs/.well-known/openid-configuration"
Type: string

password​

Password for ADFS/Windows AD authentication.
How to use:
"password": "examplePassword"
Type: string

requestType​

Define the request method ("POST" or "GET").
How to use:
"requestType": "POST"
Type: string

resourceId​

Set the ADFS/AzureAD identity of the called service for impersonation.
How to use:
"resourceId": "ClientID"
Type: boolean

success​

Conditional expression to verify successful completion. Fields from a Json or XML body returned by the service can be referenced.
How to use:
"success": "{result_returnCode}==0"
Type: string

timeout​

Timeout in seconds for calling the specified service. Default 100 seconds.
How to use:
"timeout": 300
Type: number

transformFile​

Provide an XSLT file for transformation of HybridForms XML to POST body.
How to use:
"transformFile": "nameofxsltemplate.xslt"
Type: string

url​

Specify the URL to connect to.
How to use:
"url": "....."
Type: string

userName​

Username for ADFS/Windows AD authentication.
How to use:
"userName": "exampleUser"
Type: string

type: jsonrequest​

Send JSON data to the service.

clientId​

ClientId for ADFS/Windows AD authentication.
How to use:
"clientId": "exampleId"
Type: string

clientSecret​

ClientSecret for ADFS/Windows AD authentication.
How to use:
"clientSecret": "exampleSecret"
Type: string

fields​

List of fields to set in the form using values from the body returned by the called service.
How to use:
"fields": {"fld1":"result_data_fld1",...}
Type: { [key: string]: string }

format​

Specify how complete the information in JSON should be, same as can be specified when requesing forms using the API.
How to use:
"format": "Minimal/Brief/Full/Repeating"
Type: string

headers​

List of additional http headers to set when calling the service.
How to use:
"headers": {"X-Access-Token":"1234",...}
Type: { [key: string]: string }

impersonate​

Set the value to true to call the service authenticated as the user submitting the form.
How to use:
"impersonate": false
Type: boolean

includeCharset​

Set to true to include charset attribute in the content type ("application/json; charset=utf-8").
How to use:
"includeCharset": true
Type: boolean

includeFiles​

Set to true to include attachment binary data in "files" property (as "base64Content").
How to use:
"includeFiles": true
Type: boolean

message​

Template for the history entry in case the success condition is not met.
How to use:
"message": "Status code '{result_returnCode}' returned by service. Error: {result_message}"
Type: string

metaData​

MetadataAddress for OpenID authentication configuration.
How to use:
"metaData": "https://adfs.example.com/adfs/.well-known/openid-configuration"
Type: string

password​

Password for ADFS/Windows AD authentication.
How to use:
"password": "examplePassword"
Type: string

requestType​

Define the request method ("POST" or "GET").
How to use:
"requestType": "POST"
Type: string

resourceId​

Set the ADFS/AzureAD identity of the called service for impersonation.
How to use:
"resourceId": "ClientID"
Type: boolean

success​

Conditional expression to verify successful completion. Fields from a Json or XML body returned by the service can be referenced.
How to use:
"success": "{result_returnCode}==0"
Type: string

timeout​

Timeout in seconds for calling the specified service. Default 100 seconds.
How to use:
"timeout": 300
Type: number

url​

Specify the URL to connect to.
How to use:
"url": "....."
Type: string

userName​

Username for ADFS/Windows AD authentication.
How to use:
"userName": "exampleUser"
Type: string

type: execute​

Call an executable or a script on the server. Special parameter {PDF} refers to the path of a copy of the form.pdf file.

arguments​

Parameters to pass to the called script or program.
How to use:
"arguments": "{templateId} {itemId}"
Type: string

program​

Location on the server of a script to execute.
How to use:
"program": "path_to_script_on_server"
Type: string

type: setowner​

owner​

Change the owner of the Form Item when proceeding to the next stage.
How to use:
"owner": "{field}"
Type: string

type: setcurrentowner​

owner​

Change the owner of the Form Item in the current stage.
How to use:
"owner": "{field}"
Type: string

type: setstatus​

status​

Define the new Form Item status ("New", "Edit","Group", "Approved" or "Archived") when proceeding to the next stage.
How to use:
"status ": "Archived"
Type: string

type: setcurrentstatus​

status​

Define the form status ("New", "Edit","Group", "Approved" or "Archived") in the current stage.
How to use:
"status ": "Archived"
Type: string

type: setgroup​

group​

Define a new group assignment when proceeding to the next stage.
How to use:
"group": "grp_admin"
Type: string

type: setcurrentgroup​

group​

Define a new group assignment in the current stage.
How to use:
"group": "grp_admin"
Type: string

type: setfield​

field​

Define the fieldID of a form field to be changed.
How to use:
"field": "fieldID"
Type: string

value​

Define the new value of the defined form field at stage change. Enter the new value by using the variant string "new value" or by referencing a field value {{another fieldID}} or set the value of RadioBoxes or CheckBoxes using the variant {true}, {false} or {null}
How to use:
"value" : "new value"
Type: string

type: setfeedback​

feedback​

Set a feedback message on the current form.
How to use:
"feedback" : "Feedback message"
Type: string

type: stagechange​

stage​

Define a stage to proceed out of the predefined stage order.
How to use:
"stage": "stage_3"
Type: string

Workflow Data

​

Besides any form field value (i.e addressed by {form field id} ) you can use the following server meta data:

PropertyDescription
AuthorThe name of the user who created the form
AuthorEmailEmail of this user (if any)
AuthorIDThe ID (UPN) of the user who created the form
ClientIdThe ID of the sub system the form belongs to
CreatedCreation date of the form item (datetime in UTC format)
Created_DateCreation date of the form item - dateOnly
Created_HFLocal"Local" creation time of the form item
Created_TimeCreation time of the form item
CultureThe HF.Culture field from the form definition
DisplayVersionThe version of the form at the time of PDF generation/of the workflow action
EditorThe user who last changed the form
EditorEmailEmail of this user (if any)
EditorIDThe ID (UPN) of the user who last changed the form
GroupThe name of the currently assigned group.
ItemIDHF.ItemID field
ModifiedDate of the last modification of the form item (datetime in UTC format)
Modified_DateDate of the last modification of the form item - dateOnly
Modified_TimeOnly the time of the last modification of the form item
Modified_HFLocalThe "local" time of the last modification of the form item
OwnerThe user who owns the form - this must not be the editor!!
OwnerEmailEmail of this user (if any)
OwnerIDThe ID (UPN) of the user who owns the form
ReachoutUrlUrl to Reachout form
ReachoutConfirmUrl to Reachout confirm form
ServerUrlBase url of HybridForms server
StageIDThe id of the current form stage
StageLabelThe label of the current form stage
StatusValue of the HF.Status field
TemplateIDHF.FormID of the form definition
TemplateNameThe name of the form definition
TitleThe form "Title"
VersionThe current version number of the Form Item

Note: You can use all these server meta data to generate a PDF filename except the time values because of the time format - a colon is not allowed!

Form Definition

​

Conditions

​

The visibility of HybridForms elements (e.g. pages, tabs, blocks, fields, etc.) can be defined by a new condition type "stage". The "val" configures the relevant stages.

<form>
    ...
    <li
        data-hf-title="Repair"
        data-hf-condition='{
            "cond": [{
                "type": "stage",
                "id": "stage_2",
                "val": true
            }],
            "else": "readonly"
        }'
    >
        <a href="#repair-block1"></a>
        <a href="#repair-block2"></a>
    </li>

    <li>...</li>
</form>

list-/headerTemplate

​

The stage id and stage label can be used by the list-/headerTemplate as well. Access the information by "data.stage.id" and "data.stage.label".

<form>
    ...
    <span data-hf-bind="textContent: data.stage.id"></span>
    <span data-hf-bind="textContent: data.stage.label"></span>
    ...
</form>

Images in mailtemplate.txt

​

Note

Attached images can be referenced inside your email body by the HTML tag img and the path prefix `cid.

Example
<img src="cid:logo.png" />