Intro

This tutorial is about

How to create a form in PIPEFORCE.

This tutorial is relevant for

Low-Code Developers who want to learn how to create and display web forms as a fundamental part of an application to accomplish several critical objectives like: Data collection, data review and data validation.

The final form will look similar to this:

Prerequisites

You need to have a developer account in a PIPEFORCE customer or trial instance.

PIPEFORCE instance should have version 9.5 or higher.

If you don’t have an account yet, just request it here: https://pipeforce.io/jetzt-testen/.

It is recommended to go through the Tutorial 01: Basic Concepts before, to get a better understanding of the PIPEFORCE basics.

Step 1: Create Form Schema

In this step you will create a Form Schema (= define the fields of a form)

In order to create such a Form Schema, follow these instructions

1. Login to portal with a valid developer account.

2. Navigate to LOW CODE → Properties.

3. Click the plus + icon at the top.

4. Select App and create a new app with name: io.pipeforce.tutorial-03-forms.

5. Select this app and click again the plus + icon.

6. Now select Form Schema and create it inside this app with name: person.
   

   

7. The new schema was created and pre-filled with an example person schema.

8. Later, you can edit this form schema and remove, change or add data fields to your form.

9. For this tutorial, do not change anything and leave it as it is. 

Step 2: Create Form Config

In this step we gonna create the Form Config and define the layout and configs parameters of a form

In order to create a simple Form Config, follow now these steps:

1. Go to LOW CODE -> Properties.

2. Select your app io.pipeforce.tutorial-03-forms in the tree.

3. Click the plus + icon.

4. Select Form Config.

5. Create a new Form Config with name: person

6. In the property tree, select your app and click on the plus icon + to create a new property inside.

7. Give a name to the Form Config then click Create.

8. A new Form Config was created for you with a pre-configured title and configuration.

9. Leave this Form Config as it is for now.

10. Since we did not specify any layout information here, the default layout will be used: All fields defined in the Form Schema will be displayed in vertical format.

This is how the Form Config JSON will look like:

{
  "id": "person",
  "title": "person",
  "public": false,
  "description": "",
  "schema": "$uri:property:global/app/io.pipeforce.tutorial-03-forms/schema/person",
  "output": "$uri:property:global/app/io.pipeforce.tutorial-03-forms/data/person/"
}

• id = The unique id of this form. Can be any string.

• title = The title to display on this form.

• description = The description to display for this form.

• public = Whether this form should be reachable without login.

• schema = The path to the Form Schema to be used for this form. The prefix $uri:property: defines that the schema can be found in the property store.

• output = The path to the location where to write the data of the submitted form as JSON. The prefix $uri:property: defines that the result will be written to the property store at this location.

Step 3: Execute the Form

After the Form Schema and the Form Config have been created, you can open your form.

To do so follow these steps:

1. Navigate to APPS -> Installed Apps.

2. Click on the app io.pipeforce.tutorial-03-forms.

3. Click on person.

4. Now you should see the form with the example fields like this:

Submit the form

1. Add valid values in any of the fields.

2. Click on SUBMIT.

Noteworthy

After you clicked on SUBMIT, the form data will be validated and then send to the server as JSON. This JSON will then be stored to your app's data folder: io.pipeforce.tutorial-03-forms/data/...

Any new submit will create a new entry in the data folder with a random uuid.

The reason why this works this way is because in the Form Config, the output path was configured to this location, like this:

"output": "$uri:property:global/app/io.pipeforce.tutorial-03-forms/data/person/"

Note: Since this path ends with a /, a new entry is created with a random uuid every time you write to this URI location.

Step 4: Handle the Form Submit

In this step you will learn how to handle a Form Submit at server side and add logic to be executed after submit.

Follow these steps in order to trigger a pipeline after the form was submitted:

This pipeline should then send an email.

1. Go to AUTOMATION -> Properties.

2. Select your app io.pipeforce.tutorial-03-forms.

3. Click the plus + icon.

4. Click Pipeline and create a new pipeline

5. Give the pipeline a name and then click Create.

6. Copy and paste this YAML script to the pipeline editor and overwrite any existing content:

pipeline:
  - event.listen:
      eventKey: property.created
      filter: ${body.target.path.contains('global/app/io.pipeforce.tutorial-03-forms/data/')}
  
  - mail.send:
      to: name@email.tld
      subject: "Form was submitted"
      message: |
        The form was submitted:
        ${body.target}

As you can see, this pipeline listens to the property.created event. Since the form submit writes to the location global/app/io.pipeforce.tutorial-03-forms/data/ (as configured by the output parameter) you can listen to this write event and execute your business logics. Which is sending a simple email in this example.

7. Change the email address name@email.tld to your own address.

8. Save the pipeline. After save, the pipeline will be automatically registered as a listener to the property.created event.

9. Execute the form again.

10. You should now receive a new email on any form submit.

 Step 5: Customize Form Layout

In this step you will learn how to change the default form layout

Follow these instructions in order to change the default layout of your form:

1. Go to AUTOMATION -> Properties.

2. Open the Form Config form/person inside your app io.pipeforce.tutorial-03-forms.

3. Replace the content of the Form Config by the JSON listed below, and then click SAVE

{
  "id": "person",
  "title": "Add person",
  "public": false,
  "description": "",
  "schema": "$uri:property:global/app/io.pipeforce.tutorial-03-forms/schema/person",
  "output": "$uri:property:global/app/io.pipeforce.tutorial-03-forms/data/person/",
  
  "layout":{
    "orientation":"vertical",
    "items":[
      {
        "orientation":"horizontal",
        "title": "Name",
        "border": true,
        "items":[
          {
            "field":"firstName"
          },
          {
            "field":"lastName"
          }]
      },
      {
        "field":"age"
      },
      {
        "field":"gender"
      },
      {
        "field":"birthDate"
      }
    ]
  }
}

As you can see in the Form Config, the layout part was added which defines a different orientation of the fields.

4. Navigate to APPS -> Installed Apps and click your app io.pipeforce.tutorial-03-forms.

5. Now you should see that the “person” tile has changed to “Add person”. Click it.

6. Here you can see the changed layout: first Name and last Name fields are now in the same line (horizontal) and all other fields are in separate line (vertical):