This section provides instructions for uploading batch files via the Accrual user interface. It also provides instructions for resolving any errors that may have occurred during the import process.
The batch upload feature enables you to submit accrual data for multiple subjects and one or more trials at a time rather than having to enter data for each subject/study individually.
Once you have been granted permission to submit accrual data, you can upload accrual data files singly as plain text files or in multiple text files that have been compressed into a Zip file. For instructions, refer to Requesting Permission to Submit Accrual Data and Preparing Accrual Batch Files.
Only Super Abstractors can upload accrual data batch files for CTEP and DCP trials. For these trials, the system assigns default patient disease codes if the disease code was not included in the batch file. The following table maps disease code systems to their default codes.
Disease Code System | Default Code Assigned |
---|---|
ICD-O-3 | C998 (site code) 7001 (histology code) |
ICD-9 | V100 |
ICD-10 | Z1000 |
SDC | 8000001 |
If a trial currently has no existing study subjects, and if all study subjects are missing the disease code in the CDUS file being submitted, the system assigns the CTEP SDC "disease not specified code, i.e., " 80000001, by default. The system cannot process files in which invalid study subject disease codes are provided.
Preparing CTRP Accrual Batch Files
Use the Batch File Utility as a guide
If you are new to the batch file creation process, you can use the CTRP Accrual Batch File Tool to get you started. With it you can produce properly-formatted batch files that you can upload in the Accrual application.
When you create a batch file, ensure that each data element conforms to the requirements:
- List each data element in its appropriate position in a given row
- Use the correct character cases (CAPITAL vs. lower case letters)
- Use the correct character lengths (number of characters allowed in a single field)
After you have prepared a batch file, you can upload it to CTRP. For instructions on submitting batch files, see Uploading Accrual Batch Data Files.
Accrual Batch File Data for Complete Trials
The CTRP Accrual Batch File conforms to the CDUS file specification, but it only uses a limited number of fields from that file. Data in the rest of the fields are ignored, but the place holders (commas) must still be present in the data file, whether empty or filled.
Before you begin
CTRP considers each accrual submitted as the total (cumulative) count to date. Be sure to read the information about accrual counts in Recording Participating Site Subject Accrual Counts.
Complete Trial Tables
Tables identify the record type for each record. The CTRP uses the following tables for complete trials.
Table Name | Number of CDUS Fields (Excluding the Table Name) | Number of Fields Used by CTRP (Excluding the Table Name) | Purpose |
---|---|---|---|
COLLECTIONS | 10 | 2 | Identifies the study for this data file |
PATIENTS | 23 | 12 | Subject-specific accrual data |
PATIENT_RACES | 3 | 3 | Subject's Race |
For a list of all the CDUS fields for these tables, refer to Comparison of CTRP and CDUS Accrual Data Elements.
Complete Trial Data Elements and Field Formats
Each row in a batch file is associated with a single record in the database. The first field in each line identifies the name of the table that a record belongs to. Subsequent fields contain different data element values for the same table. The number of fields required in each record, and the values they must contain, are provided in the Complete Trial Record Data Field Requirements table. Because many more elements are required in CDUS records than in CTRP records, many fields in your batch file will be null (contain no field values at all). In these cases, use a comma to indicate a field for which there is no datum.
If a comma is part of the value, enclose the fields in double quotes. Otherwise the use of double quotes is optional.
Complete Trial Data Record Formats
Each line of the data file contains one record, is prefixed by the table name, and is comma delimited.Important!
Use blank fields for those fields that are included in the CDUS standard but not used by the CTRP.
Valid Record Formats and Field Sequence
COLLECTIONS,<Study_Identifier>,,,,,,,,,<Change_Code>
PATIENTS,<Study_Identifier>,<Study_Subject_Identifier>,<Zip_Code>,<Country_Code>,<Birth_Date>,<Gender>,<Ethnicity>,<Payment_Method>,<Subject_Registration_Date>,<Registering_Group_Identifier>,<Study_Site_Identifier>,,,,,,,,,,<Subject_Disease_Code>,,
PATIENT_RACES,<Study_Identifier>,<Study_Subject_Identifier>,<Race>
The following is an example batch file for a study that has three study subjects, and one race per subject using CTRP accepted valid values. In the example below "Male", for example, is used instead of a CDUS accepted numeric value of "1".
Example Batch File
COLLECTIONS,"NCI-2011-03861",,,,,,,,,1
PATIENTS,"NCI-2011-03861",873222899999999,84124,,196311,Male,Unknown,Private Insurance,20060809,CALGB,149280,,,,,,,,,,238.7,,
PATIENTS,"NCI-2011-03861",8732228,84124,,196311,Male,Unknown,Private Insurance,20060809,CALGB,149280,,,,,,,,,,238.7,,
PATIENTS,"NCI-2011-03861",1,84124,,196311,Male,Unknown,Private Insurance,20060809,CALGB,149280,,,,,,,,,,185.0,,
"PATIENT_RACES","NCI-2011-03861",8732228,White
"PATIENT_RACES","NCI-2011-03861",873222899999999,Asian
"PATIENT_RACES","NCI-2011-03861",1,White
The following is another example batch file, accepted by CTRP, for the same study but using CDUS accepted numeric codes instead of the text values used in the example above .
Example Batch File
COLLECTIONS,"NCI-2011-03861",,,,,,,,,1
PATIENTS,"NCI-2011-03861",873222899999999,84124,,196311,1,9,1,20060809,CALGB,149280,,,,,,,,,,238.7,,
PATIENTS,"NCI-2011-03861",8732228,84124,,196311,1,9,1,20060809,CALGB,149280,,,,,,,,,,238.7,,
PATIENTS,"NCI-2011-03861",1,84124,,196311,1,9,1,20060809,CALGB,149280,,,,,,,,,,185.0,,
"PATIENT_RACES","NCI-2011-03861",8732228,01
"PATIENT_RACES","NCI-2011-03861",873222899999999,05
"PATIENT_RACES","NCI-2011-03861",1,01
Special Characters
If you include any of the following characters in a value, enclose the field with double quotes:
! " # $ % & ' ( ) * + , - . / : ; < > = ? @ [] \^ _{} | ~
If you enclose a field with double quotes (as in "NCI-2012-00225"), CTRP interprets the string inside the quote exactly as presented. If the field does not contain any special characters, the quote marks are optional.
ICD-O-3 Trial Format for Topography Codes
For trials using ICD-O-3 codes, use the Subject Disease Code position for ICD-O-3 Topography and Morphology (which must include Histology and Behavior codes). When you use both Topography and Morphology codes, separate them by a semi-colon as per the example below.Format: site code; histology codeCode: C64.9;8000/3
Examples:
SDC TopographyPATIENTS,"NCI-2011-03861",8732228,84124,,196311,1,9,1,20060809,CALGB,149280,,,,,,,,,,238.7,,
ICD-O-3 Topography and MorphologyPATIENTS,"NCI-2011-03861",8732228,84124,,196311,1,9,1,20060809,CALGB,149280,,,,,,,,,,C64.9;8000/3,,
Complete Trial Record Data Field Requirements
The tables in this section contain detailed information about each of the data elements included in the Batch Upload file. The CDUS Accepted Values are provided to show differences in case your system is already producing the CDUS file. In most cases, both CTRP and CDUS values are accepted.
Accrual Data Elements Table with CTRP-Accepted Values
Accrual Data Element Name | Mandatory=M; Optional=O Conditional = C | Definition | CTRP Accepted Values | Information Model Class / Diagram Mapping | Comments/Conditions |
---|---|---|---|---|---|
Study Identifier | M | Unique identifier assigned to the study | NCI, CTEP, or DCP Identifier | Study Protocol / assignedIdentfier | -- |
Study Subject Identifier | M | Unique identifier (numeric or alphanumeric) assigned to subjects in a study | Any numeric or alphanumeric value assigned to a study subject | Study Subject / identifier | -- |
ZIP Code | C | String of characters used to identify the five-digit Zone Improvement Plan (ZIP) code that represents the geographic segment that is a subunit of the ZIP code, assigned by the U.S. Postal Service to a geographic location to facilitate mail delivery. | 5 digit numeric ZIP code | Patient / postalAddress | Mandatory if patient’s Country of Residence is U.S. |
Country of Residence | C | For non-U.S. residents only. This should be used when patient participation from foreign countries is involved. For patients from outside the U.S., enter the foreign country code. Leave blank if the patient is a U.S. resident. CTRP is using the International Standards Organization country codes. Note: Either Zip code (if U.S resident) or country code (if not U.S resident) is mandatory. | 2-letter ISO Country Codes | Patient / postalAddress | Mandatory if not U.S. |
Patient’s Date of Birth | M | The month and year on which the person was born | YYYYMM | Patient / birthDate | Year and Month are mandatory. |
Gender of a Person | M | Text designations that identify gender. Gender is described as the assemblage of properties that distinguish people on the basis of their societal roles |
| Patient / sexCode | Identification of gender is based upon self-report and may come from a form, questionnaire, interview, etc. Genders in batch files do not have to correspond to the gender indicated as a trial eligibility criterion. |
Ethnicity | M | Text for reporting information about ethnicity based on the Office of Management and Budget (OMB) categories |
| Patient / ethnicGroupCode | -- |
Payment Method | O | Term for an entity, organization, government, corporation, health plan sponsor, or any other financial agent who pays a healthcare provider for the healthcare service rendered to a person or reimburses the cost of the healthcare service |
| StudySubject / paymentMethodCode | Payment Method Codes in batch files are not case-sensitive. |
Subject Registration Date | M | Date the subject was registered to the study | YYYYMMDD | PerformedSubjectMilestone / registrationDate | -- |
Registering Group Code | O | Unique CTEP Group code assigned to the group that originally registered the patient for the study | -- | StudySubject / registrationGroupId | For trials with Group participation, provide CTEP Group Code, if available |
Study Site Identifier | M | Unique identifier (PO ID) assigned to the institution accruing the patient to the study | CTRP Person/Organization ID (PO ID) | Study Site / identifier | -- |
Subject Disease Code
| M | Code that identifies a disease |
| For SDC Disease Code: StudySubject / diease_identifier For ICD-9 Disease Code: StudySubject / icd9diease_identifier | Disease code is mandatory for all trials except those managed by DCP PIO. Cancer specific ICD-9-CM disease codes in the range 140 to 239. Information about these disease codes is available at http://www.icd9data.com For trials using ICD-O-3 terminology, use this position for Site and Morphology (which must include Histology and Behavior Codes). When using both Site and Histology codes, separate them by a semicolon ( ; ). Site codes are available at https://codes.iarc.fr/usingicdo.php. For Disease Codes for disease not specified, healthy volunteers and donors see Disease Codes for Disease not Specified, Healthy Volunteers and Donors - Include v4.4 |
Race | M | Text for reporting information about race based on the Office of Management and Budget (OMB) categories |
| Patient / raceCode | Multiple races in batch files are permissible even if "Not Reported" or "Unknown" is indicated. |
Change Code | O | Additions or changes since the last report |
| AccrualCollections / changeCode | 1 or NULL = changes in the file; the CTRP system processes and saves the submission 2 = If the trial's current accrual is 0, the CTRP system processes the file as a Code 1 change. If the trial's current accrual is greater than 0, the system saves the file but does not process it. |
Accrual Data Elements Table with CDUS-Accepted Values
Accrual Data Element Name | Mandatory=M; Optional=O Conditional = C | Definition | CDUS Accepted Values | Comments/Conditions |
---|---|---|---|---|
Study Identifier | M | Unique identifier assigned to the study | CTEP Identifier | -- |
Study Subject Identifier | M | Unique identifier (numeric or alphanumeric) assigned to subjects in a study | Any numeric or alphanumeric value assigned to a study subject | -- |
ZIP Code | C | String of characters used to identify the five-digit Zone Improvement Plan (ZIP) code that represents the geographic segment that is a subunit of the ZIP code, assigned by the U.S. Postal Service to a geographic location to facilitate mail delivery. | 5 digit numeric ZIP code | Mandatory if patient’s Country of Residence is U.S. |
Country of Residence | C | For non-U.S. residents only. This should be used when patient participation from foreign countries is involved. For patients from outside the U.S., enter the foreign country code. Leave blank if the patient is a U.S. resident. CTRP is using the International Standards Organization country codes. Note: Either Zip code (if U.S resident) or country code (if not U.S resident) is mandatory. | 2-letter ISO Country Codes | Mandatory if not U.S. |
Patient’s Date of Birth | M | The month and year on which the person was born | YYYYMM | Year and Month are mandatory |
Study Subject Sex | M | Text designations that identify gender. Gender is described as the assemblage of properties that distinguish people on the basis of their societal roles |
| Identification of gender is based upon self-report and may come from a form, questionnaire, interview, etc. |
Ethnicity | M | Text for reporting information about ethnicity based on the Office of Management and Budget (OMB) categories |
| -- |
Subject Registration Date | M | Date the subject was registered to the study | YYYYMMDD | -- |
Study Site Identifier | M | Unique identifier (PO ID) assigned to the institution accruing the patient to the study | CTEP Site ID | -- |
Subject Disease Code | M | Code that identifies a disease |
| Disease code is mandatory for all trials except those managed by DCP PIO. Cancer specific ICD-9-CM disease codes in the range 140 to 239. Information about these disease codes is available at http://www.icd9data.com |
Race | M | Text for reporting information about race based on the Office of Management and Budget (OMB) categories |
| -- |
Change Code | O | Additions or changes since the last report | -- | -- |
Complete Trial Record Data Field Formats
Tables | Field (Field Position in a Row) | Format (Maximum Number of Characters) |
---|---|---|
COLLECTIONS | Study Identifier (2) | Text (35) |
COLLECTIONS | Change Code (11) | Number (1) |
PATIENTS | Study Identifier (2) | Text (35) |
PATIENTS | Study Subject Identifier (3) | Text (20) |
PATIENTS | ZIP Code (4) | Text (10) |
PATIENTS | Country of Residence (5) | Text (2) |
PATIENTS | Patient's Date of Birth (6) | Date (YYYYMM) |
PATIENTS | Gender of a Person (7) | Text (10) |
PATIENTS | Ethnicity (8) | Text (25) |
PATIENTS | Payment Method (9) | Text (50) |
PATIENTS | Subject Registration Date (10) | Date (YYYYMMDD) |
PATIENTS | Registering Group Identifier (11) | Text (25) |
PATIENTS | Study Site Identifier (12) | Text (25) |
PATIENTS | Subject Disease Code (22) 1 | Number (10) |
PATIENT_RACES | Study Identifier (2) | Text (35) |
PATIENT_RACES | Study Subject Identifier (3) | Text (20) |
PATIENT_RACES | Race (4) | Text (45) |
The relation between COLLECTIONS, PATIENTS, and PATIENT_RACES is that COLLECTIONS can have multiple PATIENTS, and PATIENTS can have multiple PATIENT_RACES. These relations are maintained through the use of consistent Study Identifier and Study Subject Identifier fields.
Using the format table, you can determine that you must enter the Patient's Date of Birth in the sixth position in a row in the PATIENTS table as YYYYMM. The following diagram contains a typical line of text from a batch file. Brackets with numbers indicate the field position number.
In the example above, the fifth field position (5) is null (blank) because it (Country of Residence) is a conditionally required field and in this example is not required.
___
- For trials using ICD-O-3 terminology, use this position for Site and/or Histology Codes. When using both Site and Histology codes, separate them by a semicolon ( ; ). ↩
Accrual Batch File Data for Abbreviated Trials
Abbreviated Studies in CTRP are those with the Data Table 4 trial submission category of Industrial. The CTRP requires users to submit accrual totals only for these trials. Do not submit subject-specific data. The CTRP Accrual Batch File uses the same file format as CDUS, but the fields are unique to CTRP.
Before you begin
The CTRP considers each accrual submitted as the total (cumulative) count to date. Be sure to read the information about accrual counts in Recording Participating Site Subject Accrual Counts.
Abbreviated Trial Tables
Table Name | Number of CDUS Fields (Excluding the Table Name) | Number of Fields Used by CTRP (Excluding the Table Name) | Purpose |
---|---|---|---|
COLLECTIONS | 10 | 1 | Identifies the study for this data file |
ACCRUAL_COUNT | (TBD: 0 or 1) | 4 | Aggregate accrual data |
Abbreviated Trial Data Record Formats
Abbreviated Trial Record Data Field Requirements
For field requirements, refer to the following pages:
Accrual Data Elements with CTRP-Accepted Values
Accrual Data Element Name | Mandatory=M; Optional=O Conditional = C | Definition | CTRP Accepted Values | Information Model Class / Diagram Mapping |
---|---|---|---|---|
Study Identifier | M | Unique identifier assigned to the study | NCI, CTEP, or DCP Identifier | Study Protocol / assignedIdentfier |
Study Site Identifier | M | Unique identifier (PO ID) assigned to the institution accruing the patient to the study | PO ID | Study Site / identifier |
Study Site Accrual Count | M | Numeric count of subjects accrued at a study site to date | Numeric | Study Site / subjectAccrualcount |
Cut-Off Date | O | The date from which the cumulative accrual count was calculated. | YYYYMMDD | (TBD) |
Accrual Data Elements with CDUS-Accepted Values
Accrual Data Element Name | Mandatory=M; Optional=O Conditional = C | Definition | CDUS Accepted Values |
---|---|---|---|
Study Identifier | M | Unique identifier assigned to the study | CTEP Identifier |
Study Site Identifier | M | Unique identifier (PO ID) assigned to the institution accruing the patient to the study | CTEP Site ID |
Study Site Accrual Count | M | N/A | -- |
Cut-Off Date | O | The date from which the cumulative accrual count was calculated. | (TBD) |
Abbreviated Trial Data Field Requirements
Tables | Field (Field Position in a Row) | Format (Maximum Number of Characters) |
---|---|---|
COLLECTIONS | Study Identifier (2) | Text (35) |
ACCRUAL_COUNT | Study Identifier (2) | Text (35) |
ACCRUAL_COUNT | Study Site Identifier (3) | Text (25) |
ACCRUAL_COUNT | Study Site Accrual Count (4) | Text (10) |
The COLLECTIONS and ACCRUAL_COUNT tables are linked by consistent Study Identifier and Study Site Identifier fields. There is no limit to the number of ACCRUAL_COUNT records.
Uploading Accrual Batch Files
Be sure to complete your batch file preparation first
Before you begin, gather all the protocol data you need. See Preparing CTRP Accrual Batch Files for instructions. The system logs you out if it detects that you have not used the application for 90 minutes.
The system locks you out after three unsuccessful attempts to log in within 24 hours. In the event that you have been locked out of your account, contact us at ctrp_support@nih.gov. If you have forgotten your password, or if you want to reset it for any reason, refer to Resetting Your Password.
Once you have created your Accrual Batch Upload file, upload it via the CTRP Accrual web interface. Existing accrual data for the study will be updated and any new data you submit will be added.
The batch upload template currently does NOT provide a way to enter accrual disease code terminology; instead, the default value of SDC is used.
The batch files you submit do not delete previously accrued patients/patient data. Use the Accrual application user interface to delete accrued subjects as necessary.
How to Upload Accrual Batch Files
- On the toolbar, click Batch Upload
The Batch Upload page appears.
Click Browse and select the .txt or .zip file that contains your accrual data.
Click Submit.
Your file is uploaded to the system and processed in the backgroundWhen processing has been completed, the system sends you an email message to inform you of the status of your file(s). It includes the information listed below. The system will also notify you if it is unable to process your Zip file.
- NCI Identifier
- Number of subject accruals that the system imported
- Details of any errors that may have occurred during the import process
The system checks your submissions to ensure there are no duplicates. The system does not process a study subject record if it detects that a participating site in the same trial has registered a subject with the same Study Subject ID. The system includes details about which Study Subject IDs are affected in an error message.
A subject is duplicate if
1. There is already an accrual with same subject id on the same PS for a trial.
2. If following attributes (subject id, dob, gender, ethnicity) match for a subject on any other PS on the trial(not including the PS accrual is added to).
Once you have uploaded your batch file, the CTRP system continues to update the record status both by email and Accrual. To view the information you uploaded, see Downloading Accrual Batch Data Files and Reviewing and Updating Prior Accrual Submissions.
Resolving Accrual Batch File Upload Errors
If the email notice you received after uploading a batch file indicated that errors occurred during the the import process, you can use the following steps to correct them before re-submitting your accruals batch file.
If the batch (.zip) file contains both valid (error-free) and invalid files, the system processes the valid files and notifies you about the files that it could not process.
If the CTRP system was unable to identify an organization that you submitted in your batch file, it determines if the organization was nullified and merged with another organization. If so, the system includes the new organization name in the error message.
For Super Abstractors
If a CDUS batch file contains accruals for sites that have not been added yet to the trial in the CTRP, the system processes the valid sites and then emails you a list of participating sites from your file that are missing in the CTRP. You can correct this type of error by adding the site(s) to the trial and resubmitting the accrual batch file.
How to Resolve Accrual Batch File Upload Errors
- Go through the list of errors described in detail in the status email you received for each line in your text file that caused the error.
- Correct the errors.
- Save the file and re-submit.