Displaying address custom fields on work orders

Overview

The Information section of a work order displays the work order's description. Because a workflow can write that description, you can use a workflow to show values from the service address, such as an address custom field, directly on the work order where dispatchers and technicians will see them.

In this article, we'll be covering where address custom field values live in workflow data, how to fetch them with a gaiia GraphQL node, and how to add them to the Information section, whether your workflow creates the work order or updates one that already exists.

The fields displayed in the Service Target area of a work order are fixed and cannot be configured. Use the Information section to display additional details.

Understanding where the data comes from

Before editing your workflow, keep the following in mind:

1. The Information section is the work order's description. In the Create Work Order and Update Work Order nodes, this is the description input. It accepts HTML, so you can use tags like <p> and <strong> to format it.
2. Address custom fields are not part of the Get Account node's output. The Get Account node returns the account's address lines, city, and postal code, but not the custom fields attached to that address. To read them, use a gaiia GraphQL node, as described below.
3. Dropdown fields store an option ID, not the label. A text or number field returns its value directly. A dropdown field returns the ID of the selected option, which must be matched against the field's options to get the label you see in gaiia. The code below handles both cases.
4. The description input replaces the whole description. It does not add to it. Whatever the node writes becomes the full contents of the Information section.
5. Only one workflow should write a work order's description. If two workflows write to the same work order's description, whichever finishes last overwrites the other. If a workflow already writes to your work orders' Information section, add the steps below to that workflow rather than creating a new one.

Before you begin

Editing a workflow requires the workflow edit permission. See Workflow Permissions.

Make your changes in a draft so the live version of the workflow keeps running until you are ready. See Working with Workflow Drafts.

1. Note the exact name of the address custom field you want to display, as it appears on the address.
2. Open your workflow in the Workflow Builder.
3. Locate the node that writes the work order's description. This is usually a Create Work Order or Update Work Order node.
4. Note where the account ID comes from in your workflow. To check, hover over the work order node, open its ellipsis menu and click View data details. See Viewing a Node's Data Shape in the Workflow Builder.

A. Fetching the address custom field

Add a gaiia GraphQL node that reads the account's address custom fields, then use an output mapper to keep only the value you need.

1. Hover over the node that runs just before your work order node and click the + icon.
2. Select the gaiia GraphQL node and name it Get Address Custom Fields. Its slug becomes get-address-custom-fields, which the code below uses.

   If you choose another name, replace get-address-custom-fields with your node's slug in every snippet of this article.

3. In the Inputs tab, paste the following query.

   query GetAddressCustomFields($accountId: GlobalID!) {
     account(id: $accountId) {
       physicalAddress {
         geoAddress {
           customFields {
             data
             definition {
               name
               type
               options {
                 id
                 option
               }
             }
           }
         }
       }
     }
   }

4. Set the variables input to Typescript and return the account ID your workflow already has.

   ({ state }) => ({
     accountId: state.objectId
   })

   Replace state.objectId to match how your workflow starts:

   Your workflow starts from	Account ID
   A manual trigger on an account	state.objectId
   A Get Account node earlier in the workflow	state.steps['get-account'].output.account.id
   Any other trigger	The same value your work order node already uses for the account. Check it with View data details.

5. Open the Configure tab and paste the following into the Output mapper. Replace Your field name with the name of your address custom field. Capitalization does not matter.

   ({ output, utils }) => {
     const FIELD_NAME = 'Your field name';
     const fields = output.response?.account?.physicalAddress?.geoAddress?.customFields ?? [];
     const field = fields.find(
       (f) => f.definition.name.toLowerCase() === FIELD_NAME.toLowerCase()
     );
   
     if (!field || field.data === null || field.data === undefined) {
       return { value: '' };
     }
   
     if (field.definition.type === 'DROPDOWN') {
       const selected = field.definition.options.find(
         (o) => utils.parseGlobalId(o.id).id === field.data
       );
       return { value: selected?.option ?? '' };
     }
   
     return { value: String(field.data) };
   }

The field's value is now available to later nodes as state.steps['get-address-custom-fields'].output.value. It is an empty string when the address has no value for that field.

B. Adding the value to the Information section

How you add the value depends on what your work order node does today. In the snippets below, replace Your field name in the label with the text you want to display before the value.

• Use this tab if the description input of your Create Work Order or Update Work Order node is already a Typescript function.

  1. Select the work order node and open its description input.
  2. Find the line that returns the description. For example:

     return description;

  3. Replace it with the following, keeping the name of the variable your function already returns.

     const value = state.steps['get-address-custom-fields'].output.value;
     return value
       ? `${description}<p><strong>Your field name:</strong> ${value}</p>`
       : description;

• Use this tab if your Create Work Order node uses plain text, or no description at all.

  1. Select the Create Work Order node.
  2. In the Inputs tab, set the description input to Typescript.
  3. Paste the following, replacing the first paragraph with the text your work orders already use, or with an empty string.

     ({ state }) => {
       const value = state.steps['get-address-custom-fields'].output.value;
       const description = '<p>Your existing work order information.</p>';
     
       return value
         ? `${description}<p><strong>Your field name:</strong> ${value}</p>`
         : description;
     }

• Use this tab if your workflow adds the value to a work order that already has information you want to keep.

  The description input replaces the entire contents of the Information section. Follow these steps to keep the existing text.

  1. Return to the Get Address Custom Fields node and replace its query with the following, which also reads the work order's current description.

     query GetAddressCustomFields($accountId: GlobalID!, $workOrderId: GlobalID!) {
       account(id: $accountId) {
         physicalAddress {
           geoAddress {
             customFields {
               data
               definition {
                 name
                 type
                 options {
                   id
                   option
                 }
               }
             }
           }
         }
       }
       workOrders(first: 1, filter: { id: { equals: $workOrderId } }) {
         nodes {
           description
         }
       }
     }

  2. Add workOrderId to the variables function, using the work order ID your workflow already passes to the Update Work Order node.

     ({ state }) => ({
       accountId: state.objectId,
       workOrderId: state.input.workOrderId
     })

  3. Replace the output mapper with the following, which returns the current description alongside the value.

     ({ output, utils }) => {
       const FIELD_NAME = 'Your field name';
       const currentDescription = output.response?.workOrders?.nodes?.[0]?.description ?? '';
       const fields = output.response?.account?.physicalAddress?.geoAddress?.customFields ?? [];
       const field = fields.find(
         (f) => f.definition.name.toLowerCase() === FIELD_NAME.toLowerCase()
       );
     
       if (!field || field.data === null || field.data === undefined) {
         return { value: '', currentDescription };
       }
     
       if (field.definition.type === 'DROPDOWN') {
         const selected = field.definition.options.find(
           (o) => utils.parseGlobalId(o.id).id === field.data
         );
         return { value: selected?.option ?? '', currentDescription };
       }
     
       return { value: String(field.data), currentDescription };
     }

  4. Select the Update Work Order node, set the description input to Typescript, and paste the following.

     ({ state }) => {
       const { value, currentDescription } = state.steps['get-address-custom-fields'].output;
       const label = 'Your field name:';
     
       if (!value || currentDescription.includes(label)) {
         return currentDescription;
       }
       return `${currentDescription}<p><strong>${label}</strong> ${value}</p>`;
     }

     The includes check stops the line from being added a second time if the workflow runs again on the same work order.

C. Testing and publishing

Testing a draft runs it against production data. Test on an account and work order you can safely modify.

1. Click Save draft.
2. Click Test and run the workflow on an account whose address has a value in your custom field.
3. Open the execution from the Execution History panel and select the Get Address Custom Fields node. Confirm that value holds the expected text.
4. Open the work order and confirm the value appears in the Information section.
5. Click Publish.

Troubleshooting

Scroll right to view the whole table on smaller screens.

Related articles

• gaiia Nodes
• Understanding Node Input Types
• Using Output Mappers
• Using utils in Workflow Functions