Airspacelink.com

Survey123 Work Order Integration

1. Introduction

This guide outlines the process for integrating Survey123, an external data collection tool, with the AirHub® Portal. The goal is to enable a seamless two-way flow of work order data: allowing work orders to be created in the Portal from Survey123 and reflecting Portal status updates back into the original Survey123 feature layer.

2. Overview of the Integration Flow

The integration involves a two-way communication setup:

  • Inbound Flow (Survey123 to AirHub® Portal - Work Order Creation):

    1. A user submits a Survey123 form.

    2. This triggers an event (e.g., a webhook associated with the Survey123 form submission) to send data.

    3. A Power Automate Flow (Inbound) receives this data, transforms the Survey123 format into Airspace Link's standard work order schema.

    4. The Power Automate flow calls the Airspace Link API to create a new work order in the AirHub® Portal.

    5. The work order appears in the AirHub® Portal, mapped to the correct organization.

  • Outbound Flow (AirHub® Portal to Survey123 - Status Updates):

    1. An update is made to a work order within the AirHub® Portal (e.g., status).

    2. This triggers an internal AirHub® Portal process that calls a Power Automate Flow (Outbound).

    3. This Power Automate Flow transforms Airspace Link's update schema into Survey123's expected format.

    4. The Power Automate flow uses the "Update a Record in a Feature Layer" functionality to publish the update back to the original Survey123 record's feature layer.

    5. The original Survey123 record is updated.

3. Pre-Integration Steps & Information Gathering (From Customer)

Before configuring the integration, essential information and access are required from the customer:

3.1. Understand the Customer's Survey123 Usage

  • Familiarize yourself with how they intend to use Survey123 for work order intake.

  • Understand the design of their proposed Survey123 form and the fields they plan to use.

3.2. Gather Key Information & Access from the Customer

  • Customer's Survey123 Form URL: The URL of the specific Survey123 form that will be used for work order creation.

  • Customer's ArcGIS Online Credentials (Optional): If Airspace Link will be setting up the Power Automate flows on their behalf, these credentials may be needed (decision pending on who creates/manages the PAFs).

  • Schema & Field Mapping:

    • Ideal Scenario: The customer uses a Survey123 form based on a schema template provided by Airspace Link. This simplifies the field mapping in Power Automate significantly.

    • Customization: If they customize their fields, field mapping details (exact field names and their expected values) will be required to ensure correct translation to Airspace Link's schema.

  • Location Data Handling: Survey123 can typically collect geometry directly. Confirm how they are collecting location data (e.g., point, polygon) and ensure it aligns with Airspace Link's API requirements.

4. Airspace Link Portal Configuration

This section covers the configuration steps on the Airspace Link side.

4.1. Create Power Automate Flows (By Airspace Link or Customer)

  • Draft Inbound Power Automate Flow: Create a Power Automate flow designed to trigger upon a Survey123 form submission and receive its data. This flow will generate a unique URL (if triggered by HTTP request).

  • Draft Outbound Power Automate Flow: Create a Power Automate flow designed to receive updates from the Airspace Link Portal and publish them back to the Survey123 feature layer.

  • Obtain Outbound URL (If applicable): If the Survey123 form isn't directly triggering the Power Automate flow, but rather a webhook that then calls an HTTP request, note the unique HTTP request URL generated by Power Automate. This will be used in Airspace Link's org.json configuration.

4.2. Update Airspace Link Configuration File

  • Navigate to the org.json configuration file in the Airspace Link GitHub repository (specific location to be provided by engineering).

  • For each environment (e.g., Development, Staging, Production), add a new entry for the customer's organization.

  • Required Data for Each Organization Entry:

    • uniqueId: A unique, randomly generated ID (can be generated by Airspace Link).

    • org_name: The exact organization name as defined in Auth0.

    • org_id: The unique organization identifier from Auth0.

    • outbound_url: The HTTP request URL generated from the inbound Power Automate flow (see Section 4.1).

5. Survey123 System-Specific Configuration

5.1. Customer's Survey123 Form Creation

  • Objective: The customer creates their Survey123 form to collect work order requests.

  • Action: The customer will design and publish their Survey123 form.

    • Best Practice: Encourage the customer to use a provided Airspace Link schema template to simplify subsequent field mapping.

    • Ensure the form collects necessary fields like title, description, and location (geometry if possible).

5.2. Power Automate Flow (Inbound - Simpler Mapping)

  • Objective: To receive Survey123 data and create a work order in AirHub® Portal.

  • Action: Configure the Power Automate flow:

    • Trigger: Set to "When a new survey response is submitted" (or "When an HTTP request is received" if using webhooks).

    • Field Definition: Define the expected fields from the Survey123 response.

    • Data Mapping: Implement logic to transform Survey123 fields into Airspace Link's standardized work order schema. This is typically straightforward if a template schema is used.

    • API Call: Add an action to make an HTTP POST request to the Airspace Link API to create the work order.

5.3. Power Automate Flow (Outbound - Update Feature Layer)

  • Objective: To receive work order updates from AirHub® Portal and apply them back to the original Survey123 record.

  • Action: Configure the Power Automate flow:

    • Trigger: Set to "When an HTTP request is received" (from AirHub® Portal).

    • Action: Use the "Update a Record in a Feature Layer" functionality.

    • Target: Identify the specific Survey123 feature layer and the record to update (e.g., using a unique ID passed from AirHub® Portal).

    • Field Mapping: Map Airspace Link update fields (e.g., status) to the corresponding fields in the Survey123 feature layer. Some status value mapping may be required.

6. Testing & Validation

Thorough testing is crucial to ensure the two-way integration works as expected.

  • Test Inbound Flow: Submit a Survey123 form and verify the new work order appears correctly in the AirHub® Portal with all mapped fields.

  • Test Outbound Flow: Update a work order's status (or other allowed fields) in the AirHub® Portal and verify these changes are reflected accurately in the original Survey123 record's feature layer.

  • Edge Cases: Test various scenarios, including different field values and potential error conditions.

7. Important Considerations & Best Practices

  • Power Automate Flow Ownership: A clear decision is needed on whether customers manage their own Power Automate flows (requiring detailed instructions from Airspace Link) or if Airspace Link creates/manages them using customer ArcGIS Online credentials.

  • Survey123 Form Customization: While customization is supported, a standardized schema (e.g., via a template provided by Airspace Link) will significantly reduce integration complexity.

  • Documentation: Capture detailed documentation as you go for each integration, particularly for unique customer configurations, to build repeatable processes.

PreviousServiceNow Work Order Integration

Last updated