Form Configuration Options

Last edit: Feb 28, 2020

This is an overview of all form configuration options.


To understand this topic, you should be familiar with:

Full Form example and source code

The code below present all possible form configuration options together with the optional form implementation part that comes just after the YAML section. All possible configuration options will be explained in detail in the following section. You can play with the form generated by the example here.
You can also see source code on GitHub.

name: full_form_example
resource: example_model
resource_owner: anyone
return_to: /full-form-example
flash_alert: This is flash alert (fail)
flash_notice: This is flash notice (success)
spam_protection: "" # e.g. { recaptcha_v2: {} } - needs to be configured
          message: Email cannot be empty
        email: true
        virtual: true
- welcome_user
- ping_example_com_on_user_sign_up
callback_actions: >
  {% log "Hello from callback actions" %}
  delay: 1
  priority: low
  max_attempts: 2
  content: |-
    {% log "Hello from async callback actions - I am delayed 1 minute!" %}
  - valid_example_policy
default_payload: |-
    "properties_attributes": {
      "greeting": "Hello from default payload!"
<p>{{ }}</p>

{% form html-class: 'w-50' %}
  <div class="form-group">
    <label for="form_email">Email</label>

      name="{{ }}"
      value="{{ }}"

     <p>{{ form.errors[''] }}</p>

  <button class="btn btn-primary">Save</button>
{% endform %}

The configuration part of the form defines the API endpoint where the server listens to specific requests and invokes all actions defined in the form. The implementation part is what is displayed as HTML to your user. It is optional because sometimes you will only want to configure the server and the request will come from another source like in the example form tutorial: Building a Contact Form with Models. For more information about the implementation part head to the Rendering Form tutorial.

Required form configuration options


The unique identifier of the form. It's how you reference your forms in the include_form tag. This field doesn't depend on the actual Form file name, but it's a good practice that the file name corresponds with the value of the name property.

pos-cli currently does not raise an error when two form configurations have the same name - the last synced form will be displayed.


Either the name of your Model Schema or one of the predefined platformOS classes. For the full list of classes visit our REST API reference.


Optional form configuration options


Array of API Call Notification names that will be executed after the form is successfully submitted.

Example from Creating an API Call Notification:

  - ping_example_com_on_user_sign_up


Accepts the following parameters:

  • content: String, Liquid Template code executed asynchronously. There is no timeout set for processing this code so it is the right place for more time-consuming calculations.
  • delay: Integer, number of minutes added to the moment of form submission before the code defined in content is executed.
  • priority: String, high, default or low, defines priority of execution when executed at the same time with other callbacks.
  • max_attempts: Integer, number of executions of callback in case of an error, default is 1.


  delay: 1
  priority: low
  max_attempts: 2
  content: >
    {% log "Hello from background" %}

The example above prints the "Hello from background" string to the output of pos-cli logs staging.


Array, list of names of Authorization Policies that are protecting the form from unauthorized submission.


String, Liquid Template code that is executed as soon as the form is successfully validated.


Object, whitelist of fields that are allowed to pass to the form object together with the validation rules for each of the defined fields. Every property added to the configuration is accessible in form variable and has the following configuration options:


  • virtual: Virtual fields come in handy when there’s no direct mapping to a model attribute or when you plan on displaying a value without processing.


          virtual: true


JSON formatted String that is merged with user data provided in the form submission.
Head to the Default Payload Tutorial to learn more about it.


Array of Email Notifications names that will be executed after the form is successfully submitted.


String, message that is passed to the context.flash.alert object when the form validation is raised.
Learn more in a separate tutorial about Flash Messages.


String, message that is passed to the context.flash.notice object when the form is valid.
Learn more in a separate tutorial about Flash Messages.


String, defines path of the page rendered after a successful form submission. Example: /welcome


String, defines form configuration user permissions schema.

Available values are:

  • anyone - anyone can modify the object
  • creator - only the user that previously created the object can update/delete the object with that form configuration
  • self - like owner for User resource

The table below shows all possible resource owners for different resources:

Resource Available resource owners
User self, anyone
Model creator, anyone

This is very useful when you want to restrict user permissions to modify only records that were previously created by that user.


Array of short text message notification names that will be executed after the form is successfully submitted.


Object, strategy and configuration for strategy. There are available strategies recaptcha_v2 and recaptcha_v3

Config for recaptcha_v2:


Config for recaptcha_v3:

    action: signup         # required, action for recaptcha V3
    minimum_score: 0.5       # optional, minimum score that we accept for recaptcha V3, default: 0.5

A separate topic explains how to add reCaptcha Spam Protection.


We are always happy to help with any questions you may have.