Orbeon Forms
  • Getting started
  • Installation
    • Logging
    • Configuration banner
    • Docker
    • Azure
    • Tomcat
    • WildFly
    • WebSphere
    • WebLogic
    • GlassFish
    • Caches
    • Replication
    • Upgrading
  • Configuration
    • Properties
      • General
        • HTTP client
      • Form Runner
        • Detail page
          • Attachments
          • Email
          • PDF
          • Table of contents
        • Persistence
        • Summary page
      • Form Builder
      • XForms
    • Advanced
      • Workflows
      • Session management
      • State handling
      • Client-side error handling
      • Clustering and High Availability
      • Configuring a Form Runner eXist database
      • Creating a production WAR
      • Environments
      • JavaScript and CSS assets
      • Limiter filter
      • Run modes
      • Security
        • Content-Security-Policy header
      • SAP Hybris Module
      • XForms logging
    • Troubleshooting
      • Troubleshooting with the orbeon.log
      • Memory and threads
      • Relational database logging
      • Misc
  • Form Builder
    • Form settings
      • Time window
    • Form editor
      • Form area
      • Toolbox
      • Buttons bar
      • Control settings
      • Dependent fields and sections
      • Validation
      • Choices editor
      • Publishing
      • Cut, copy and paste
      • Section and grid settings
      • Section settings
      • Grid settings
      • Quick control search
      • Repeat settings
      • Repeated grids
      • Undo and redo
      • Keyboard shortcuts
    • Formulas
      • Examples of formulas
      • Formulas inspector
      • Formulas console
    • Summary page
    • Form localization
    • Advanced
      • Edit source
      • Services and actions
        • HTTP services
        • Database services
        • Simple Actions
        • Action Syntax
        • Action Syntax examples
        • Synchronizing repeated content
      • Testing a form in web mode
      • Testing PDF production
      • Testing offline functionality
      • Email settings
      • Field-level encryption
      • Messages
      • Section templates
      • Template syntax
      • XML Schemas support
      • Extensibility
        • Extension API
        • Integration
        • Toolbox component metadata
  • Form Runner
    • Overview
      • Terminology
    • Pages
      • Landing page
      • Published Forms page
      • Forms Admin page
      • Summary page
    • Components
      • Alert dialog
      • Attachment
      • Autocomplete
      • Captcha
      • Character counter
      • Checkbox input
      • Currency
      • Date
      • Dropdown date
      • Static and dynamic dropdown
      • Error summary
      • Grid
      • Handwritten signature
      • Hidden field
      • Image
      • Image annotation
      • Image attachment
      • Number
      • Open selection
      • Repeater
      • Formatted Text / Rich Text Editor
      • Section
      • Single-selection tree
      • Source code editor
      • Time
      • US phone
      • US state
      • Video
      • Video attachment
      • Wizard
      • XForms inspector
      • Yes/No answer
    • Features
      • Automatic calculations dependencies
      • Datasets
      • Excel and XML import
      • Excel and XML export
      • Summary page Excel Export
      • Form definitions and form data Zip Export
      • Purging historical data
      • Lease
      • Localization
      • Supported languages
      • Mobile support
      • Multitenancy
      • Form Runner navigation bar
      • PDF production
        • Automatic PDF
        • Automatic PDF header and footer configuration
        • PDF templates
      • Responsive design
      • Revision history
      • S3 storage
      • Simple data migration
      • TIFF production
      • Versioning
      • Wizard view
      • Workflow stage
    • Persistence
      • Using a relational database
      • Relational database schema
      • Purging old data using SQL
      • Auditing
      • Autosave
      • Database support
      • Flat view
    • Linking and embedding
      • Linking
      • Java Embedding API
      • JavaScript Embedding API
      • Liferay full portlet
      • Liferay proxy portlet
      • Securing Form Runner access
      • Form Runner offline embedding API
      • Angular component
      • React component
    • Access control and permissions
      • Users
      • Login & Logout
      • Deployed forms
      • Form fields
      • Editing forms
      • Owner and group member
      • Organizations
      • Scenarios
      • Token-based permissions
    • Styling
      • CSS
      • Grids CSS
      • Automatic PDF styling and CSS
    • APIs
      • Authentication of server-side service APIs
      • Persistence API
        • CRUD API
        • Search API
        • List form data attachments API
        • Form Metadata API
        • Lease API
        • Reindexing API
        • Caching
        • Versioning
        • Revision History API
        • Zip Export API
        • Custom persistence providers
      • Other APIs
        • Connection context API
        • Duplicate form data API
        • File scan API
        • Form Runner JavaScript API
        • Generate XML Schema API
        • PDF API
        • Publish form definition API
        • Run form in the background API
      • Data formats
        • Form data
        • Date and time
        • Form definition
    • Architecture and integration
      • Architecture
      • Access form data
      • Integration
    • Advanced
      • Buttons and processes
        • Simple process syntax
        • Core actions
        • Form Runner actions
          • Save action
          • Send action
          • Email action
        • XForms actions
        • Predefined buttons, processes and dialogs
        • Summary page buttons and processes
      • Custom dialogs/model logic
      • Services
      • Singleton form
      • Monitoring HTTP requests
  • XForms
    • Core
      • Attribute Value Templates (AVTs)
      • Binds
      • Validation
      • Variables
      • Keyboard focus
      • XForms JavaScript API
      • Error handling
        • Detailed behavior
      • Model-Bind variables
      • XForms 2.0 support
    • Events
      • Standard support
      • UI refresh events
      • Keyboard events
      • Extension events
      • Extension context information
      • Other event extensions
    • Actions
      • Repeat, insert and delete
      • Scripting actions
      • Extensions
    • Controls
      • Label, hint, help
      • Input
      • Output
      • Text area
      • Button
      • Upload
      • Dialog
    • Submission
      • Standard support
      • JSON support
      • Asynchronous submissions
      • Caching extension
      • Other submission extensions
    • XPath
      • Type annotations
      • Expression analysis
      • Tips
      • Compatibility
      • Standard functions
      • Maps and arrays Functions
      • Extension functions
        • Core functions
        • Utility functions
        • Model functions
        • Controls functions
        • XML functions
        • JSON functions
        • HTTP functions
        • Form Runner functions
        • Other functions
        • Deprecated functions
    • XBL components
      • FAQ
      • Guide
        • XBL Tutorial
        • Bindings
        • XForms models
        • Including content
        • Event handling
        • Conventions
        • Map XBL example
        • Learning from existing components
      • Advanced topics
        • XBL Modes
        • JavaScript companion classes
        • XBL library
        • Extensions
        • Attachment controls
    • XForms tutorial
      • Introduction
      • Installation
      • The Hello application
      • The Bookcast application
        • The basic app
        • Database access
        • Polishing the app
        • Adding a feed
    • Using XForms from Java apps
  • XML Platform
    • Page Flow Controller
      • Basics
      • XML submission
      • Navigating between pages
      • Paths and matchers
      • Other configuration elements
      • Typical combinations of page model and page view
      • Examples
      • Authorizing pages and services
    • Processors
      • URL generator
      • Request generator
      • PDF to image converter
    • Resources
      • Resource managers
      • Setting up an external resources directory
    • Other
      • Binary and text documents
  • FAQ
    • Licensing
    • PE and Dev Support
    • Form Builder and Form Runner
    • Resources and support
    • Other technical questions
  • Contributors
    • Automated tests
    • Building Orbeon Forms
    • Localizing Orbeon Forms
    • Validation functions
    • Contributor License Agreement
  • Release notes
    • Orbeon Forms 2022.1.9
    • Orbeon Forms 2024.1.1
    • Orbeon Forms 2023.1.7
    • Orbeon Forms 2024.1
    • Orbeon Forms 2023.1.6
    • Orbeon Forms 2023.1.5
    • Orbeon Forms 2021.1.11
    • Orbeon Forms 2022.1.8
    • Orbeon Forms 2023.1.4
    • Orbeon Forms 2023.1.3
    • Orbeon Forms 2023.1.2
    • Orbeon Forms 2022.1.7
    • Orbeon Forms 2023.1.1
    • Orbeon Forms 2023.1
    • Orbeon Forms 2022.1.6
    • Orbeon Forms 2021.1.10
    • Orbeon Forms 2022.1.5
    • Orbeon Forms 2021.1.9
    • Orbeon Forms 2022.1.4
    • Orbeon Forms 2022.1.3
    • Orbeon Forms 2021.1.8
    • Orbeon Forms 2022.1.2
    • Orbeon Forms 2022.1.1
    • Orbeon Forms 2022.1
    • Orbeon Forms 2021.1.7
    • Orbeon Forms 2021.1.6
    • Orbeon Forms 2021.1.5
    • Orbeon Forms 2021.1.4
    • Orbeon Forms 2021.1.3
    • Orbeon Forms 2021.1.2
    • Orbeon Forms 2021.1.1
    • Orbeon Forms 2021.1
    • Orbeon Forms 2020.1.6
    • Orbeon Forms 2019.2.4
    • Orbeon Forms 2019.1.2
    • Orbeon Forms 2018.2.5
    • Orbeon Forms 2018.1.4
    • Orbeon Forms 2020.1.5
    • Orbeon Forms 2020.1.4
    • Orbeon Forms 2020.1.3
    • Orbeon Forms 2020.1.2
    • Orbeon Forms 2019.2.3
    • Orbeon Forms 2020.1.1
    • Orbeon Forms 2020.1
    • Orbeon Forms 2019.2.2
    • Orbeon Forms 2019.2.1
    • Orbeon Forms 2019.1.1
    • Orbeon Forms 2019.2
    • Orbeon Forms 2019.1
    • Orbeon Forms 2018.2.4
  • Release history
  • Use cases
  • Product roadmap
  • Index of features
Powered by GitBook
On this page
  • Introduction
  • Basic action configuration
  • Creating or updating an action
  • Reordering actions
  • With Orbeon Forms 2017.1 or newer
  • Handling the service request
  • User interface
  • How a value is provided to the service
  • Passing a control value
  • Passing a value from a formula
  • Handling the service response
  • User interface
  • Setting the value of a control
  • Setting the choices of a selection control
  • Storing the response to a dataset
  • Namespace handling
  • See also
  1. Form Builder
  2. Advanced
  3. Services and actions

Simple Actions

PreviousDatabase servicesNextAction Syntax

Last updated 7 months ago

Introduction

The Form Builder Actions Editor is an feature and allows you to implement simple actions in your form. The basic philosophy goes as follows:

  1. React to an event occurring on the form, such as the form being loaded or a user action.

  2. Call an HTTP or database service:

    • passing in parameters from the form,

    • receiving parameters back from the service.

  3. Use the returned parameters to update the form

Actions are tightly coupled with services. In the future, support might be added for actions which do not require services.

Basic action configuration

Creating or updating an action

You create a new action or update an existing action in the "Advanced" tab of the toolbox. This opens the Actions Editor.

Reordering actions

[SINCE Orbeon Forms 2018.2]

You can reorder actions by drag and drop in the toolbox. Sometimes, the specific order of actions is important, or you might just want to organize them in a way that makes sense for your form.

With Orbeon Forms 2017.1 or newer

[SINCE Orbeon Forms 2017.1]

This is the meaning of the fields of the dialog:

  • Action Name

    • This is the name of the action, as seen by Form Builder.

    • Must start with a letter, and may not contain spaces.

  • Run condition

    • Always: Run the action independently from the form mode.

    • In "new" mode only: Run the action only in creation mode, that is when the user creates new data, as opposed to editing, viewing, emailing, or generating a PDF.

  • Run action when

    • Specifies a phrase built of the following parts:

      • "the control"

        • label / name of the control

          • "changes its value"

          • or "appears or changes its value"

          • or "is activated" (a button is activated or the "Enter" key is pressed in a text line)

      • or "the form loads"

        • "after the controls are ready"

          • This is the default.

          • The action runs when controls are "live", which means you can set their values and list of choices.

        • "after the data is ready"

          • The action runs when the data is ready:

            • It has been loaded from the database if needed.

            • Its initial values and calculations are up to date.

          • You cannot set control values and list of choices as a result.

          • You can store datasets as a result.

        • "before the data's initial values are calculated"

          • The action runs before the data is ready.

          • You cannot set control values and list of choices as a result.

          • You can store datasets as a result.

  • Service to Call.

    • The service to call as once the action is triggered.

Like for services, once your action is defined, the Save buttons saves it to the form. You can come back to it and modify it later by clicking on the Edit icon next to the action name. You can also delete the action using the Remove button.

Handling the service request

User interface

Each row instructs the action to take a value and pass it to the service, and you can add as many such rows as needed using the "+" button, and remove existing entries with the dropdown menu.

How a value is provided to the service

  • With HTTP services doing a POST:

    • You provide a formula, which must point to an element or attribute node of the request body defined in the HTTP service under "XML Request Body".

  • With HTTP services doing a GET or DELETE:

    • [SINCE Orbeon Forms 2022.1] The dropdown under "Destination" lists the URL parameter names you have defined in the HTTP Service Editor, allowing you to select the parameter you want to set.

    • [UNTIL Orbeon Forms 2021.1] The HTTP Service Editor implicitly creates an XML document representing these parameters, as in the example below. The Actions Editor doesn't yet support specifying URL parameters directly by name; instead, you need to enter a formula under "Set Service Request Values", like //userId or //userName.

      <params>
          <userId>1</userId>
          <userName>test</userName>
      </params>
  • With Database services:

    • To set the first query parameter, use the value "1" (without the quotes), the second, "2", etc.

Passing a control value

Select "Control Value" in the first dropdown.

Parameters:

  • Control:

    • Specifies the control whose value must be used.

    • A single "closest" control will be selected:

      • If the control is not within a repeated grid or section, then that unique control is updated.

      • Otherwise, the control which is the closest by following repetitions and repeat indexes is chosen.

  • Destination XPath Expression:

    • The expression is evaluated in the context of root element of the XML request data to send to the service.

    • The expression must point to an element or attribute node of the request body. If multiple nodes are returned, only the first one is considered.

Passing a value from a formula

[SINCE Orbeon Forms 2021.1]

Select "Formula" in the first dropdown.

Parameters:

  • Formula:

    • The given formula is evaluated and converted to a string.

  • Destination XPath Expression:

    • The expression is evaluated in the context of root element of the XML request data to send to the service.

    • The expression must point to an element or attribute node of the request body. If multiple nodes are returned, only the first one is considered.

Handling the service response

User interface

[SINCE Orbeon Forms 2017.1]

You access the response in the Service Response Actions tab. This allows adding, removing, and moving response actions:

Setting the value of a control

As a result of running an action, you can set a form control's value from data returned by a service using:

  • [SINCE Orbeon Forms 2017.1] the "Set Control Value" action

  • [UNTIL Orbeon Forms 2016.3] the "Set Response Control Values" section

Parameters:

  • Destination Control:

    • Specifies the control whose value must be set.

    • A single "closest" control will be selected:

      • If the destination control is not within a repeated grid or section, then that unique control is updated.

      • Otherwise, the control which is the closest by following repetitions and repeat indexes is chosen.

  • Source XPath Expression:

    • The expression is evaluated in the context of root element of the XML data returned by the service.

    • The expression can point to an element or attribute node of the response body, but can also be a more complex expression. Its result is converted to a string.

Setting the choices of a selection control

Basics

As a result of running an action, you can set a selection control's set of items (AKA "itemset") using:

  • [SINCE Orbeon Forms 2017.1] the "Set Control Choices" action

  • [UNTIL Orbeon Forms 2016.3] the "Set response Selection Control Items" section

Selection controls include dropdown menus, checkboxes, and more.

  • Destination Selection Control.

    • Specifies the selection control whose items must be set. Only selection controls appear in this list.

    • Depending on the relative position of the source of the action and the target selection controls, one or more "closest" controls can be selected (see the detailed explanation of the behavior below).

  • Choices XPath expression.

    • The XPath expression must point to a set of element or attribute nodes of the response body returned by the service.

    • For each node returned, an item is created.

  • Label XPath expression. The XPath expression must return the text of the label for an item. It is relative to the current item node.

  • Value XPath expression. The XPath expression must return the text of the value for an item. It is relative to the current item node.

Adjustment of control values

[SINCE Orbeon Forms 4.3]

Each selection control's selected value(s) are updated to be in range following the new itemset:

  • For single-selection controls: if the item value currently stored in the instance data is not part of the returned set of items, the value is cleared.

  • For multiple-selection controls: any of the space-separated values currently stored in the instance data that are not part of the returned set of item values are removed.

Behavior starting with Orbeon Forms 2016.1

In the presence of repeated grids or sections, the destination selection control can resolve to zero, one or more concrete controls.

The way this works is that the "closest" controls are searched. This means:

  • If the destination selection control is not within a repeated grid or section, then the single destination control is updated.

  • If the source of the action is within the same repeated iteration as the destination selection control, then that single destination control is updated. Occurrences of the selection control on other repeat repetitions are not updated.

  • If the source of the action is at a higher level compared to the destination selection control, then all repetitions of the selection control are updated, and subsequent new repetitions added will also use the new itemset.

Behavior up to Orbeon Forms 4.10 included

All the previously available items of the selection control(s) identified are replaced with the items specified. In other words, the itemset for the given control is global. This is the case even in the presence of repeated grids or sections.

Internationalization

[SINCE Orbeon Forms 4.7]

Your service should return localized labels for all the languages supported by your form. For instance, if your form is available in English and French, a service you use to populate a dropdown with a list of countries might return:

<response>
    <row>
        <value>us</value>
        <lang>en</lang>
        <label>United States</label>
    </row>
    <row>
        <value>us</value>
        <lang>fr</lang>
        <label>États-Unis</label>
    </row>
    <row>
        <value>ch</value>
        <lang>en</lang>
        <label>Switzerland</label>
    </row>
    <row>
        <value>ch</value>
        <lang>fr</lang>
        <label>Suisse</label>
    </row>
</response>

After the service is called, the items, label, and value XPath expressions you wrote when defining the action are executed once per language supported by the form, and for each execution the $fr-lang variable is set to current language. So in the case of our hypothetical service returning a list of countries, you will define the items as /response/row[lang = $fr-lang], the value simply as value, and label as label.

While in theory this allows you to have the values depend on the language, to avoid unexpected behavior when users switch languages or different users look at the same data using a different language, you should make sure that values are the same for all languages, and only the labels differ between languages.

Storing the response to a dataset

[SINCE Orbeon Forms 2017.1]

  • use the "Save to Dataset" action

  • enter a dataset name

Each dataset name identifies a unique dataset for the form. Depending on the use case, dataset names can be reused or be unique.

A dataset name must:

  • start with a letter or _

  • continue with letters, digits, ., - or _ (if the name has more than one character)

NOTE: Section templates keep their own local datasets, separate from the main form.

Namespace handling

At this point, you can't declare custom namespace mappings in the Actions Editor. So say you have a response looking like this:

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
    <soap:Body>
        <my:items xmlns:my="http://example.org/my">
            <my:item>
                <my:label>Cat</my:label>
                <my:value>cat</my:value>
            </my:item>
            <my:item>
                <my:label>Dog</my:label>
                <my:value>dog</my:value>
            </my:item>
            <my:item>
                <my:label>Bird</my:label>
                <my:value>bird</my:value>
            </my:item>
        </my:items>
    </soap:Body>
</soap:Envelope>

or, using the default namespace mechanism:

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
    <soap:Body>
        <items xmlns="http://example.org/my">
            <item>
                <label>Cat</label>
                <value>cat</value>
            </item>
            <item>
                <label>Dog</label>
                <value>dog</value>
            </item>
            <item>
                <label>Bird</label>
                <value>bird</value>
            </item>
        </items>
    </soap:Body>
</soap:Envelope>

In both these cases, <my:item> (or <item>) and nested elements are in the http://example.org/my namespace. This means that your XPath expression must match elements in a namespace and that, in theory, you need a custom namespace mapping in form builder. Since this is not supported yet, you can work around the issue by using XPath expressions with wildcards:

  • Items: /soap:Envelope/soap:Body/*:items/*:item

  • Label: *:label

  • Value: *:value

You can even use shorter variations if element names are use consistently, for example:

  • Items: //*:item

  • Label: *:label

  • Value: *:value

These expressions with wildcards ignore namespace information completely, so you have to be careful if your XML document contains elements with the same name but in different namespaces.

See also

When formula evaluates to true: [SINCE Orbeon Forms 2021.1] Allows you to enter your own condition using XPath, which, if it evaluates to false, will prevent the service from running (see ).

The HTTP Service Editor when using the GET and DELETE HTTP methods.

As a result of running an action, you can store the entire set of data returned by the service into a :

You access data from a dataset using the function.

For more on datasets, see .

Blog post:

Orbeon Forms PE
video
dataset
Datasets
Making sense of Form Runner Actions
Services and actions overview
HTTP services
Database services
Synchronizing repeated content
allows you to define URL parameters
Actions Editor General Settings
Actions Editor Service Request Actions
Action request formula
Actions Editor Service Response Actions
fr:dataset()