Skip to main content

Castor EDC Data Source

The Castor EDC connector enables you to ingest clinical study data—including participants (records), CRF and survey data points, study metadata, and audit trails—from your Castor EDC studies. Follow the instructions below to create a new data flow that ingests data from a Castor EDC source in Nexla.
castor_edc_api.png

Castor EDC

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 Castor EDC connector tile from the list of available connectors. Then, select the credential that will be used to connect to the Castor EDC instance, and click Next; or, create a new Castor EDC credential for use in this flow.

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

    Castor EDC sources can also be configured manually, allowing you to ingest data from Castor EDC 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 Castor EDC endpoints. Each template is designed specifically for the corresponding Castor EDC endpoint, making data source setup easy and efficient.

Many Castor EDC endpoints are scoped to a specific study, and several are further scoped to a specific participant (record) or survey package instance. These templates require you to supply the relevant identifiers, all of which can be obtained from the higher-level list endpoints (for example, use Get Study to find Study IDs and List Study Records to find Record IDs).

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.

    Get Current User

    Retrieves information about the user account associated with the configured API credentials. Use this endpoint to confirm connectivity and identify the account Nexla is authenticating as.

    • No additional configuration is required beyond selecting this endpoint template. The endpoint returns the details of the currently authenticated user.

    This is a useful first endpoint to test that your credential is valid and reaching the correct Castor environment.

    Get Study

    Retrieves the list of studies accessible to the authenticated user. Use this endpoint to discover the studies available in your account and to obtain the Study IDs required by most other Castor EDC endpoints.

    • No additional configuration is required beyond selecting this endpoint template. Results are paginated automatically, and Nexla fetches additional pages until all studies have been retrieved.

    The Study ID returned by this endpoint is required to configure most study-scoped endpoints, such as List Study Records, List Study Fields, and Export Study Data.

    Get Study By ID

    Retrieves metadata for a single study identified by its Study ID. Use this endpoint when you already know the study you want and need its detailed metadata.

    • Enter the identifier of the study in the Study ID field. Study IDs can be obtained from the Get Study endpoint.

    Get Audit Trail

    Retrieves the audit trail records for a study, capturing changes and actions performed within the study. Use this endpoint for compliance, monitoring, or change-tracking workflows.

    • Enter the identifier of the study in the Study ID field. Study IDs can be obtained from the Get Study endpoint.

    List Countries

    Retrieves the list of countries available in Castor. Use this reference data when mapping or validating country values used in study sites and records.

    • No additional configuration is required beyond selecting this endpoint template.

    List Study Surveys

    Retrieves the surveys defined in a study. Surveys are the building blocks of ePRO data collection in Castor.

    • Enter the identifier of the study in the Study ID field. Study IDs can be obtained from the Get Study endpoint.

    List Survey Packages

    Retrieves the survey packages defined in a study. A survey package groups one or more surveys that are dispatched to participants together as an ePRO submission.

    • Enter the identifier of the study in the Study ID field. Study IDs can be obtained from the Get Study endpoint.

    List Study Sites

    Retrieves the sites participating in a study. Sites represent the clinical locations enrolling participants.

    • Enter the identifier of the study in the Study ID field. Study IDs can be obtained from the Get Study endpoint.

    List Study Fields

    Retrieves all fields defined in a study. Fields define the individual variables collected on CRFs and surveys and are an essential part of a study's data dictionary.

    • Enter the identifier of the study in the Study ID field. Study IDs can be obtained from the Get Study endpoint.

    List Field Dependencies

    Retrieves the field dependencies defined in a study. Field dependencies control when fields are shown or hidden based on the values of other fields.

    • Enter the identifier of the study in the Study ID field. Study IDs can be obtained from the Get Study endpoint.

    List Field Validations

    Retrieves the field validation rules defined in a study. Validations enforce data quality constraints, such as ranges and required values, on collected field data.

    • Enter the identifier of the study in the Study ID field. Study IDs can be obtained from the Get Study endpoint.

    List Study Forms

    Retrieves all forms configured in a study. Forms (CRFs) organize fields into structured pages for data entry.

    • Enter the identifier of the study in the Study ID field. Study IDs can be obtained from the Get Study endpoint.

    List Study Roles

    Retrieves all user roles defined in a study. Roles determine the permissions granted to users assigned to the study.

    • Enter the identifier of the study in the Study ID field. Study IDs can be obtained from the Get Study endpoint.

    List Field Option Groups

    Retrieves all field option groups configured in a study. Option groups define the selectable answer options for choice-based fields.

    • Enter the identifier of the study in the Study ID field. Study IDs can be obtained from the Get Study endpoint.

    Get Study Statistics

    Returns statistical summary data for a study, including participant counts and data completion metrics. Use this endpoint for study-level progress reporting and dashboards.

    • Enter the identifier of the study in the Study ID field. Study IDs can be obtained from the Get Study endpoint.

    List Study Users

    Returns all users assigned to a study. Use this endpoint for access review and user management reporting.

    • Enter the identifier of the study in the Study ID field. Study IDs can be obtained from the Get Study endpoint.

    List Study Visits

    Returns all visit definitions configured in a study. Visits represent the scheduled time points at which data is collected for participants.

    • Enter the identifier of the study in the Study ID field. Study IDs can be obtained from the Get Study endpoint.

    List Study Records

    Retrieves a paginated list of all participants (records) enrolled in a study. This is the primary endpoint for discovering Record IDs used by participant-scoped endpoints.

    • Enter the identifier of the study in the Study ID field. Study IDs can be obtained from the Get Study endpoint.

    In Castor, a "record" represents an individual study participant. The Record IDs returned here are required to configure endpoints such as Get Record, List Study Data Points, and List Record Survey Package Instances.

    Get Record

    Retrieves a single participant (record) by ID. Use this endpoint when you need the details of one specific participant.

    • Enter the identifier of the study in the Study ID field. Study IDs can be obtained from the Get Study endpoint.
    • Enter the identifier of the participant in the Record ID field. Record IDs can be obtained from the List Study Records endpoint.

    List Study Data Points

    Retrieves the study-form data points (CRF answers) collected for a specific participant. Use this endpoint to extract the clinical field values entered for a participant's study forms.

    • Enter the identifier of the study in the Study ID field. Study IDs can be obtained from the Get Study endpoint.
    • Enter the identifier of the participant in the Record ID field. Record IDs can be obtained from the List Study Records endpoint.

    List Repeating Data Instances

    Retrieves all instances of repeating-data (report) forms across a study, such as adverse events or concomitant medications. Repeating data captures information that can occur multiple times per participant.

    • Enter the identifier of the study in the Study ID field. Study IDs can be obtained from the Get Study endpoint.

    List Record Repeating Data Instances

    Lists all repeating-data instances belonging to a specific participant. Use this endpoint to enumerate the repeating-data instances for one record before retrieving their data points.

    • Enter the identifier of the study in the Study ID field. Study IDs can be obtained from the Get Study endpoint.
    • Enter the identifier of the participant in the Record ID field. Record IDs can be obtained from the List Study Records endpoint.

    List Repeating Data Data Points

    Retrieves the data points captured for a specific repeating-data instance on a participant. Use this endpoint to extract the field values recorded within a single repeating-data instance.

    • Enter the identifier of the study in the Study ID field. Study IDs can be obtained from the Get Study endpoint.
    • Enter the identifier of the participant in the Record ID field. Record IDs can be obtained from the List Study Records endpoint.
    • Enter the identifier of the repeating-data instance in the Repeating Data Instance ID field. These IDs can be obtained from the List Repeating Data Instances or List Record Repeating Data Instances endpoints.

    List Record Survey Package Instances

    Retrieves all survey package instances (ePRO submissions) for a specific participant. Use this endpoint to track which surveys have been dispatched to or completed by a participant.

    • Enter the identifier of the study in the Study ID field. Study IDs can be obtained from the Get Study endpoint.
    • Enter the identifier of the participant in the Record ID field. Record IDs can be obtained from the List Study Records endpoint.

    List Survey Package Instance Data Points

    Retrieves all survey data points collected for a specific survey package instance (ePRO submission). Use this endpoint to extract the survey responses captured for one dispatched survey package.

    • Enter the identifier of the study in the Study ID field. Study IDs can be obtained from the Get Study endpoint.
    • Enter the identifier of the survey package instance in the Survey Package Instance ID field. These IDs can be obtained from the List Record Survey Package Instances endpoint.

    Export Study Data

    Bulk-exports all clinical data (records and data points) for a study in a single response. Use this endpoint when you need a complete snapshot of a study's collected data rather than per-participant calls.

    • Enter the identifier of the study to export in the Study ID field. Study IDs can be obtained from the Get Study endpoint.

    Study data exports can return large volumes of data. This endpoint is well suited for periodic full-data ingestion into a database or data warehouse.

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​

Castor EDC data sources can be manually configured to ingest data from any valid Castor EDC 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 Castor EDC sources, such as sources that use chained API calls to fetch data from multiple endpoints or sources that require custom request parameters.

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 Castor EDC API from the Method pulldown menu. Castor EDC read endpoints use:

    • GET: For retrieving data from the API

API Endpoint URL​

  1. Enter the URL of the Castor EDC API endpoint from which this source will fetch data in the Set API URL field. This should be the complete URL including the protocol (https://) and any required path parameters. Castor endpoints are built on your environment base URL—for example, https://data.castoredc.com/api/study/{'{study_id}'}/record to list records for a study, where {'{study_id}'} is the identifier of your study.

Ensure the API endpoint URL is correct and accessible with your current credentials, and that it matches the regional environment configured in your credential. You can test the endpoint using the Test button after configuring the URL.

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.

Macros are particularly useful for APIs that require date ranges, pagination parameters, or other dynamic values that change between data ingestion runs.

  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. This format will be applied to the base datetime value of the macro—i.e., the value of {now} in {now-1}.

  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 create API endpoints that reference specific IDs, values, or parameters from other data sources in your Nexla environment—for example, iterating Castor record retrieval over a list of Record IDs maintained in a lookup.

  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 that will be returned by the API endpoint is needed, you can designate the part(s) of the response that should be included in the Nexset(s) produced from this source by specifying the path to the relevant data within the response. This is particularly useful when API responses contain metadata, pagination information, or other data that you don't need for your analysis.

Castor list endpoints return their records inside an _embedded object. For example, the List Study Records endpoint returns participants under $._embedded.records[*], and List Study Fields returns fields under $._embedded.fields[*]. By entering the path to the relevant array, you can configure Nexla to treat each element of the returned array as a record.

Path to Data is essential when API responses have nested structures. Without specifying the correct path, Nexla might not be able to properly parse and organize your data into usable records.

  • 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., $._embedded.records[*] to access the array of records returned by Castor list endpoints).

    • For responses in XML format, enter the XPath that points to the object/array containing relevant data. XPath uses slash notation (e.g., /response/data/item to access item elements within a data element).

    Path to Data Example:

    For the Castor List Study Records endpoint, the participants are returned in the array $._embedded.records[*], so this value would be entered as the path to data.

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.

    PathSuggestions.png

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 when you want to preserve important contextual information that applies to all records but isn't part of the main data array.

For example, Castor list responses include pagination information and total counts alongside the embedded record array. If you have specified the path to the relevant data but want to retain this contextual metadata, you can specify a path to it to include it with each record in the generated Nexset(s).

Metadata paths are particularly useful for preserving API response context like total counts, page information, or request timestamps that apply to all records in the response.

  • 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, and for responses in XML format, enter the XPath.

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). Additional headers are often required for API versioning, content type specifications, or custom requirements.

    You do not need to include any headers already present in the credentials. The OAuth 2.0 Authorization header is added automatically by Nexla based on your credential configuration.

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 Castor EDC 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.