This guide shows how to install and operate a Tetra Charles River Apollo Connector v1.x. The Connector is a standalone, containerized application that uses the Pluggable Connector Framework to automatically retrieve documents from the Charles River Apollo API and upload them to the Tetra Data Platform (TDP).

Install a Tetra Charles River Labs Apollo Connector

To install a Tetra Charles River Apollo Connector, do the following.

Prerequisites

Before you can create and use a Tetra Charles River Apollo Connector, you must have the following:

• An active TDP environment running version 3.6.0 or higher
• A Charles River Apollo API account with the following credentials:
  • Client ID
  • Client Secret
  • Subscription Key (Ocp-Apim-Subscription-Key)
  • OAuth Token URL
  • OAuth Scope
  • Base API URL
• IP allowlisting configured in the Charles River Apollo API firewall for your TDP environment's IP addresses
• Charles River Apollo Study Opt-In Manager pipeline v1.0.0 or higher deployed and configured in your TDP environment
• An AES-256 encryption key for encrypting study IDs and sponsor emails (required by the Charles River Apollo Study Opt-In Manager pipeline, not the Connector itself)

📘

NOTE

The Charles River Apollo API requires IP allowlisting. Contact your Charles River representative or TetraScience support to obtain the appropriate IP addresses for your TDP environment, as these vary by region and deployment type.

Configure IP Allowlisting

Before deploying the Connector, you must ensure that your TDP environment's IP addresses are allowlisted in the Charles River Apollo API firewall configuration by doing the following:

1. Contact your TetraScience support representative to obtain the list of IP addresses for your TDP environment.
2. Provide the list of IP addresses to your Charles River representative to have them allowlisted in the Apollo API firewall.
3. Verify that the IP addresses have been allowlisted by testing API connectivity from your TDP environment.

🚧

IMPORTANT

The Connector will not be able to connect to the Charles River Apollo API until the IP allowlisting is complete.

Configure Apollo API Credentials

The Connector requires several credentials and configuration values to authenticate with the Charles River Apollo API. Sensitive credential values should be stored as secrets in your TDP environment.

Required Configuration Values

The following configuration values are required:

• Base URL: The base URL for the Apollo API (for example, https://api.qa.criver.com/apollo-das for QA or https://api.criver.com/apollo-das for production)
• OAuth Token URL: The OAuth 2.0 token endpoint URL (for example, https://login.microsoftonline.com/{tenant-id}/oauth2/v2.0/token)
• OAuth Scope: The OAuth 2.0 scope for API access (for example, api://{app-id}/.default)
• Client ID: The OAuth 2.0 client ID provided by Charles River
• Client Secret: The OAuth 2.0 client secret provided by Charles River (store as a secret)
• Subscription Key: The Ocp-Apim-Subscription-Key for API access (store as a secret
• Encryption Key: A 256-bit (64-character hexadecimal) AES encryption key for encrypting study IDs and sponsor emails (store as a secret)

Create a Tetra Charles River Apollo Connector

To create a Tetra Charles River Apollo Connector, do the following:

1. Sign in to the TDP. Then, in the left navigation menu, choose Data Sources and select Connectors. The Connectors page appears.
2. Follow the instructions in Create a Pluggable Connector. For CONNECTOR TYPE, make sure that you select CRL Apollo.

📘

NOTE

After the Connector is created, the initial MODE status is set to IDLE by default. To activate the Connector, you must configure its settings. For instructions, see the Configure the Connector section.

Configure the Connector

On the Connectors page, select the name of the connector that you created. Then, select the Configuration tab to configure the required settings.

Configuration Parameters

The following table lists the configuration parameters available for the Tetra Charles River Apollo Connector.

🚧

IMPORTANT

When no startDate is configured and the Connector runs for the first time, it defaults to the current time. This means no historical documents will be downloaded. If you need to retrieve historical documents, you must explicitly set a startDate in the past.

Review and Edit the Connector's Information

The Information tab on the Connector Details page displays information about the Connector, the files pending, successfully uploaded, or failed. It also provides functionality to edit a Connector’s information, metadata, and tags.

To edit the Connector's information, select the Edit button on the Connector Details page's Information tab.

For more information, see Review and Edit a Pluggable Connector's Information.

Set the Connector's Status to Running

Set the Connector's status to Running by following the instructions in Change a Pluggable Connector's Status.

📘

NOTE

The Connector will not download any documents until studies have been opted into using the Charles River Apollo Study Opt-In Manager pipeline.

Configure the CRL Apollo Study Opt-In Manager Pipeline

The CRL Apollo Study Opt-In Manager pipeline is a companion pipeline that manages which studies are opted into for document retrieval. The pipeline must be deployed and configured before the Connector can download documents.

Deploy the Study Opt-In Manager Pipeline

To deploy the Charles River Apollo Study Opt-In Manager pipeline, do the following:

1. Contact your TetraScience support representative to obtain the Charles River Apollo Study Opt-In Manager pipeline artifacts (task script and protocol).
2. Deploy the pipeline by following the instructions in Set Up and Edit Pipelines.
3. Configure the pipeline with the same Charles River Apollo API credentials that you used for the Connector:
   • Base URL
   • OAuth Token URL
   • OAuth Scope
   • Client ID
   • Client Secret
   • Subscription Key
   • Encryption Key

Prepare the Study Opt-In CSV File

The Study Opt-In Manager pipeline accepts a CSV file that uses the following format.

CSV File Format

| CRL Study ID | Sponsor Email |
|--------------|---------------|
| STUDY-001 | [email protected] |
| STUDY-002 | [email protected] |

📘

NOTE

The CSV file must include a header row with the exact column names shown above: CRL Study ID and Sponsor Email.

• CRL Study ID: The unique identifier for the study in the CRL Apollo system
• Sponsor Email: The email address of the sponsor associated with the study (required by Charles River for security verification)

🚧

IMPORTANT

The sponsor email is a Charles River security requirement to ensure users are not attempting to opt into studies they are not associated with. The email must be valid and associated with the study in the Charles River Apollo system.

Opt In to Studies by Running the Study Opt-In Manager Pipeline

To opt into studies, run the Study Opt-In Manager Pipeline by doing the following:

1. Create a CSV file with the list of studies you want to opt into, following the required CSV file format.
2. Upload the CSV file to the TDP.
3. Run the CRL Apollo Study Opt-In Manager pipeline with the uploaded CSV file as input.
4. The pipeline does the following:
   • Queries the Charles River Apollo /v1/studies endpoint to retrieve the list of currently opted-in studies
   • Opts into any studies in the CSV file that are not currently opted into (if the sponsor email is valid)

📘

NOTE

The pipeline only supports opting into studies. Once a study is opted in, it will remain opted in and the Connector will continue to retrieve documents from that study.

Monitor and Operate the Connector

After the Connector is deployed and studies have been opted into, the Connector will automatically poll the CRL Apollo API and download documents.

Metrics

After a Connector instance is created and running, you can monitor the Connector’s health by selecting the Metrics tab on the Connector Details page. The Metrics tab displays the Connector's container metrics as well as aggregated states on total files scanned and uploaded as well as files that returned errors or are pending.

Access Data

To view documents downloaded by the Connector, do the following:

1. Sign in to the TDP and open the Search page.
2. Use the following labels to filter for documents downloaded by the Connector:
   • Apollo crlStudyId: Filter by CRL study ID
   • Apollo documentId: Filter by document ID
   • Apollo documentType: Filter by document type
   • Apollo primaryStudyContact: Filter by primary study contact
   • Apollo status: Filter by document status
   • Apollo crlSite: Filter by CRL site location
   • Apollo gxpFlag: Filter by GxP status ("true" or "false")

Troubleshooting

Connector is Not Downloading Documents

If the Connector is running but not downloading documents, check the following:

• IP Allowlisting: Verify that your TDP environment's IP addresses are whitelisted in the CRL Apollo API firewall.
• Study Opt-In: Verify that studies have been opted into using the CRL Apollo Study Opt-In Manager pipeline.
• API Credentials: Verify that the CRL Apollo API credentials are correct and have not expired.
• Connector Logs: Check the Connector logs for errors or warnings that may indicate the issue.

Authentication Errors

If you see authentication errors in the Connector logs, do the following:

• Verify that the OAuth Token URL, OAuth Scope, Client ID, and Client Secret are correct.
• Verify that the Subscription Key is correct.
• Check that the credentials have not expired or been revoked.

Study Opt-In Errors

If you see errors when running the Charles River Apollo Study Opt-In Manager pipeline, do the following:

• Verify that the sponsor email addresses in the CSV file are valid and associated with the studies in the CRL Apollo system.
• Verify that the encryption key is correct and matches the key expected by the CRL Apollo API.
• Check the pipeline logs for specific error messages.

Documentation Feedback

Do you have questions about our documentation or suggestions for how we can improve it? Start a discussion in TetraConnect Hub. For access, see Access the TetraConnect Hub.

📘

NOTE

Feedback isn't part of the official TetraScience product documentation. TetraScience doesn't warrant or make any guarantees about the feedback provided, including its accuracy, relevance, or reliability. All feedback is subject to the terms set forth in the TetraConnect Hub Community Guidelines.