Set up action result questionnaires

An action result questionnaire is the set of questions a driver answers when completing a task, such as unloading. The answers become the action result: whether the task was done, why not, remarks, photos and signatures. Answers can also update the order, for example the number of pallets actually loaded or a new delivery date.

How questionnaires work

• Your platform has at most one questionnaire per action type, for example one for loading and one for unloading. To vary the questions within a type, use conditions (see below).
• When a driver completes a task in OpenMove, the questionnaire of its type replaces the standard result screen. See Answer action questionnaires.
• The same questionnaire opens in the shared execution view of a trip, when someone completes a task there in a browser.
• Answers a driver gives on a board computer, for example Transics or Webfleet, are matched to the same questions (see Board computer answers below).
• Without a questionnaire, drivers choose Done, Partly done or Not able to do and type a reason and remarks.

Open the questionnaires

1. Open the side menu (☰, top right) and choose Settings.
2. Click the Environment tab.
3. Open the Action Result Questionnaires section, between Planning and Pricing.

The section shows the Generate with AI button and an editor with the questionnaires as JSON text. When nothing is set up yet, the editor contains {}.

Create or change questionnaires with AI

The quickest way to start is to describe what you need, or to upload the information sheet of your board computer.

1. Click Generate with AI.
2. Optionally, add files under Information sheet or documents (optional): click the paperclip or drag files onto it. PDF, Word, Excel, CSV, images and other common formats are accepted.
3. In Instruction, describe what you want, for example "Add a damage question with a photo to unloading" or "Create the questionnaires from this Transics information sheet".
4. Click Generate. This can take up to a few minutes.
5. Read the summary that appears. Updated: lists the action types that were created or changed; the other action types are left exactly as they were.
6. Check the new questionnaires in the editor below.
7. Click Save at the bottom of the page to keep them.

If you click Generate with an empty instruction and no files, you see Please provide an instruction or upload a document. When there was nothing to change, you see The AI made no changes.

Edit the questionnaires yourself

1. Type or paste in the editor. Use the buttons at the top of the editor to format the text or undo a change.
2. Watch the margin of the editor: a mistake in the JSON, such as a missing comma or quote, is marked on its line. While the text is not valid, Save is disabled.
3. Click Save at the bottom of the page.
4. Test the questionnaire by completing a task of that type on a test trip (see Test a questionnaire below).

The text is an object with one entry per action type. Each entry has enabled (only true questionnaires are used), a list of questions and a list of resultMappings. This example asks whether an unloading went well, asks for a reason when it did not, and collects a signature when it did:

{
  "unload": {
    "enabled": true,
    "questions": [
      {
        "id": "delivered",
        "label": "Were all goods delivered?",
        "type": "select",
        "order": 1,
        "options": [
          { "value": "yes", "label": "Yes", "setsResultStatus": "succeeded" },
          { "value": "partly", "label": "Partly", "setsResultStatus": "partiallySucceeded" },
          { "value": "no", "label": "No", "setsResultStatus": "failed" }
        ]
      },
      {
        "id": "why",
        "label": "What went wrong?",
        "type": "text",
        "order": 2,
        "conditions": [{ "questionId": "delivered", "operator": "notEquals", "value": "yes" }],
        "fieldMapping": { "target": "actionResult", "fieldPath": "reason" }
      },
      {
        "id": "signature",
        "label": "Signature of the receiver",
        "type": "signature",
        "required": false,
        "order": 3,
        "conditions": [{ "questionId": "delivered", "operator": "equals", "value": "yes" }]
      }
    ],
    "resultMappings": []
  }
}

Action types

The key of each entry is the action type it applies to:

Key	Task
load	Loading
unload	Unloading
attachTransportEquipment	Coupling a trailer or container
detachTransportEquipment	Uncoupling a trailer or container
genericAction	General action
refuel, customs, weighing, wait, break	Refuelling, customs, weighing, waiting and breaks

Questions

Setting	What it does
id	A unique name for the question within the questionnaire, such as delivered. Conditions and result mappings refer to it. Do not change it once drivers have answered.
label	The question the driver sees.
type	The kind of answer (see the next table). Without a type, the question is a text question.
required	Whether the driver must answer before completing. A question is required unless you set "required": false.
order	The position in the questionnaire, lowest first.
description, placeholder	Help text under the question and the gray text in an empty field.
options	The choices of a choice question, each with a value (stored) and a label (shown). An option can also set the result (see Set the result), or make another question its follow-up with nextQuestionId.
conditions	When the question is shown (see Show a question only when it applies).
validation	Limits on the answer: minLength and maxLength (characters), min and max (numbers, inclusive) and decimals (digits after the decimal separator).
fieldMapping	Where the answer is written (see Write answers into the order).
externalIds	The codes a board computer uses for this question (see Board computer answers).

Question types

Type	The driver
text	Types free text.
number	Types a number. Both 12,5 and 12.5 are accepted.
select	Picks one option.
multiSelect	Ticks one or more options.
boolean	Uses a yes/no switch. The answer is stored as true or false.
date, datetime	Picks a date, or a date and time.
photo	Takes a photo or picks one from the phone.
signature	Lets someone sign on the screen.
message	Reads an instruction, such as "Take photos of the seal". It needs no answer. Add "messageState": "important" to show it as Attention instead of Info.

Show a question only when it applies

Give a question conditions to show it only in some cases. A question with several conditions is shown only when all of them are met. A hidden question is never required, and its answer is not used.

A condition compares the answer to an earlier question with a value:

Operator	Met when the answer
equals / notEquals	is exactly / is not the value. For yes/no questions, use "true" or "false".
contains	contains the value.
greaterThan / lessThan	is a number above / below the value. The value must be a number.
isEmpty / isNotEmpty	is empty / has been given. These need no value.

A condition can also look at the order instead of an answer. Set "source": "field", a target (action or shipment) and a fieldPath, the same paths as in Write answers into the order. For example, ask for the trailer temperature only when the shipment's first goods line has a license plate:

"conditions": [{ "source": "field", "target": "shipment", "fieldPath": "goods.0.licensePlate", "operator": "isNotEmpty" }]

This is how one questionnaire covers several variants of the same task, such as different departments or customers. When the field cannot be read at all, the question is shown.

For "ask this only after that answer", give the option a nextQuestionId instead. The question it names becomes a follow-up: it is shown, and required, only once that option or another option pointing at it is chosen. Its own conditions still apply.

Set the result

The answers decide the result of the task. Transportial looks in this order and uses the first one that applies:

1. Result mappings. The first entry in resultMappings whose conditions are all met sets its resultStatus and resultReason. Use these for combinations, such as "partly delivered and more than 5 items left".
2. Options. A chosen option with setsResultStatus sets that status, and setsResultReason the reason.
3. Default. Otherwise the result is Done.

"resultMappings": [
  {
    "conditions": [
      { "questionId": "delivered", "operator": "equals", "value": "partly" },
      { "questionId": "itemsLeft", "operator": "greaterThan", "value": "5" }
    ],
    "resultStatus": "failed",
    "resultReason": "Too many items not delivered"
  }
]

Status	Shown as	Effect
succeeded	Done	None.
partiallySucceeded	Partly done	Counts as done.
failed	Not able to do	The shipment needs replanning.
canceled	Canceled	Counts as done.

What a failed task sets in motion is described in Status life cycles.

Write answers into the order

A fieldMapping writes the answer of a question to a field. It has a target, a fieldPath and optionally a strategy and a transform.

Target	Field paths
actionResult	reason and remark of the result. requestedRescheduleAt records a new date the receiver asked for, which starts replanning. Any other name is stored with the result under that name.
action	startTime, endTime, eta, etd, remark, duration (seconds) and externalAttributes.<name>. On a photo question, documents adds the photo to the documents of the task, where planners see it on the action card.
shipment	remark, description, constraints.delivery.startingDateTime, constraints.delivery.endingDateTime and externalAttributes.<name>. Goods: goods.<field> (every goods line), goods.0.<field> (the first line, counting from 0) or goods.0.containedGoods.1.<field> (the second item in the first trailer or container). Goods fields: quantity, name, description, remark, barCode, weight, grossWeight, loadMeters, and for trailers and containers licensePlate, seal and equipmentId.

The strategy decides what happens with the answer:

Strategy	Effect
overwrite (default)	Replaces the field with the answer.
recordDifference	Leaves the field alone. When the answer differs from it, the result records a difference, such as 33 pallets reported where the order says 32. Use this to check the order rather than change it.
appendComment	Adds a line "question: answer" to the remark of the target.

Answers are written as given. To write a date in another format, add "transform": { "type": "dateParse", "format": "dd-MM-yyyy HH:mm" }; "type": "addDuration" turns a number of seconds into that much time from now.

Board computer answers

Drivers with a board computer answer questions on that device. Transportial matches those answers to your questionnaire through externalIds: per system (transics or webfleet) the code the board computer sends. Answers to questions without a match are not applied to the questionnaire.

• Transics. Use the code from the "Info columns" of your information sheet, such as SNR for a seal number. When a question has no code, use its exact description from the sheet. Give options both encodings: the answer text as value and the answer code in their own externalIds.
• Webfleet. Use the name of the order message field.

{
  "id": "seal",
  "label": "Seal number?",
  "type": "text",
  "required": false,
  "externalIds": { "transics": "SNR" },
  "fieldMapping": { "target": "shipment", "fieldPath": "goods.0.seal", "strategy": "recordDifference" }
}

Board computer answers arrive one at a time, so required questions may stay unanswered and an invalid answer is skipped instead of rejecting the rest. The result only changes when an answer sets one.

By default, every answer the driver gave is also shown on the task, including answers to questions you have no question for. To record only matched answers, switch off Record all board computer answers on the board computer integration. See Board computers.

React to differences

When an answer records a difference, or a board computer answer is skipped as invalid, Transportial raises the event After a questionnaire conflict. Choose it as the trigger of a workflow, an alert rule or a message automation, for example to notify the planner or the customer service team. See Workflows and Alert rules.

Test a questionnaire

1. Create a test trip with a task of the action type, and start the trip.
2. On the trip, click the Share execution view icon to copy the link, and open it in a new browser tab.
3. Click Start on the task, then Complete.
4. Answer the questions and check that follow-up questions appear when they should.
5. Click Complete and check the result on the task in the trip. See Read action results.

Troubleshooting

• The questionnaire does not appear. Check that enabled is true, that the key matches the action type of the task, and that you saved the settings.
• A question never appears. Check its conditions: the questionId must be an earlier question, and the value must match the option's value exactly, not its label.
• The driver cannot complete. A question is required unless it has "required": false. Hidden questions are never required.
• The wrong result is set. Result mappings come before options, and the first matching mapping wins. Put the most specific mapping first.
• A field is not updated. Check the fieldPath against the lists above, that the strategy is overwrite, and that the task belongs to a shipment when the target is shipment.