Free Trial

Chapter 4 - Projects

4B. Metadata in Forms

Metadata in Forms - Introduction

Customizable Forms can be used when you require user input at any point in your workflow or as a stand-alone request. Forms can be used for many different reasons, and the ability to customize them for any business scenario is extremely powerful. Data input into a Form can be converted into metadata fields and stored inside the Aproove database. This stored Metadata can then be used for many purposes. For example, it could determine the configuration of the workflow, or to display the information in the project dashboard/s. Maybe you may want a "project kick-off" Form where the requester of the project has to fill in information about the project requirements and upload a creative brief. The Form can have an unlimited number of fields, some of which you can mark as mandatory. Perhaps the Form could drive a generic workflow and use the gathered information to specify the stakeholders of the project and what workflow to use at runtime. You can even have a second (or any number) of Forms further in the workflow to determine the direction of the workflow or additional stakeholders that should be involved in the project.

Simply put, the information input into a customizable Form can be used to drive your workflows or display additional information in the user interface.

Metadata in Forms - Basic Setup

In the previous section, we prepared metadata types and keys needed for creating a Form. A Form is just an assembly of this metadata. This section exposes settings that allow you to configure the user experience related to those Forms and what metadata fields are used in them.

Once Form templates are built, they are available for use in the Task definition as a specific step. A Task can contain several steps, including Forms, file uploads, document annotation, file downloads, or any combination of these.

Creating a new Form

To create a Form, enter the name of the template and click "Add".

Forms Add

Modifying a Form

Forms Add3-1

  • Color: Click the color picker to select a different background color. 
  • Description: describe the purpose of this form; only visible within the admin tool.
  • Enabled: Activates the form where in use. Uncheck to disable the form.
  • Edit labels: Click to edit language localization of labels (Preview, Title, and Info)
  • Preview: Click to preview the form (opens in your default web browser)

Adding fields to a Form

Select the Form from the list to open the editing window. To add a metadata key as a metadata form field, select it from the list of available metadata keys and click "Add selected".

Note: Only metadata keys with a defined Type are displayed. Some metadata keys may not have a Type due to the way they were created (ie., using the API or Hot folders). You will need to edit these keys and assign them a Type in order to add them to the Form.

Forms Add2-2

Editing Form fields settings

Each Form field is editable and depending on the metadata type, you may have different options.

Forms Add4-1

All metadata types will have the same Form attributes, except for the contact and contact group field types, which have an additional search option. These options will affect the appearance of the Forms in the user interface.

Forms Add5-1 Forms Add6

Field position

  • Order - Determines the order of the field in the Form at runtime.
  • Tab order - Sets the order in which fields are selected with the tab key.
  • Width & Height - Size in pixels that the visual component will have in the final rendered Form at runtime.
    • Note: some components require a minimum height or width to be displayed correctly. Default values are indicated in the edit window.

Field options

  • Use all the available row width - If checked, the component will use the entire line width dynamically no matter what value is set in width.
  • Alone on the row - The component will honor the width setting, but will be alone on this row.
  • Mandatory - This marks the field as required to continue (a red dot will be displayed on the form, next to the field to indicate that this is a mandatory field).
    • Note: that this setting is not available for boolean type fields as leaving a checkbox unchecked is considered an acceptable option.
  • Read-Only - The field will not be editable, it will be used for only displaying information that cannot be changed.
  • Hidden - The field will be hidden if checked. Useful for dynamically hiding or showing fields based on rules in the form (coming soon).
  • Note form Use project value if existing - if the Note tag form does not contain a value for a metadata key(s), it will inherit the value (if one exists) from the existing project metadata

Type options

This tab is empty for all metadata key types except Contact and Group, and Multiple Contact and Group. For those, the Contact search (regexp) setting is available for limiting end-user search capabilities. The regex used here will be used to gather the raw information on which the end-user will be able to search.

Note: a similar attribute already exists on the Metadata type definition. This one is seen as a "late" restriction field while the other is seen as an "early" or pre-restriction field. It is up to the integrator to use the best combination of restrictions based on the project requirements.

Forms Add8

Form Preview

To preview and test a Form, click "Preview". The Form will load in a new tab of your default web browser.

Forms Add9-1

Assigning a Form to a Task

To assign a Form to a Task, select the Task from Workflows → Tasks. In the Features settings, tick the Metadata form checkbox and select the Form from the dropdown list.

Note: if this Task is used in an existing workflow you will need to "re-save" the Task in the workflow step for the change to take effect.

Forms Add10-1

Metadata in Forms - Advanced Setup

Additional Form field definitions

Image preview component

This component will offer an easy way to display images in the Form. The metadata value stored in it should be the URL, then can be accessed to the image file. If a metadata key of image type is used in a project, you can also hardcode a specific value to it in order to display a hardcoded image. Of course, this value can be dynamic and caught from another component of the form like a search type field that returned a URL value that will be bound to this Image type field.

Search type component

The search type is not a data type in the strict sense of it. It is a complex type that handle a specific Form behavior to enable interactive data queries to a third-party system. This component is a classical search field which will capture data input from the user and trigger a search query with the content. The results of the search query can be displayed in 2 different ways:

  • As text results
  • As image results

These results will show directly in the Search component as a dropdown list of results. When a result is selected by the user, the related object data are parsed by the component and each attribute returned can be bound to a specific Aproove metadata field (usually in the same form for displaying the selected result).

The "Request" tab


1 This tab is meant to define the query to be executed by the search component. This query is built from static information (base URL for example) and dynamic data (Aproove internal Tags or Metadata tags). These GET data are mandatory to initiate the call. Any kind of GET parameter can be added to the request string, either static or dynamic. 
2 As an option, the query can also submit some POST data (body) which will be formatted in JSON.The definition of the POST data is a Key value array of parameters. Again, both Key or values can be static or dynamic.
3 If the server behind the URL is requiring an HTTP authentication, you have the option to specify a user and a password.


The "Results binding" tab

1 Once a user selects a result from the search results, a parsing and a specific data binding is possible. The parsing of the results assumes that results are sent in JSON format. The array of results that will flow back are parsed by specifying the key to use for parsing the objects.

Depending whether you want to display results as Text or images, you will use either the text result key or the image result key parameters. Please note that using an image as a result will require you to have the height and width of the image to be sent back from the server who received the query.

2 Once a specific result is selected, the other attributes of the selected item can be bound to Metadata keys in order to collect them or display them in the current form.

The "Results" filtering tab

When a query is executed, it is sometime not easy to filter them at server level simply because the service called is not design to do so. This tab is there for enabling late filtering of the results. Please note that the query tab can be completely omitted and an existing metadata can be used for parsing results. In this specific case, the the project level JSON object will require some filtering and this tab makes therefore a lot of sense.


Array of object type 

An array of object is a complex type (versus simple types like text, numbers, etc.) used to store lines of vectors (a vector is a list of multiple column objects). A typical use case for arrays of objects is using them to host the content of a Grid component (like a XLS sheet for example). The goal is to have a dynamic type of data able to grow in regards to the need of the user (adding more lines if required at run time by the user) and being able to use the content of the array type in further automation (actions), or forms (using a grid component or another components extracting part of the array).

Backend server executed actions

When used to trigger a back-end action, it will simply execute the specified action in the server. Actions can be anything available as actions in Aproove. An example of such action can be: send a mail when user hits this button.
A more useful and interactive action would be a HTTP request call executed from the server to a third-party system. That kind of call can be used to query a third-party system (like a SQL database, a PIM, ERP or a DAM for example). For example, querying a PIM to extract all metadata fields from a product ID and instantiate all the metadata keys in Aproove as new variables. Once the action is fully executed, a push event is sent to the front end to refresh the content of the Form as the action may have changed the metadata content displayed on the front end.

We'll use such an action to execute some "searches" on a third-party system and get the results from it through metadata encapsulated in a JSON object. This will help to browse a third-party system interactively from Aproove and get immediate query results displayed.

Front end HTTP calls (from the user browser)

When used to trigger HTTP call from the front end, the purpose is completely different. It is meant to execute things from the front end which will usually only affect things happening in the end user interface. A simple use case is to download a file from the front end directly. So, behind the button, a URL for downloading a file is present in the value of the metadata Key attached to the Button.


Lorem ipsum dolor sit amet, consectetur adipiscing elit. Duis ac lorem vel lectus finibus placerat. Vivamus nec elementum orci, a sagittis libero. Fusce egestas augue ante, eu luctus magna convallis eu. Donec eget nibh ut orci lobortis imperdiet. Donec pellentesque quam a nulla eleifend tempus. Quisque facilisis iaculis nibh in elementum. Mauris porta cursus ante in dictum.

Orci varius natoque penatibus et magnis dis parturient montes, nascetur ridiculus mus. Quisque dolor magna, fringilla congue tempor eget, tempus ut ipsum. Maecenas feugiat erat at velit tempor commodo. Donec iaculis pharetra ligula eu pellentesque. Suspendisse venenatis nulla leo, eu porttitor leo aliquet eu. Praesent luctus mi a imperdiet egestas. Phasellus bibendum tincidunt ultricies. Sed vestibulum eros turpis, ac venenatis orci lacinia ac. Aliquam semper scelerisque libero, nec lobortis mi tristique quis. Quisque eget blandit purus.

Praesent ultricies felis ac molestie dignissim. Sed eu ornare ante, id pellentesque lectus. Nullam dapibus dapibus nisl, et volutpat justo mattis vitae. Sed placerat laoreet nisi. Proin mollis lorem felis, sed consequat felis cursus eget. Proin aliquam augue porta diam dictum, a porta ipsum consectetur. Sed eget cursus erat. Phasellus id imperdiet tortor, eget semper purus. Donec sagittis elit in rutrum eleifend. Etiam laoreet, dui eleifend fringilla cursus, magna eros dignissim dui, in lacinia arcu erat nec enim. Donec in est id eros imperdiet dictum nec in sapien. Fusce pretium ligula magna, sed pulvinar tellus dignissim in.

Maecenas sodales interdum augue eu convallis. Maecenas molestie auctor velit. Ut id venenatis lacus, eget vestibulum magna. Fusce in sollicitudin nisi. Ut placerat sapien non quam facilisis, ac aliquam felis pharetra. Donec sapien dui, interdum rutrum risus sit amet, pellentesque euismod augue. Ut fermentum erat nibh, nec suscipit lorem dapibus ut. Sed nec volutpat ligula.

In magna ligula, convallis id consectetur in, rutrum vel sapien. Aliquam id fermentum nibh. Cras dictum sapien sit amet molestie suscipit. Vestibulum vitae leo ac mi placerat vestibulum. Donec posuere, est in fermentum ultricies, est purus varius lacus, euismod convallis ex mauris eget lectus. Proin eget nunc vitae urna auctor euismod. Morbi sed ex vel ligula tempor vestibulum. Maecenas bibendum varius augue a rutrum. Pellentesque id felis ut felis rutrum viverra. Etiam bibendum suscipit dictum. Sed leo lacus, porta aliquet quam in, mattis feugiat arcu.