1. Information for CRO and Sponsor Users
  2. About API Integration

20 About API Integration

If you are responsible for integration and endpoint management, you'll find details in this chapter. Links provided at the end of the chapter have task-based instructions for accessing API documentation, monitoring API messages on the Event Messages page, configuring endpoints with common authentication methods (e.g., Standard, OAuth, etc.), and more.

Sharing data via API integration

Oracle Site Activate includes outbound publishing functionality that allows CROs and sponsors to share data. At the account or study level, administrative you can select the types of API messages to be published outbound and the endpoint URL for each enabled publish message.

Account and study level settings are additive, not exclusionary. Settings made at the account level on the Manage Publish Endpoints page apply to ALL studies. Settings at the Study level on the Add or Edit Study page would generate an additional message. If you only want messages published for specific studies, you would enable the settings for those studies but leave them off at the Account level.

The following outbound post message types are supported:

  • Milestones – Publishes when milestones change (e.g., updated planned date).
  • Activity completion – Publishes when activities are created, completed, or updated.
  • Artifact event – Publishes an artifact change or completion for documents, submissions, packages, or IP release packages.
  • Scheduled activity dates – Publishes changes to baseline, planned, and actual activity dates for submissions and documents.
  • Site status change – Publishes site status changes (e.g., In activation, In feasibility, etc.).
  • eTMF – Publishes a file and metadata for the following event triggers:
    • IP package completed: Generates an eTMF publish message for each document in the IP package. An optional account setting can be enabled to send an additional eTMF outbound message with a document containing the IP package notes. Contact your Oracle services representative to discuss enabling this setting.
    • Document or contract completed: Generates an eTMF publish message that sends the document or contract to the TMF.
    • New file uploaded to document or contract: Generates an eTMF publish message that sends the document to TMF when a new file attachment is uploaded or an existing attachment is replaced on the corresponding placeholder in Oracle Site Activate
    • Submission package approved: An optional account setting can be enabled allowing permissioned users to manually trigger sending Submission package documents, once, to an eTMF from within the package itself.

      Tip:

      By design, Oracle Site Activate does not send eTMF messages without a file attached; Event Messages will show them as failed.
  • SIP – Publishes activities to the Shared Investigator Platform to be completed by a site user. This setting will only appear when your organization enables SIP functionality. Contact your Oracle services representative to discuss integration.

Note:

When Study library shares an item for the first time, the item updates to Complete status. If the eTMF PUBLISH or Artifact PUBLISH message type are enabled, the item’s status change triggers an eTMF PUBLISH or Artifact PUBLISH message.

You can view outbound messages on the Event Messages page, review them in detail, and retry them if necessary.

Event Messages page

You can access the Event Messages page to review API integration messages when you have a business role with View event messages permission. Successful messages remain in the database for 7 days, and Failed messages remain for 14 days, after which the messages are automatically removed from the database.

The Event Messages page provides multiple options to filter the message list. The default display when landing on the page is yesterday and today's messages, and you can update these date filters as necessary within the retention limits (7 or 14 days). You can also filter messages shown in the grid by searching for a text string or selecting an option from the Status, Type, and Endpoints drop-down lists.

At the top left of the message grid, you’ll see a message count reflecting the total messages available for display, with any filters applied.

The message grid, which features infinite scroll functionality, includes the following columns:

  • Created At: Message date and timestamp
  • Study Name: Study display name
  • Country: Country name
  • Site Number: Site number
  • Artifact: Placeholder name
  • Tries: Number of times the message has been tried (0-5)
  • API Status: Success (green), Failed (red), Trying (blue), Processing (blue) status badge
  • Message Type: eTMF Message, Milestone Message, Document Event, etc.
  • Actions: Retry button. The Retry button is active for messages in Success and Failed status and inactive for messages in Trying and Processing status.

Event Messages page

Click on a message’s linked Message Type (e.g., Document Event, Activity Change Message, eTMF Message, etc.) to open a drawer component from the right side of your screen. The message details (like the status badge, message GUID, endpoint address, etc.) show at the top of the drawer, followed by the message body (in formatted JSON), transformed message (if any), and response (if any).


Message detail drawer shows message body in formatted JSON

  • Access API documentation
    API documentation provides the message detail your organization will need for data integration with Oracle Site Activate.
  • View event messages
    Evaluate API message activity in the Event Messages area to see individual message detail and actions.
  • Retry a single failed event message
    Filter the event message list to quickly locate a single failed event message so that you can retry sending it.
  • Retry a successful event message
    Under certain circumstances, you may want to retry an event message that was originally successful. This procedure describes how you can optionally filter the event messages list to find the successful message.
  • Download event messages to CSV
    When you want to view event messages outside of the application, you can export the list to a comma separated values (.csv) format spreadsheet.
  • Create publishing endpoint with standard authentication
    When you create an endpoint with standard authentication type, it displays on the left side of the Publishing to an Outside API page, and the endpoint and "view" pop-in details are also available for selection on the Edit Study page.
  • Create publishing endpoint with basic authentication
    Using the steps in this procedure, you can quickly create a publishing endpoint with username and password authentication type.
  • Create publishing endpoint with OAuth 2.0 authentication
    Learn the steps required to create a publishing endpoint that uses the industry-standard OAuth 2.0 authentication method.
  • Edit an existing endpoint
    If you need to update attributes for an existing endpoint, use this procedure. When you finish making your updates, the endpoint details will be updated on the Edit Study page as well.
  • Delete an endpoint
    Sometimes you'll need to delete an endpoint so that it isn't available for selection. Use this procedure to ensure that messages stop flowing to the endpoint.
  • Configure custom eTMF attributes
    Create up to 10 custom fields to capture document data and send that data in an eTMF publish message.
  • Review files in IRB documents queue
    If you have a role that allows you to access the IRB approval documents queue, you can quickly evaluate files received via API from IRB integration partners.
  • Match an IRB file or add new item
    If you have a role that allows you to access the IRB approval documents queue, you can attempt to match a file in the queue to an existing placeholder item or add a new item if no match is found.