Forms

The primary purpose of this service is to provide forms.

To see the Forms menu entry on the Portal, the forms=view permission is required.

For a summary of permission names and uses related to this service, please refer to this section.

Note

If you have the forms=* permission, you will have access to all the functions mentioned below.

List and view forms

To list and display all forms, the forms=read permission is required.

If your permission has values such as: forms=read('Form 1', 'Form 2'), you will only see the listed forms.

You can view a form by clicking on the magnifier icon in the ‘Actions’ column.

On the different tabs you can view (based on your current locale), and without translation interpolation:

• the preview of the final form
• the schema definition
• the look and feel
• the default data
• the internationalization

Edit a form

To create, update, rename, duplicate, export or import forms, the forms=edit permission is required.

To delete forms, the forms=delete permission is required.

Double-click on a row of the table display or click on the pen icon to edit a form.

Type

Determine the type of form management

JSON

JSON to use the form generator based on the JSON definition

Schema

Warning

For JSON forms only

The Schema correspond to the data definition manage by the form. It’s normalized, according to the official specifications.

By default, the schema is added to the JSON.

{
  "$schema": "http://json-schema.org/draft-07/schema"
}

Here are some useful links about React Json Schema Form:

• examples
• documentation

Look & Feel

Warning

For JSON forms only

The Look & Feel correspond to how the data are going to be displayed. By default, React Json Schema Form is able to generate a display.

Here are some useful links about React Json Schema Form:

• examples
• documentation

Custom: Comments timeline

Platform 6 provides a custom way to display an array of comments.

The comment schema object definition should be

{
  "comments": {
    "type": "array",
    "items": {
      "type": "object",
      "properties": {
        "date": {
          "type": "string"
        },
        "user": {
          "type": "string"
        },
        "comment": {
          "type": "string"
        }
      }
    }
  }
}

The Look & Feel definition for the comments object should be

{
  "comments": {
    "ui:widget": "timeline"
  }
}

The display will correspond to the image below

Default data

Warning

For JSON forms only

The Default data are the data used by default on the form. Like all the others properties they can be override on the before render script.

Internationalization

Warning

For JSON forms only

The internationalization is used to have localized text inside the form and even inside the data.

To use the injection of localized text inside the Schema, Look & Feel, or Default data, use the ${fee.foo} syntax in one of the previous fields.

The internationalization will be as below

{
  "fee": {
    "foo": "bar"
  }
}

Buttons

The internationalization of the button is for now managed by using the prefix _button

{
  "_button": {
    "id": "label"
  }
}

By default, if no translation is found, the button label will be the id capitalized.

JAVASCRIPT

JAVASCRIPT to use the custom form with an embedded JavaScript

Buttons

The permission forms=display is required to access the following endpoints. You can also restrict access to specific forms (i.e. forms=display("form1", "form2"))

You can define other arguments in the uri to be passed to the script through the pipeline.

Notice

The URI must start with p6cmb://. The primary target for form calls is the script service but any p6 service can be called via this mechanism.

Variables will be provided to the script throw the pipeline:

• locale: the locale of the connected user
• type: the type of form

The next variables will be only provided if the form is displayed from a transaction or a workflow task

• viewName: the name of the current view
• platform6.request.dataPartition: the dataPartition of the current view
• platform6.request.dataType: the dataType of the current view
• platform6.request.ids.X: the id of the selected item in the view (where X is 0 indexed number)

Properties

Notice

For JSON only

You can dynamically add some properties to the buttons using the Buttons properties section.

The convention for the property key naming is <id>.<key>.

The properties could be overridden by a script (cf next section for JSON).

The following keys are supported:

• force: to allow the user using a button even if the form data are not valid. (ie: for cancel and close buttons)
• icon: the fontawesome icon to be displayed
• type: the type of button (ie: primary, danger, default)

Before rendering

The form can be configured with a before render handler. It is the uri of the target destination of a message through the Common Message Bus.

For example, you can define a script as target: p6cmb://scripts?platform6.request.action=execute&id=BeforeFormRender

Variables will be provided to the script throw the pipeline:

For JSON only:

• jsonSchema: the JSON Schema (for the current locale ; EN locale use as fallback)
• uiSchema: the UI Schema (for the current locale ; EN locale use as fallback)
• defaultData: the default form data (for the current locale ; EN locale use as fallback)
• translations: the translations (for the current locale ; EN locale use as fallback)

For JAVASCRIPT only:

• javascript: the javascript bundle
• wrapperVersion: the wrapper version

Notice

The wrapper version 1.1.6 is for old React 15 with Amalto components custom forms. The wrapper version 2.0.1 is for new React 17 / Antd custom forms.

In response, the script can write into the pipeline the following entries:

• form.properties: the javascript properties. Should be an association map of key / value.

For JSON only:

• form.jsonSchema: the data schema
• form.uiSchema: the ui schema
• form.formData: the form default data
• form.buttons.\<ButtonKey>.\<key>: set the property \<Key> to the button with the Key \<ButtonKey>. Multiple properties can be set (see examples).

For JAVASCRIPT only:

• form.javascript: the javascript bundle
• form.wrapperVersion: the wrapper version (required if not set on the form item)
• form.dependencies: the javascript dependencies. Should be an array of CDN links

Notice

If the output pipeline entries are missing then the default configuration of the form will be used

Script example

JSON

p6.pipeline.put("form.jsonSchema", "")
p6.pipeline.put("form.uiSchema", "")
p6.pipeline.put("form.formData", "")
p6.pipeline.put("form.buttons.cancel.icon", "fa-cancel") 
p6.pipeline.put("form.buttons.cancel.force", "true")
p6.pipeline.put("form.properties.width", "500")

_JAVASCRIPT _

p6.pipeline.put("form.javascript", "")
p6.pipeline.put("form.wrapperVersion", "2.0.1")
p6.pipeline.put("form.dependencies", "[\"https://cdn.url/depencency/one\"]")
p6.pipeline.put("form.properties.fee", "foo")
p6.pipeline.put("form.properties.bar", "true")

Using the transaction data

import groovy.json.*;
import io.platform6.core.api.datapartition.DataPartitionType;

def xmlSlurper = new XmlSlurper()
p6.transaction.getPKsUsingPipelineRequest().each { pk ->
    def item = p6.transaction.get(pk)
    def transactionInfo = xmlSlurper.parseText(item)
    def amount = transactionInfo.KeyValue.find{it.Key == 'Total Amount'}.Value.text()
    p6.pipeline.put("form.properties.amount", amount)
}

On click

The form can be configured with multiple on click render handler based on an ID. It is the uri of the target destination of a message through the Common Message Bus.

Note

These handlers will be used to define forms buttons.

Variables will be provided to the script throw the pipeline:

• locale: the locale of the connected user
• action: the action ID used
• formData: the form data (as a JSON String)

For example, you can define a script as target: p6cmb://scripts?platform6.request.action=execute&id=OnFormClick

In response, the service can write into the pipeline the following entries:

• ui.action: the action to be returned to the UI:

  • POPUP_MESSAGE: Close the current form and display a simple message popup containing locale specific text

  • FORM_MESSAGE: Display the given message on the form using locale specific text

  • FORM_MODEL_UPDATE: Provides an update to the current form data model.

  • FORM_CLOSE: Close the current form

  • REFRESH_CURRENT_VIEW: Close the current form and force the refresh of the current page view of transactions or workflow tasks

  • NEW_FORM: Close the current form and create a new named form

  • OPEN_JOBS: Close the current form and open the jobs panel so the user can see job progress and download generated payloads

  • INDICATOR: Return an execution indicator

Notice

Only the script service is capable of reading and writing to/from the pipeline. Other services must read/write the Platform 6 Common Message directly to adhere to this implied Request/Response contract. If the call succeeds a success action will be returned. Otherwise, a failure will be returned, and a warning is displayed in the log of Platform 6.

The following action requires additional parameters:

POPUP_MESSAGE

• popup.type: the type of the popup (allowed values are: ERROR, INFO, WARNING, SUCCESS)
• popup.title: the title of the popup
• popup.message: the message of the popup

FORM_MESSAGE

• message.type: the type of the popup (allowed values are: ERROR, INFO, WARNING, SUCCESS)
• message.message: the message of the popup

FORM_MODEL_UPDATE

• form.data: the string serialization of the form data (Should be a valid JSON)

NEW_FORM

• form.id: the id of the form to be displayed

The following action accepts optional parameters:

INDICATOR

• indicator.success: is the indicator on success (true by default)
• indicator.message: the indicator message

Script example

p6.pipeline.put("ui.action", "POPUP_MESSAGE")
p6.pipeline.put("popup.type", "INFO")
p6.pipeline.put("popup.title", p6.i18n.getText([EN: "Payment", FR: "Paiement"]))
p6.pipeline.put("popup.message", "Message to be displayed")

import groovy.json.*;
import io.platform6.core.api.datapartition.DataPartitionType;

def action = p6.pipeline.get('action')

if(action == 'cancel') {
    p6.pipeline.put("ui.action", "FORM_CLOSE");
} else if(action == 'submit') {
    def slurper = new JsonSlurper()
    def formData = slurper.parseText( p6.pipeline.get('formData') )
    def amount = formData.amount
    def notifications = []

    p6.pipeline.put("ui.action", "POPUP_MESSAGE");
    p6.pipeline.put("popup.type", "INFO");
    p6.pipeline.put("popup.title", "Information")

    def xmlSlurper = new XmlSlurper()
    p6.transaction.getPKsUsingPipelineRequest().each { pk ->
        def item = p6.transaction.get(pk)
        def transactionInfo = xmlSlurper.parseText(item)
        transactionInfo.KeyValue.find{it.Key == 'Total Amount'}.Value = amount
        p6.transaction.put(groovy.xml.XmlUtil.serialize( transactionInfo ), pk)
        notifications << "Amount of the transaction ${pk} updated to ${amount}"
    }
    p6.pipeline.put("popup.message", notifications.join("<br/>"))

} else if(action == 'update') {
    p6.pipeline.put("ui.action", "FORM_MODEL_UPDATE");

    def xmlSlurper = new XmlSlurper()
    p6.transaction.getPKsUsingPipelineRequest().each { pk ->
        def item = p6.transaction.get(pk)
        def transactionInfo = xmlSlurper.parseText(item)
        def amount = transactionInfo.KeyValue.find{it.Key == 'Total Amount'}.Value.text()
        p6.pipeline.put("form.data", "{\"amount\":${amount ? amount : "null"}}");
    }
} else if(action == 'debug') {
    p6.pipeline.put("ui.action", "FORM_MODEL_UPDATE");
    p6.pipeline.put("form.data", p6.pipeline.get('formData'));
}

Form Properties

You can dynamically add some properties to the form.

The properties could be overridden by a script using p6.pipeline.put("form.properties.<key>", "<value>").

The following keys are supported:

• width: the width of the form window