Forms can be used to give users the possibility to interact with your processes and applications and to create, edit and delete data.

How does it work?

In order to define a form in PIPEFORCE, you need at least a JSON schema and the form configuration.

Open

The JSON schema (also called the “object schema”) defines the structure of a data set and “tells” the form which fields to display and a user can fill-out. Learn more about JSON Schema in this chapter: Schema & Objects.

The input data is used in case an existing data set needs to be edited. The form is pre-filled with these data, so the use can make changes and save again.

After a form was submitted, the output is automatically saved into the property store. So you do not need to care about where the data is stored.

After this, an event is send, depending on what the form did with an object/property:

• property.created = If a new object was created by submitting the form.

• property.changed = If an existing object has been changed by submitting the form.

• property.deleted = If an existing object has been deleted by submitting the form.

Any pipeline can then listen to such events using the command event.listen and do additional logic afterwards using the submitted data. For example sending notification emails, doing data integration or alike. Such a pipeline could look like this:

The glue of all this is the form configuration which defines, how the form should use the schema and display the fields. Additionally any information about layouting a form’s fields goes into the form configuration.

How to handle the form output

By default, after a submit, the data of a form is automatically stored into the property store under a new property having this key path:

Whereas <APP> is the name of your app. <NAME> is the name of the object, the schema of the form belongs to and <UUID> is a unique identifier for the data set, created automatically for each new entry.

In the person example above, after a form submit with new data, this data could be stored in a new property with key path which looks like this:

The output of the form - which is the value of this instance property - could look like this:

You can easily querying for existing instances using the command property.list. For example using the pi tool:

In case you have more than one object type in your app and you want to list all instances of all objects of your app, you could use this list filter:

How to load and edit input data in a form

After a form has been submitted, for each submit a new instance property is created in the instance path of an object, for example:

In case you want to edit such an instance first you need to load it into the form using the request parameter input, when calling the form:

Now form renders initial values from input, but will still save into newglobal/app/myApp/object/person/v1/instance/{somenewrandomuid}

To save to the same record, additional form output parameter needs to be added to overwrite default behaviour.

This all is automatically done for you in case you call a form using a list.

The form configuration

The last step to create and configure a new form is to create a form configuration file. This is a configuration file in JSON format which defines important attributes of a form like its title or layout information.

Here’s an example how such a file could look like:

The title defines the title of the form to be displayed in the web ui, for example.

The description is optional and describes the intention of the form.

The schema defines a command which is called to retrieve the JSON schema for this form.

The output defines the path in the property store where to store the the data. The part %23%7Bvars.property.uuid%7D is the url encoded version of #{vars.property.uuid} which is a PE to return the uuid of the property to form its path.

By default the form configuration is stored inside the form folder as JSON file:

After you have created a JSON Schema file and a form configuration and pushed them to the property store using pi push, the form is listed in the forms section and is ready to be used.

For all schema properties there is a web input control rendered - filed. By default all fields are displayed using the default - single column layout, every field in its own row.

To reach custom layout, fields behaviour, file uploads, custom buttons and more, additional layout attribute of form configuration file needs to be used. Layout uses different approach to define which fields to show. Only field referenced in this structure are rendered. For details see following sections.

Change orientation of form fields

You can change this default by configuring orientation of the layout in the form configuration.

See this section for more details: Form - Orientation

Change appearance of form fields

Beside the orientation (vertical, horizontal) of form fields, also the appearance (color, border, icons, aso) can be changed inside the layout section.

See this section for more details: Form - Look & Feel

Custom buttons

Replacements for default Submit button can be defined by render attribute of boolean field in layout section.

See this section for more details:Form - Buttons

File upload

In layout section it is also possible to configure that set of schema properties defines form upload.

See this section for more details: Form - Upload