Configure Connector Data Mappings

Create mappings between Survey123 and Cartegraph

To set up data mappings between the two systems, the Agency administrator must be presented with a list of available fields in each system. For this connector, the integration with Cartegrahh provides a real-time collection of fields. However, ArcGIS Survey123 does not. To have the ArcGIS Survey123 fields available for data mapping, it is necessary to post a survey result to a special URL/Endpoint of Velosimo. Once completed, the URL will be returned to its normal use value.

Initial Velosimo Connector Form Setup

The first step is to get the form structure set within Velosimo so that we have access to the URL needed for the next step. Log into the Administrator Site and then select 'Survey 123' under 'Digital Services', which is under 'Cartegraph' in the left Menu:

1436

Then Click 'ADD NEW FORM' on the top right:

1442

You will see a 'New form' popup. This is your 'Velosimo' form where you define the data mappings between the ArcGIS Survey123 Form and Cartegraph.

Enter the name of your form and click "OK":

959

You will be taken back to the Cartegraph Survey123 forms listing screen. Click the name of your new connector:

If you happen to have another form defined and linked, you must first unlink that form to proceed.

1437

You will see a popup that displays the setup Endpoint URL. Click the copy icon and then click close:

You now have the URL in memory for the next step.

961

Send Survey123 Form Fields to Velosimo

The second step is to set the URL Endpoint value to Velosimo setup, post the Survey123 form fields to Velosimo, and then reset the URL Endpoint value for normal use.

Log into ArcGIS Survey 123:

488

Click the Form set up prior:

1435

Set Survey123 Webhook for Setup

Now let's set the payload webhook so that Survey123 sends the information to the Velosimo connector setup endpoint. Click 'Settings'

1423

Now click 'Webhooks':

1435

Next, click the edit link under 'Operations' for your ArcGIS Survey123 Form:

1438

Now paste the setup URL Endpoint value from the Velosimo form into the 'Payload URL' field and click "Save":

1437

Post Survey123 Form Fields to Velosimo

Now that we have set the endpoint to which Survey123 will post, we now need to submit the form which will result in velosimo receiving the form field values from the Survey123 form:

Click the 'Collaborate' menu item:

1434

Once redirected to the 'Share survey' screen, click on the Open icon next to the link box:

1429

You will be taken to the Survey123 form, ready for input and submission.

This step is special because we are using this form submission to send the field data to Velosimo for the upcoming mapping exercise. As a result, there is no need to input any data into the fields except for any fields you set as required during the Survey123 form setup.

After you enter any required data, click 'Submit':

451

You will be presented with a screen confirming successful submission:

518

Final Velosimo Connector Form Setup

Now that we have sent the Survey123 form field data to Velosimo let's map the fields between the two systems and then rest the Survey123 webhook to normal use of forms submission.

Map fields from Survey123 to Cartegraph

It's time to configure the actual mappings between ArcGIS Survey123 and Cartegraph. Return to the Agency Administrator site for the Connector and Select 'Survey 123' under 'Digital Services' under the 'Cartegraph' menu item:

Note: if you were already logged into Velosimo, you would need to refresh your screen.

1715

You will notice the green chain link, indicating your prior setup submission from ArcSurvey 123 was successful.

Click the name of the Velosimo form:

1715

Top-Level Mappings

If you were setting up a service request type form, click 'REQUEST.' In this example, we are setting up an asset cleaning, so we will select "ASSET":

1459

Next, complete the top-level mappings as per your connector. This example will set the Aset Type to 'Storm Manhole' and Activity to 'Clean.'

We will save our work after performing at least one field-level mapping next

Field-Level Mappings

Once finished, we will map the fields, starting by clicking the '+' (added Mapping) button:

1460

Next, you will see a popup with the Cartegraph fields. Select the first one you wish to map to your Survey123 form. In this example, we select 'Actual Start Date':

1461

Next, you will see a popup showing the Survey123 fields. Select the one you want to map to the Cartegraph field and click 'Save'. In this example, we select 'visit_date':

Note that the Survey123 field names displayed are the key field IDs created by ESRI but should resemble the field names you entered when designing the survey form.

1467

After mapping each field, your mapping screen will refresh, noting the new mapping:

1476

Once you have completed your mappings, click 'SAVE':

1468

Set Survey123 Webhook for Normal Use

It's time to test our connector, but first, we need to set the payload webhook in Survey123 to normal survey collection: the Velosimo submission endpoint.

Copy the Submission URL from Velosimo

If you are not continuing from the prior step, log into Velosimo Admin for the connector and navigate to Digital Services 123 and select your Velosimo form completed in the prior step.

Click the 'Copy' Icon on the 'Submission URL' form field at the top of the page. This will place the URL into memory:

1453

Paste the Velosimo Submission URL into the ArcGIS Survey123 webhook field

If you no longer have your Arc Survey123 window open from the previous steps, log in to ArcGIS Survey123 and navigate to the survey form configured in a prior step.

Click the 'Settings' menu item in the top right:

1423

Click 'Webhooks' in the top left:

1435

Click the edit pen under 'Operations':

1438

Paste the Velosimo Submission URL into the 'Payload URL' field and click 'Save':

1470

You will be directed back to the webhook screen:

1474

Congratulations, you have fully setup your Velosimo Connector for ESRI ArcGIS Survey123 to Cartegraph!