Datascope Data Source

The Datascope connector enables you to ingest data from your Datascope account into Nexla, including form answers, locations, metadata lists, task assignments, tickets, notifications, and generated files. Follow the instructions below to create a new data flow that ingests data from a Datascope source in Nexla.

Datascope

Create a New Data Flow

1. To create a new data flow, navigate to the Integrate section, and click the New Data Flow button. Then, select the desired flow type from the list, and click the Create button.

2. Select the Datascope connector tile from the list of available connectors. Then, select the credential that will be used to connect to the Datascope account, and click Next; or, create a new Datascope credential for use in this flow.

3. In Nexla, Datascope data sources can be created using pre-built endpoint templates, which expedite source setup for common Datascope endpoints. Each template is designed specifically for the corresponding Datascope endpoint, making source configuration easy and efficient.
   • To configure this source using a template, follow the instructions in Configure Using a Template.

   Datascope sources can also be configured manually, allowing you to ingest data from Datascope endpoints not included in the pre-built templates or apply further customizations to exactly suit your needs.
   • To configure this source manually, follow the instructions in Configure Manually.

Configure Using a Template

Nexla provides pre-built templates that can be used to rapidly configure data sources to ingest data from common Datascope endpoints. Each template is designed specifically for the corresponding Datascope endpoint, making data source setup easy and efficient.

Endpoint Settings

• Select the endpoint from which this source will fetch data from the Endpoint pulldown menu. Available endpoint templates are listed in the expandable boxes below. Click on an endpoint to see more information about it and how to configure your data source for this endpoint.

List Locations

Returns a list of all locations available in your Datascope account. Use this endpoint to retrieve the full catalogue of locations defined in Datascope, which are used to assign tasks, associate form answers, and organize field operations geographically.

• This endpoint requires no additional configuration parameters beyond selecting the template. Nexla will automatically retrieve all locations from your account using offset-based pagination, fetching up to 200 records per page.
• Each location record typically includes the location name, code, address, coordinates (latitude and longitude), and associated contact and company information.

Location data is foundational for many Datascope workflows. Use the List Locations endpoint to build a directory of your operational sites before joining location IDs returned by other endpoints (such as List Answers) to their full location details.

List Answers (v2 - flat format)

Returns all form answers collected in your Datascope account in the v2 flat format, where each row represents a single answer to a single question. This is the preferred endpoint for analytical and data pipeline use cases because the flat structure integrates directly with tabular data destinations such as databases and data warehouses.

• This endpoint requires no additional configuration parameters beyond selecting the template. Nexla will automatically retrieve answers using offset-based pagination, fetching up to 200 records per page.
• Each record includes the form name, form ID, submitting user details, timestamps, GPS coordinates, location assignment, and the individual question-answer pair.

The v2 flat format is recommended over the v1 nested format for most analytical pipelines because each row contains a single question-answer pair, making it easier to filter, aggregate, and join with other data. Use the List Answers (v1 - nested format) endpoint only if your pipeline requires the legacy grouped structure.

List Answers (v1 - nested format)

Returns form answers in the legacy v1 nested format, where answers are grouped by form submission rather than returned as individual question-answer rows. Use this endpoint when your analytical pipeline depends on the form-grouped structure or when integrating with systems built against the original Datascope API format.

• This endpoint requires no additional configuration parameters beyond selecting the template. It returns a static (non-paginated) response.
• Note that the v1 endpoint has a 600-record cap. For accounts with large volumes of submissions, use the List Answers (v2 - flat format) endpoint to retrieve complete data sets without this limitation.

The v1 endpoint is provided for backward compatibility. For new pipelines, the v2 flat format endpoint is recommended, as it supports full pagination and returns data in a structure that is easier to work with in most analytical tools.

List Metadata Objects

Returns the full catalogue of metadata list elements in your Datascope account, such as products, clients, or any other custom list types your organization has defined. Metadata objects are used in Datascope to standardize dropdown options and reference data across forms.

• This endpoint requires no additional configuration parameters beyond selecting the template. The full result set is returned in a single response without pagination.
• Each metadata object record includes the element name, code, description, and any custom attributes defined for the list type.

Use this endpoint to extract your Datascope reference data for use in lookups or to enrich other data sources. To retrieve a single specific metadata element by its type and ID, use the Get Metadata Object endpoint instead.

List Notifications

Returns a list of all notifications generated for your Datascope account. Notifications in Datascope are alerts triggered by form submissions or other events, and can be used to monitor field activity, flag anomalies, or track compliance issues in real-time.

• This endpoint requires no additional configuration parameters beyond selecting the template. Nexla will automatically retrieve all notifications using offset-based pagination, fetching up to 200 records per page.

Get Metadata Object

Retrieves a single metadata list element by its metadata type and ID. Use this endpoint to resolve specific list item references returned by other Datascope endpoints (such as List Metadata Objects or form answers that include list IDs).

• This endpoint requires the following parameters:

  • Metadata Type: Enter the name of the metadata list (list type) that the element belongs to. This corresponds to the metadata_type field in the Datascope API. For example, if your account has a list named "products", enter products.
  • Metadata ID: Enter the numeric ID of the specific metadata list element you want to retrieve. This ID is returned by the List Metadata Objects endpoint and is referenced as list_id in form answer records.

Use the List Metadata Objects endpoint first to identify the correct metadata type name and element IDs before configuring this endpoint. The Get Metadata Object endpoint is useful for resolving individual list item references without downloading the entire catalogue.

List Files

Returns the most recently generated files in your Datascope account, such as PDF reports and data exports produced by Datascope's reporting features. Use this endpoint to track or download output files generated from form submissions and scheduled reports.

• This endpoint requires no additional configuration parameters beyond selecting the template. The result set is returned in a single response without pagination.
• Each file record includes metadata such as the file name, type, URL, and creation date. Optional start and end query parameters can be used in manual configuration to narrow results by date range.

This endpoint returns metadata about generated files, not the file content itself. To retrieve the actual file content, use the file URL provided in the response to download the file directly.

List Task Assigns

Returns task assignments for your Datascope account by period. Task assignments represent work items assigned to specific users for completion at a given location on a specified date. Use this endpoint to monitor field team workloads, track assignment completion rates, and integrate task data with workforce management or scheduling systems.

• This endpoint requires no additional configuration parameters beyond selecting the template. Nexla will automatically retrieve task assignments using offset-based pagination. The default page size is 100 records, with a maximum of 300 records per page.
• The response includes a nested structure containing a task_assigns array along with total, limit, and offset pagination fields. Nexla uses the task_assigns array as the source of individual records.

Get Task Assign

Retrieves a single task assignment by its numeric ID, including detailed assignment fields. Use this endpoint to fetch complete information about a specific task assignment when you know its ID.

• This endpoint requires the following parameter:

  • Task Assign ID: Enter the numeric ID of the task assignment to retrieve. Task assignment IDs are returned by the List Task Assigns endpoint.

Use the List Task Assigns endpoint first to identify task assignment IDs, then use Get Task Assign to retrieve full detail records for specific assignments.

List Tickets (Findings)

Returns tickets (also called findings) from your Datascope account filtered by period, status, and form. Tickets in Datascope are issues or non-conformances identified during inspections or audits that require follow-up action. Use this endpoint to track open issues, monitor resolution progress, and integrate ticket data with quality management or CAPA (corrective action and preventive action) systems.

• This endpoint requires no additional configuration parameters beyond selecting the template. Nexla will automatically retrieve tickets using offset-based pagination, fetching up to 200 records per page with a maximum offset of 2,000.
• Optional filters for status and task_form_id can be applied using manual configuration to narrow results to specific ticket types or form sources.

The pagination limit for this endpoint is a maximum of 200 records per page with a maximum offset of 2,000. For accounts with very large ticket volumes, consider filtering by date range or status to retrieve data in manageable segments.

Get Ticket (Finding)

Retrieves a single ticket (finding) by its numeric ID. Use this endpoint to fetch the complete detail record for a specific ticket, including all fields and status information, when you know its ID.

• This endpoint requires the following parameter:

  • Ticket ID: Enter the numeric ID of the ticket (finding) to retrieve. Ticket IDs are returned by the List Tickets (Findings) endpoint.

Use the List Tickets (Findings) endpoint first to identify ticket IDs, then use Get Ticket (Finding) to retrieve the complete record for a specific ticket.

Endpoint Testing

Once the selected endpoint template has been configured, Nexla can retrieve a sample of the data that will be fetched according to the current settings. This allows users to verify that the source is configured correctly before saving.

• To test the current endpoint configuration, click the Test button to the right of the endpoint selection menu. Sample data will be fetched & displayed in the Endpoint Test Result panel on the right.

• If the sample data is not as expected, review the selected endpoint and associated settings, and make any necessary adjustments. Then, click the Test button again, and check the sample data to ensure that the correct information is displayed.

Configure Manually

Datascope data sources can be manually configured to ingest data from any valid Datascope External API endpoint. Manual configuration provides maximum flexibility for accessing endpoints not covered by pre-built templates or when you need custom API configurations.

With manual configuration, you can also create more complex Datascope sources, such as sources that apply custom date range filters, additional query parameters, or custom request headers.

API Method

1. To manually configure this source, select the Advanced tab at the top of the configuration screen.

2. Select the API method that will be used for calls to the Datascope API from the Method pulldown menu. All Datascope External API read endpoints use:

   • GET: For retrieving data from the API (used for all Datascope source endpoints)

API Endpoint URL

3. Enter the URL of the Datascope External API endpoint from which this source will fetch data in the Set API URL field. All Datascope External API endpoints begin with https://www.mydatascope.com/api/external/. Some common endpoint URLs are:
   • https://www.mydatascope.com/api/external/locations — List all locations
   • https://www.mydatascope.com/api/external/v2/answers — List answers (v2 flat format)
   • https://www.mydatascope.com/api/external/answers — List answers (v1 nested format)
   • https://www.mydatascope.com/api/external/metadata_objects — List metadata objects
   • https://www.mydatascope.com/api/external/notifications — List notifications
   • https://www.mydatascope.com/api/external/files — List generated files
   • https://www.mydatascope.com/api/external/task_assigns — List task assignments
   • https://www.mydatascope.com/api/external/findings/list — List tickets (findings)

For additional Datascope External API endpoint details and available query parameters, refer to the DataScope API documentation and the DataScope API Reference.

Date/Time Macros (API URL)

Optional

Optionally, the API URL can be customized using macros—all macros added to the API URL will be converted into values when Nexla executes the API call. Macros are dynamic placeholders that allow you to create flexible API endpoints that can adapt to different time periods or data requirements.

Date/time macros are particularly useful with Datascope endpoints that accept start and end date query parameters (such as the List Files and List Answers endpoints), allowing Nexla to automatically retrieve only the data that falls within each ingestion window.

1. To add a macro, type { at the appropriate position in the API URL (within the Set API URL field), and select the desired macro from the dropdown list.

   • {now} – The current datetime
   • {now-1} – The datetime one time unit before the current datetime
   • {now+1} – The datetime one time unit after the current datetime
   • custom – Datetime macros can reference any number of time units before or after the current datetime—for example, enter (now-4) to indicate the datetime four time units before the current datetime

2. Select the format that will be applied to datetime macros from the Date Format for Date/Time Macro pulldown menu. The Datascope API uses yyyy-MM-dd date format for date parameters.

3. Select the datetime unit that will be used to perform mathematical operations in the included macro(s) from the Time Unit for Operations pulldown menu—for example, for the macro {now-1}, when Day is selected, {now-1} will be converted to the datetime one day before the current datetime.

Lookup-Based Macros (API URL)

Optional

Column values from existing lookups can also be included as macros in the API URL. Lookup-based macros allow you to reference data from previously configured data sources or lookups, enabling dynamic API endpoints that can adapt based on existing data.

Lookup-based macros are useful when you need to pass specific Datascope IDs (such as location IDs, form IDs, or user IDs) from another Nexla data source into the API endpoint URL or query string.

1. To include a lookup column value macro, select the relevant lookup from the Add Lookups to Supported Macros pulldown menu.

2. Type { at the appropriate position in the API URL, and select the lookup column-based macro from the dropdown list. Lookup-based macros are automatically populated into the macro list when a lookup is selected in the Add Lookups to Supported Macros pulldown menu.

Path to Data

Optional

If only a subset of the data returned by the Datascope API endpoint is needed, you can designate which part of the response should be included in the Nexset(s) produced from this source by specifying the path to the relevant data within the response.

For example, the List Task Assigns endpoint returns a response object containing a task_assigns array alongside pagination fields (total, limit, offset). By specifying $.task_assigns[*] as the path to data, you configure Nexla to treat each element of that array as a record.

Most Datascope External API endpoints return a top-level JSON array, so the path to data is typically $[*] (for array responses) or $ (for single-object responses). The List Task Assigns endpoint is an exception, returning $.task_assigns[*].

• To specify which data should be treated as relevant in responses from this source, enter the path to the relevant data in the Set Path to Data in Response field.

  • For responses in JSON format, enter the JSON path that points to the object or array that should be treated as relevant data. JSON paths use dot notation (e.g., $.data.items[*] to access an array of items within a data object).
  Path to Data Example:

  For a Datascope endpoint that returns a top-level JSON array (such as List Locations or List Answers), enter $[*] as the path to data. For the List Task Assigns endpoint, enter $.task_assigns[*].

Autogenerate Path Suggestions

Nexla can also autogenerate data path suggestions based on the response from the API endpoint. These suggested paths can be used as-is or modified to exactly suit your needs.

• To use this feature, click the Test button next to the Set API URL field to fetch a sample response from the API endpoint. Suggested data paths generated based on the content & format of the response will be displayed in the Suggestions box below the Set Path to Data in Response field.

• Click on a suggestion to automatically populate the Set Path to Data in Response field with the corresponding path. The populated path can be modified directly within the field if further customization is needed.

  

Metadata

If metadata is included in the response but is located outside of the defined path to relevant data, you can configure Nexla to include this data as common metadata in each record. This is useful for preserving contextual information such as pagination totals or request timestamps that apply to all records in the response.

For Datascope endpoints that return pagination fields (such as total, limit, and offset) alongside the data array (e.g., List Task Assigns), you can use the Metadata path to capture these fields and include them with each record.

• To specify the location of metadata that should be included with each record, enter the path to the relevant metadata in the Path to Metadata in Response field.

  • For responses in JSON format, enter the JSON path to the object or array that contains the metadata.

Request Headers

Optional

• If Nexla should include any additional request headers in API calls to this source, enter the headers & corresponding values as comma-separated pairs in the Request Headers field (e.g., header1:value1,header2:value2).

  You do not need to include the Authorization header here — it is automatically applied from your Datascope credential. The Datascope External API uses the Authorization header for all authentication, which Nexla handles automatically.

Endpoint Testing

After configuring all settings for the selected endpoint, Nexla can retrieve a sample of the data that will be fetched according to the current configuration. This allows users to verify that the source is configured correctly before saving.

• To test the current endpoint configuration, click the Test button to the right of the endpoint selection menu. Sample data will be fetched & displayed in the Endpoint Test Result panel on the right.

• If the sample data is not as expected, review the selected endpoint and associated settings, and make any necessary adjustments. Then, click the Test button again, and check the sample data to ensure that the correct information is displayed.

Save & Activate the Source

1. Once all of the relevant steps in the above sections have been completed, click the Create button in the upper right corner of the screen to save and create the new Datascope data source. Nexla will now begin ingesting data from the configured endpoint and will organize any data that it finds into one or more Nexsets.