Post-fill

Overview

Post-fill allows your server validation response to change the values in a form after a user submits it. When your Messaging web service rejects a submission with a 422 response, it can return a value for any field, along with or instead of an error message. The mobile app writes that value into the field before reopening the form. Returning null clears the field instead.

Post-fill changes how you design forms that handle exceptions. Without post-fill, if you wanted to add a manual override to your server-side validated forms, you had to make the override visible the moment a user opened the form. Users learn quickly that checking it up front avoids a failed submission, which trains exactly the habit the check was meant to prevent. With post-fill, the override stays hidden until your criteria are met, so users only see it when it actually applies. For API-specific guidance, refer to the Messaging API Documentation.

NOTE: Post-fill requires server-side validation on a workflow action. Server Validation is only selectable in App Manager once Workflow Action is checked.

IMPORTANT: Post-fill requires mobile app version 1.64 or later. Earlier versions ignore the value property, so users see only the error messages.

How It Works

Post-fill runs inside the existing two-stage validation transaction. Nothing changes in the request your Messaging web service receives, only in what you send back. The diagram below illustrates the server-side form validation flow.

Values are applied only on a 422. A 200 finalizes the submission, so there is nothing left to fill.

Post-fill has no setup of its own. It is a change to what your Messaging web service returns, so everything it needs is already in place for server-side validation, plus the field codes you intend to write to.

Post-fill and Pre-fill

Pre-fill and post-fill both put a value into a field without the user typing it. The difference is when they happen: pre-fill runs before the user sees the form, and post-fill runs after the user submits it.

A value works the same way whether you pre-fill or post-fill a field. For example, if "3" pre-fills a rating field as three stars, it will also show three stars when post-filled.

The Platform does not validate the format of a post-filled value before sending it to the device. The mobile app interprets the value the same way in both cases, so you only need to learn one set of format rules.

Key Components

When your Messaging web service rejects a submission, add a value to the validation_result entry for each field you want to change. Every entry accepts three properties:

• field_code: The code of the field to act on. This property is required on every entry.

• value: The value to write into the field, or null to clear it. This property is optional.

• error_message: Optional. The message shown to the user on that field. The value cannot be null, so omit the property entirely instead of sending null.

At least one of value and error_message must be present. That gives three valid combinations:

Returning a Value

Returning a value is a four-step process:

1. Build your validation_result array with one entry per field you are responding about.

2. Add value to any entry whose field should change, formatted for that field type.

3. Include error_message on entries where the user needs to see an error.

4. Return the response with HTTP status 422.

{
  "validation_result": [
    {
      "field_code": "SHOW-OVERRIDE",
      "value": "Y"
    },
    {
      "field_code": "TRAILER-NUMBER",
      "value": null,
      "error_message": "Trailer 4471 is not assigned to this load."
    },
    {
      "field_code": "ODOMETER",
      "error_message": "Odometer cannot be lower than the last reading."
    }
  ]
}

Value Formats by Field Type

Most field types expect a string. Multi-choice fields are the exception and expect an array of strings.

IMPORTANT: Option List and Document Type fields match on the option's value, not the label shown to the user. Sending the label does not fill the field.

For multi-choice fields, return an array even when setting a single option, such as { "field_code": "EXCEPTIONS", "value": ["DAMAGED"] }. If some entries match the field's options and others don't, the mobile app fills in the matches and ignores the rest.

For Load Number (populated list), the value must match a load already in the user's list. If the field has Allow Free-Form Text enabled, a non-matching value is not entered in the text box. The mobile app ignores it.

Clearing a Value

Return null when you want the user to enter a value again instead of correcting what they typed. Unlike other post-fill instructions, a cleared field always visibly changes, so it never fails silently.

Clearing a value takes three steps:

1. Set "value": null on the validation_result entry for that field.

2. Add an error_message explaining what to enter instead. Without one, the field empties and the user doesn't know why.

3. Return the response with HTTP status 422.

{
  "field_code": "TRAILER-NUMBER",
  "value": null,
  "error_message": "That trailer is not assigned to this load. Enter the trailer you are pulling."
}

Returning null clears the field regardless of how the value arrived. It clears text the user typed, a value pre-filled from a data reference, and a value you post-filled on an earlier round trip. It also clears fields the user cannot edit, because the Editable attribute governs user input rather than post-fill.

For a Load Number (populated list) field with free-form text enabled, null deselects the list item and empties the free-form box.

Clearing can also hide a section. If a field's value controls a section through visibility_javascript, emptying that field hides the section when the form reopens, just as filling it in shows the section.

NOTE: Clearing a required field means the user cannot submit until they enter something. That is usually the intent. Pair null with an error_message so the user knows what to enter.

When a Value Is Not Applied

If the mobile app can't interpret a value, it ignores the value and the user's existing input stays in the field.

IMPORTANT: The Platform does not validate your value against the field type before sending it to the device. If the mobile app can't use a value, it drops it silently. The user sees no error, and nothing is logged to your error console. A malformed value looks the same as no change at all, so the only sign of a format error is a field that never updates.

The rest of the response is unaffected. One unusable value does not invalidate the other entries in validation_result, and their error_message properties still display.

Use this table when a field does not change as expected:

There is no confirmation signal for an applied value. Do not treat a 422 round trip as evidence that your value landed. If a downstream decision depends on a field holding a specific value, read that field from the next submission rather than assuming.

Testing Post-fill

Work through a complete exception on a device before rolling out. This example uses an Electronic Logging Device (ELD) override; substitute your own condition.

Setup: The form has an ARRIVAL-TIME field that shows when the form is first opened. There is also a hidden SHOW-OVERRIDE text field that is empty by default. A Boolean field named ELD-MALFUNCTION carries visibility_javascript that shows the field only when SHOW-OVERRIDE equals "Y".

1. Log in as a test user and put that user in the state that should fail, which here is Off Duty.

2. Launch the form from the workflow action and submit it.

3. Confirm your Messaging web service receives the form data and returns 422 with the override set.

   {
     "validation_result": [
       {
         "field_code": "SHOW-OVERRIDE",
         "value": "Y"
       },
       {
         "field_code": "ARRIVAL-TIME",
         "error_message": "You are not On Duty. Confirm below if your ELD is malfunctioning."
       }
     ]
   }

4. On the device, confirm the form reopens, the ELD-MALFUNCTION checkbox is visible, and the error appears on the arrival time field.

5. Select the checkbox and resubmit the form.

6. Confirm your Messaging web service sees ELD-MALFUNCTION as true and returns 200. The form locks and the record is delivered.

7. In the delivered form_data, confirm SHOW-OVERRIDE is "Y" and ELD-MALFUNCTION is true.

TIP: Repeat steps 1 through 4 for every field type you post-fill. Because a malformed value is ignored silently, watching the field on the device is the only reliable check.

NOTE: Post-filled values are part of the submitted record. Control fields you set for visibility logic are delivered along with everything else, so expect them in the payload.

Resources

API

• Messaging

• Forms

Guides

• Server Validation

• Workflow

• Forms

• Data References

App Manager Help Center

• Forms

• Form Field Types