NIH | National Cancer Institute | NCI Wiki  

Versions Compared

Old Version 1

changes.mady.by.user Anonymous

Saved on

compared with

New Version 2

changes.mady.by.user Frost, Ruth (NIH/NCI) [C]

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: Replaced contents with Include Page macro pointing to versioned include page with same contents.

...

width 40%
Panel
title Topic Links

Table of Contents
maxLevel 4
minLevel 2

...

Include Page

NCI CTRP Accrual REST Service Guide v4.4

Introduction

The Accrual REST Service is a CTRP Web Service that provides the following operations in a REST-like fashion:

  • Add or update trial subject accrual information on a given participating site
  • Delete specific trial subject accrual information from a given participating site
  • Submit accrual count for a participating site in an Abbreviated trial

...

Service Endpoints

Multiexcerpt

Inside the NIH Firewall (VPN required)

Outside of the NIH Firewall

Access Requirements

Multiexcerpt
To use the service, you must have a valid NCI LDAP account and a Creating New NCI CTRP User Accounts. All service endpoints require HTTP Basic authentication with your NCI LDAP username and password.

XML Schema

Multiexcerpt

The service uses XML for data exchange. All XML elements going in or out of the service are defined and validated against the following XML schema:

accrual_ws.xsd

The XML schema is well-annotated with inline documentation that explains the purpose and meaning of various elements, types, and attributes. Specific elements required for service operations are explained in the sections below.

API Specification

Add/Update Subject (Patient) Accruals

Description

This operation submits subject (patient) accrual information for a specific participating site on a trial. If the subject accrual record already exists for the specified study and participating site, this operation will update that record accordingly. If you submit multiple subject accrual records all with the same subject ID within the same request, the last record in the list will supplant the others. The submitter must have accrual access to the site.

HTTP Method

PUT

URL

Three options are available:

  1. /sites/{id}
    1. {id}. CTRP numeric identifier of a participating site
  2. /trials/{idType}/{trialID}/sites/po/{id}
    1. {idType}. Type of identifier you want to use to identify a trial in CTRP. Possible values: pa, nci, ctep, dcp.
    2. {trialID}. Trial identifier value itself

    3. {id}. PO identifier of the organization that is the site on the trial

  3. /trials/{idType}/{trialID}/sites/ctep/{id}
    1. {idType}. Type of identifier you want to use to identify a trial in CTRP. Possible values: pa, nci, ctep, dcp.
    2. {trialID}. Trial identifier value itself

    3. {id}. CTEP identifier of the organization that is the site on the trial

Request Body

XML document with studySubjects root element (see XML Schema). MIME Type: application/xml.

Response Body

None (if successful) or an error message. MIME Type: text/plain.

HTTP Response Codes

CodeResponse
200Success
400Validation error
404Participating site not found
500Internal server error

Examples

URL: https://trials-dev.nci.nih.gov/accrual-services/sites/121787425

Request XML:

The following XML request shows an example for submitting 5 study subjects to site 121787425 using ICD9 for disease codes. Note that the “siteDisease codeSystem” is not required since the disease code used is ICD9.

...

language html/xml
theme Eclipse
collapse true

Request XML (Specifying Disease and Site Disease codes using ICD-O-3)

The following XML request shows an example for submitting one study subject to site 121787425 using ICD-O-3 for the disease code. Note that when the disease <codeSystem> = “ICD-O-3”, either the <disease> or the <siteDisease> is mandatory.

...

language html/xml
theme Eclipse
collapse true

Request XML (Specifying Disease and Site Disease codes using Legacy Codes - CTEP)

The following XML request shows an example for submitting one study subject to site 121787425 using Legacy Codes - CTEP for the disease code.

...

language html/xml
theme Eclipse
collapse true 
 

Update Accrual Count

Description

This operation updates accrual counts for a participating site on an Abbreviated (Industrial) trial.

HTTP Method

PUT

URL

Three options are available:

  1. /sites/{siteID}/count
    1. {siteID}. CTRP numeric identifier of a participating site
  2. /trials/{idType}/{trialID}/sites/po/{poid}/count
    1. {idType}. Type of identifier you want to use to identify a trial in CTRP. Possible values: pa, nci, ctep, dcp.
    2. {trialID}. Trial identifier value itself.

    3. {poid}. PO identifier of the organization that is the site on the trial.

  3. /trials/{idType}/{trialID}/sites/ctep/{id}/count
    1. {idType}. Type of identifier you want to use to identify a trial in CTRP. Possible values: pa, nci, ctep, dcp.
    2. {trialID}. Trial identifier value itself.

    3. {id}. CTEP identifier of the organization that is the site on the trial.

Request Body

Non-negative numeric accrual count. MIME Type: text/plain.

Response Body

None (if successful) or an error message. MIME Type: text/plain.

HTTP Response Codes

CodeResponse
200Success
400Validation error
401Authentication/Authorization Failure: invalid username/password or insufficient permissions to access the service
404Participating site/study subject not found
500Internal server error (includes the condition of updating/deleting a study subject that you don't have accrual access to)

Examples

URL: https://trials-dev.nci.nih.gov/accrual-services/trials/nci/NCI-2013-01840/sites/po/12733422/count

Request:

...

language none
theme Eclipse

Delete Study Subject

Description

Deletes specific study subject (patient) accrual information from a participating site.

HTTP Method

DELETE

URL

Three options are available:

  1. /sites/{siteID}/subjects/{subjectID}
    1. {siteID}. CTRP numeric identifier of a participating site
    2. {subjectID}. Study subject identifier
  2. /trials/{idType}/{trialID}/sites/po/{poid}/subjects/{subjectID}
    1. {idType}. Type of identifier you want to use to identify a trial in CTRP. Possible values: pa, nci, ctep, dcp.
    2. {trialID}. Trial identifier value itself

    3. {poid}. PO identifier of the organization that is the site on the trial

    4. {subjectID}. Study subject identifier
  3. /trials/{idType}/{trialID}/sites/ctep/{ctepID}/subjects/{subjectID}
    1. {idType}. Type of identifier you want to use to identify a trial in CTRP. Possible values: pa, nci, ctep, dcp .
    2. {trialID}. Trial identifier value itself

    3. {ctepID}. CTEP identifier of the organization that is the site on the trial

    4. {subjectID}. Study subject identifier

Request Body

NONE

Response Body

None (if successful) or an error message. MIME Type: text/plain.

HTTP Response Codes

Code Response
200Success
400Validation error
404Study subject not found
500Internal server error

Examples

URL: https://trials.nci.nih.gov/accrual-services/trials/nci/NCI-2014-00233/sites/po/12733422/subjects/SU001

Submit CDUS Batch File for Asynchronous Processing

Description 

With this operation, you can upload a CDUS batch file. The system processes this file asynchronously and sends the results of processing by email to the submitting user.

HTTP Method 

Post

URL

/batch

Request Body

XML document with batchFile root element.

Response Body

None (if successful) or an error message. MIME Type: text/plain.

Example

URL: https://trials.nci.nih.gov/accrual-services/batch

Content-Type: application/xml

Accept: application/xml

Body:

In this example, consider the following CDUS Accrual information for a typical CDUS Accrual file:

...

How to Construct the Body:

...

Insert the Base64 encoded text between <batchFile xmlns="gov.nih.nci.accrual.webservices.types"> and </batchFile> tags, as follows:

...

NCI CTRP Accrual REST Service Guide v4.4