Datasets

Many forms don’t live in a vacuum: they require communicating with the outside world to help the user enter data. The items of a selection control such as a dropdown list might come from a central database, for instance. Orbeon Forms PE provides a way to do this via HTTP services, database services and actions.

This is all good but Orbeon Forms services and actions so far only allowed you to use the response from a service to set control values and itemsets. This meant that once the action had completed, that was it. You could not, in particular, use the returned values in formulas for form validation or calculations, or refer to a value returned by the service at a later time. One way around that was to store useful values returned from services into hidden controls. While that solution worked well for a few values, it didn’t scale well for larger sets of data.

So we implemented a new feature which we call datasets to help. A dataset is a mutable [1] piece of data stored in the form in XML format. [2] A dataset is identified by a unique name within the form, such as activity-dataset.

You create a dataset using the Actions Editor. There you can chose the “Save to Dataset” response action to save the entire service response to a dataset identified by name.

Actions Editor with the New Save to Dataset Action

Your form can load one or more datasets via services when the form loads. Then you can use data from these datasets in formulas. The form can also load more datasets or update existing datasets at a later time in response to user actions.

Storing data into a dataset only makes sense if you make use of that data at a later point. Orbeon Forms therefore provides a new function, fr:dataset(), which returns the data of a given dataset by name. You can use that function from any formula appearing in the form. For example:

fr:dataset('activity-dataset')/status = 'pending'

Note that for now, a dataset is transient and “lives” only as long as the user stays on the given form page:

• It is not saved alongside the form data in the database.
• It is not passed around when navigating between the “edit” and “view” modes.

Multiple actions calling services can store data into the same dataset, or in separate datasets. The action which last updates a dataset with a given name overwrites the entire content of the dataset.

For more on datasets, see the documentation.

This feature will be available in Orbeon Forms 2017.1. We hope you will like this feature!

---

1. That is, it can change over time.  ↩

2. The internal format is always XML, but it can originate from a call to a JSON service as well.  ↩