--- title: "Datacom Datascape Data Source" canonical: "https://help.cartinuum.com/space/GC1/4462280713/Datacom%20Datascape%20Data%20Source" format: markdown --- ## Overview The Datascape REST JSONata Data Source lets Connect for ArcGIS retrieve records from a Datacom Datascape REST API and display them against selected features in an ArcGIS web map. It is designed for Datascape endpoints where the response needs to be reshaped before it is shown to users. The data source authenticates to Datascape, calls a configured API resource, filters the response using a value from the selected map feature, and uses a JSONata expression to choose and format the fields returned to Connect for ArcGIS. ## Before You Start You will need: - The base URL for the Datascape customer API. - A Datascape username and password with access to the required API resource. - The Datascape resource path to query. - A shared identifier between the ArcGIS layer and the Datascape response, such as a property ID, parcel ID, contact ID or custom GIS reference. - A JSONata expression that returns the fields you want users to see. ## Data Source Settings Configure these settings when adding the Datascape data source. ### Base URL The base URL for the Datascape API. Example: ``` https://datascape.cloud/customer-name ``` ### Username The Datascape username used for OAuth authentication. ### Password The Datascape password used for OAuth authentication. We recommend you use a Datascape credential with the minimum read-only permissions to access the API. It will be used as a service account for all requests. ## Layer Link Settings Configure these settings when linking the Datascape data source to a map layer. ### Resource Path The Datascape API endpoint path to call. This is appended to the Base URL and can include feature attributes using `{{ATTRIBUTE_NAME}}`. Examples: ``` /custom/v4/ESRI_AGOL_DATACOM_API /api/properties/{{PROPERTY_ID}}/details ``` ### Filter Column The field in the Datascape API response that matches a value from the ArcGIS feature layer. This is used to build the primary Datascape filter. Examples: ``` LandParcel.ID Property.#Custom.Property.Value5 Contact.ContactID ``` ### Filter Attribute The ArcGIS feature attribute that contains the value to match against the Filter Column. Example: ``` {{PROPERTY_ID}} ``` When a user selects features in the map, Connect for ArcGIS uses this value to build a filter similar to: ``` LandParcel.ID in [`12345`,`67890`] ``` ### Additional Filters Optional filter conditions to append to the primary filter. Additional filters must start with `and` or `or` and can include feature attributes using `{{ATTRIBUTE_NAME}}`. Example: ``` and Status eq 'Active' and Type eq '{{PROPERTY_TYPE}}' ``` ### Additional Query Parameters Optional query parameters to include with the request. Enter one parameter per line in `name=value` format. Values can include feature attributes using `{{ATTRIBUTE_NAME}}`. Example: ``` $select=id,name,address,status $top=100 $orderby=name asc ``` ### Maximum Request Size The maximum number of selected features to include in a single Datascape API request. The default is `20`, with supported values from `1` to `100`. Smaller values can reduce response size. Larger values can reduce the number of requests when users select many features. ### JSONata Transformation A JSONata expression that transforms each Datascape entity into the fields returned to Connect for ArcGIS. The most simple JSONata Transformation is `$` meaning return the response object without any transformation. You might start with `$` to understand the response data and then apply a transformation as required to access one-to-many records related to the selected feature. Simple example: ``` { "id": id, "name": name, "status": status } ``` Nested field example: ``` { "id": id, "fullName": contact.firstName & " " & contact.lastName, "address": address.street & ", " & address.city } ``` For best results, return a flat object with simple values. The transformation may return a single object or an array of objects, but individual returned objects must not contain arrays. ### Test Data Test data is used when validating the layer link. Add values for any feature attributes used in the Resource Path, Filter Attribute, Additional Filters or Additional Query Parameters. Example: ``` {{PROPERTY_ID}}=12345 {{PROPERTY_TYPE}}=Residential ``` ## Example: Show Property Details from Datascape This example retrieves active Datascape property records where `LandParcel.ID` matches the selected map feature's `PROPERTY_ID` attribute. Data source settings: ``` Base URL: https://datascape.cloud/customer-name Username: your-datascape-username Password: your-datascape-password ``` Layer link settings: ``` Resource Path: /custom/v4/ESRI_AGOL_DATACOM_API Filter Column: LandParcel.ID Filter Attribute: {{PROPERTY_ID}} Maximum Request Size: 20 ``` Additional filters: ``` and Status eq 'Active' ``` Additional query parameters: ``` $select=id,name,address,status $top=100 ``` JSONata transformation: ``` { "Property ID": id, "Name": name, "Address": address, "Status": status } ``` Test data: ``` {{PROPERTY_ID}}=12345 ``` When a user selects one or more ArcGIS features, Connect for ArcGIS sends the matching property IDs to Datascape, transforms the returned entities with JSONata, and displays the resulting records. ## How Matching Works The data source batches selected features and queries Datascape using the `in` operator. For example, selecting three features can produce a filter like: ``` LandParcel.ID in [`12345`,`67890`,`24680`] ``` Results are matched back to each selected feature using the Filter Column value from the Datascape response. If a Datascape field contains comma-separated values, the data source can also match an individual selected feature value within that comma-separated list. ## Notes - The data source uses Datascape OAuth client credentials authentication. - Datascape responses must be JSON arrays. - Feature attributes can be used in the Resource Path, Filter Attribute, Additional Filters and Additional Query Parameters. - Additional filters must begin with `and` or `or`. - JSONata output should use simple values and should not include arrays inside returned objects. - Use Additional Query Parameters such as `$select`, `$top` and `$orderby` to limit and sort the data returned by Datascape.