Vizlib Input Form Guides - Payload Schema Editor

The Payload Schema Editor feature enables you to transform flat form data into complex, nested JSON structures required by external APIs.

When sending data from Input Form, the default behavior creates a flat payload structure. However, many APIs (such as Jira, ServiceNow, or custom REST endpoints) require specific nested JSON structures. The Payload Schema Editor bridges this gap by allowing you to map form field values to a custom JSON schema using a tag-based mapping system.

This editor provides a visual interface where you can define your target JSON structure and insert field tags that will be replaced with actual form values during submission. This transformation capability ensures compatibility with various API requirements while maintaining the simplicity of form design. The Payload Schema Editor is available for both server and serverless deployments.

Accessing Payload Schema Editor

Depending on your deployment, follow one of the procedures.

Server Deployment

To access Payload Schema Editor in the server deployment, follow these steps:

1. Navigate to Vizlib Input Form Property Panel > Writeback Settings > Destination > Pick Destination.

2. Select the Vizlib Server destination. The Server Settings section appears.

3. In Server Settings > Writeback Destination, select a REST JSON destination. The Schema section appears.

4. In the Schema section, enable the Use custom schema option. The Payload Schema Editor button becomes available.

5. Click the Payload Schema Editor button. The Payload Schema Editor opens.

Result: You can now configure your custom schema in the Payload Schema Editor.

Serverless Deployment

To access Payload Schema Editor in the serverless deployment, follow these steps:

1. Navigate to Vizlib Input Form Property Panel > Writeback Settings > Destination > Pick Destination.

2. Select the REST destination. The REST Settings section appears.

3. In the REST Settings section, define following properties:

   • URL

   • Methods - you can select POST, PUT, or PATCH method. The Payload Schema Editor is not available for the GET method.

   • Payload - select the JSON option.

     If you’ve configured REST Settings as above, the software displays the Schema section.

4. In the Schema section, enable the Use custom schema button. The Payload Schema Editor button becomes available.

5. Click the Payload Schema Editor button. The Payload Schema Editor opens.

Result: You can now configure your custom schema in the Payload Schema Editor.

Mapping Form Fields to JSON Properties

Before you start mapping form fields to JSON properties:

• Enter your target JSON structure into the editor window.

• Verify that JSON validation indicator shows no errors. The editor displays your JSON structure with syntax highlighting and validation status.

If there are no errors, follow these steps:

1. Identify each location in your JSON where form data should appear.

2. Replace the hardcoded values with field tags using the exact field names from your form.

3. For string values, place the tag where the string should appear.

   Copy

   "text": "VZL_TAG[Name] left a VZL_TAG[Rating] star review for your property"

4. For nested properties, maintain the structure while inserting tags at any level: "accessory":

   Copy

    {
   "type": "image",
   "image_url": "VZL_TAG[HotelImage]",
   "alt_text": "Haunted hotel image"
   }
   

5. Click Save.

Result: Your JSON structure now contains mapped field tags that will be replaced with actual values during form submission. Tags appear in green when successfully mapped to existing form fields, or orange for unmatched fields (you can still save the schema with orange tags).

Example:

Figure 1:  Sample form with the custom payload structure configured.

Custom payload schema configured for the form.

Adding System Tags

In the payload, you can add system tags such as timestamp or user (when audit columns are enabled). To do so, add these tags at desired locations:

"submittedAt": "VZL_TAG[TIMESTAMP]"

"submittedBy": "VZL_TAG[USER]"

This way, the system-generated values will be automatically inserted at submission time.

Field Type Mapping Rules

The Payload Schema Editor handles different field types according to specific rules to ensure proper data formatting. For more information, refer to Field types handling in Payload Schema Editor.

Figure 2:  Field types handling in Payload Schema Editor.

Special Tags

Beyond form field tags, the Payload Schema Editor supports system-generated tags for metadata:

• Timestamp tags allow you to insert the current date and time when the form is submitted. This is particularly useful for tracking submission times without requiring users to manually enter dates.

• User tags become available when audit columns are enabled in your configuration. These tags automatically populate with the current user's information, providing built-in audit trail capabilities.