Setting up Confirm integration - Data Sources

The "Data Sources" tab is where you define the data which you wish to pull from Confirm.

For the Confirm map widget, each of these can be thought of as a map layer. Once a Data Source is defined here, it can be used in as many places as needed throughout the website.

To add a new Data Source, click the Add Another button below the table.

• Name - a name to identify the data source in places that it is used, this is not shown to public users.
• Type - for data to be pulled from Confirm, select Confirm GraphQL query.
• Query - paste the GraphQL query generated in Confirm (see "Generating a GraphQL query").

Then click the Test Query button. This will analyze the query, outputting a summary listing the data fields that it will return, and the fields which hold spatial data (i.e. coordinates). If no spatial data is found then it will not be possible to use the Data Source on a map.

If everything looks correct, click Save.

If errors are shown after clicking Test Query or Save, correct these before trying again.

Generating a GraphQL query

A GraphQL query defines what data should be pulled from Confirm, specifying the fields required and any criteria to apply.

GraphQL queries are created in the Confirm Web Reporting interface.

Use the reporting interface to select the required data. For more information, please see the Confirm Web documentation.

Below is a very simple example to fetch features (aka Assets) representing Waste Bins. We're selecting the geometry column (so we can plot the bins on a map), the siteCode column (as Confirm expects this when raising an Enquiry) and the centralAssetId column (so we can identify the bin in any Enquiries raised against it).

Filters ("3. Set Filters", on the right-hand side of the screen) are being used to exclude any "dead" features, and only include features of type "WBIN".

Note: feature type codes are specific to your Confirm instance, so you would need to substitute this with a valid code for a feature type defined within your Confirm instance.

If we plan to display any of the data to end users, we may want to give the columns more friendly labels. This can be done by giving the columns aliases, in the 2. Set Display Preferences section, on the right hand side of the screen. In the example below we've set the alias for the centralAssetId column to be "Bin_number". Spaces aren't allowed in column aliases, but if we use an underscore, this will be replaced by a space when displayed to end users, resulting in the label "Bin number".

You can test your query by clicking the Run button, the data which would be returned by the query is displayed in tabular format below. You should make sure that it includes all of the data which you wish to display on a single map layer, plus any data which would not necessarily need to be shown to the end user, but is required for the purposes of raising an Enquiry (for example Asset ID, Site code, etc).

Once you're happy with the data returned, you need to get a copy of the query that is being run. To do this, open the Network tab of your browser's Developer Tools (refer to this guide for how to open Developer Tools in your browser). Click the Run button in the Reporting interface again, and then look for a request in the Network tab of Developer tools to a graphql endpoint. Depending on the browser you are using, you will find the query in the Request or Payload section (shown below using Chrome). Copy the query and paste it into the Query field when creating your Data Source in Jadu.

You may notice that when clicking the Test Query button, the query is amended. This is normal, Jadu is adding in additional filters on the spatial columns so that only the data for the relevant area of the map is returned. The summary output by the test will highlight when this has happened.

GraphQL queries can be made much more complex, such as including data from multiple tables in Confirm. It is important to remember that these queries will be run in real time as the end-user navigates the map, so the aim should be to make them as efficient as possible by only including data that is required.

Data considerations

A few things to consider when deciding on the Data Sources that you need to set up are:

• How do you wish for assets to be presented on the map, for example in the case of signs/signals, do you want different types to be visually distinguished as different data layers, with different markers? If so, you would need a separate GraphQL query for each type.
  • Asset attribute values can be included to present useful information about the asset on the map.
• Do you need to offer reporting against a location rather than a fixed asset (e.g. reporting a pothole)? If so, you'll need to define a GraphQL query which returns road/street features and their geometries.
  • It is advisable to include all roads/streets within the boundary of the area that the authority is responsible for, even if the authority is not responsible for maintaining a given road. This allows the map to more accurately identify the road on which the user is trying to report the issue, and also allows you to better inform/direct the user in scenarios where the authority is not responsible.
• Do you wish to display existing Enquiries on the map? If so, you would need to set up GraphQL queries looking at the "centralEnquiries" table in Confirm.
• Do you wish to display upcoming road maintenance or inspections on the map? If so you will need to define GraphQL queries for these.

Defining map boundary layers

A map boundary layer defines one or more polygons which represent the geographic area(s) that the authority is responsible for.

To create a boundary layer, create a Data Source and select "GeoJSON file" for the Type field. You will be prompted to either enter a "GeoJSON file url" or upload a "GeoJSON file", which contains the boundary polygon data. The coordinates for the polygons defined in the GeoJSON file should be in lat/long (ESPG:4326).