REST API for Oracle Healthcare Translational Research

Create Export Definition

post

/HSDataService-web/api/3.2.0/exports

This endpoint supports the creation of Export Definition by Query Name, Study Names and other inputs.

Request

Supported Media Types

application/json
application/xml

Body Parameter

Root Schema : OmicsExportDefinition

Type: object

Properties

alignmentId: Type: integer (int64)

Required: true

Alignment id.

Example: "alignmentId": 1
allDataOption: Type: boolean

Default Value: false

Export definition must have either allDataOption or genomicPosition/bedFileNameUploadService or set of genes (geneHugoNames, pathwayNames, geneSetIds).

Example: false
anatomicalSiteCodes: Type: array anatomicalSiteCodes

List of anatomical site codes.
bedFileNameUploadService: Type: string

BED file contains genomic positions. Can be specified as {bucket name}/{object name} or {file name}. Export definition must have either allDataOption or genomicPosition/bedFileNameUploadService or set of genes (geneHugoNames, pathwayNames, geneSetIds).

Example: BedFileBucket/BedFileObjectName or BedFileName.txt
context: Type: string

Required: true

Sets the context as Patient or Subject.

Example: PATIENT or SUBJECT
fileWids: Type: array fileWids

List of file load record ids.
geneHugoNames: Type: array geneHugoNames

List of gene hugo names. Export definition must have either allDataOption or genomicPosition/bedFileNameUploadService or set of genes (geneHugoNames, pathwayNames, geneSetIds).
geneSetIds: Type: array geneSetIds

List of gene set ids. Export definition must have either allDataOption or genomicPosition/bedFileNameUploadService or set of genes (geneHugoNames, pathwayNames, geneSetIds).
genomicPosition: Type: array genomicPosition

Genomic positions. CHROMOSOME ID, START POSITION, END POSITION. START POSITION, END POSITION are optional. Can be sourced from Gene reference APIs or Genomic position APIs. Export definition must have either allDataOption or genomicPosition/bedFileNameUploadService or set of genes (geneHugoNames, pathwayNames, geneSetIds).
id: Type: object OdbIdentifier

Identifier assigned by a given system
link: Type: string

A link containing href to submit the file export job

Example: {rel: 'submit',href: '/exports/{exportId}/jobs'}
pathwayNames: Type: array pathwayNames

List of pathway names. Export definition must have either allDataOption or genomicPosition/bedFileNameUploadService or set of genes (geneHugoNames, pathwayNames, geneSetIds).
patientSubjectCohortListId: Type: integer (int64)

Record id of a saved list of patients or subjects. The export definition must have either a source of patients/subjects or a source of specimens. If both are provided the specimen source takes precedence

Example: "patientSubjectCohortListId": 10000000635009
patientSubjectId: Type: array patientSubjectId

List of patient or subject record ids. The export definition must have either a source of patients/subjects or a source of specimens. If both are provided the specimen source takes precedence
queryCriteria: Type: object OracleDBQueryDS

Contains all the Query Criteria
queryCriteriaJson: Type: string

Used to transfer query criteria JSON representation from web layer to ejb layer so the JSON can be persisted to support the Retrieve Export Definition API's the @GET export definition API's will return the JSON bound to this property as well as queryCriteria
queryName: Type: string

Cohort Explorer Query Name. The export definition must have either a source of patients/subjects or a source of specimens. If both are provided the specimen source takes precedence

Example: "queryName" : "Variant_multipleRegions"
serviceProviderIdentifier: Type: string

The service provider identifier (a.k.a. namespace) to be used to find alias values.

Example: "serviceProviderIdentifier": "vcf"
specimenIdsCdm: Type: array specimenIdsCdm

List of specimen ids from CDM schema. The export definition must have either a source of patients/subjects or a source of specimens. If both are provided the specimen source takes precedence
specimenIdsOdb: Type: array specimenIdsOdb

List of specimen ids from ODB schema. The export definition must have either a source of patients/subjects or a source of specimens. If both are provided the specimen source takes precedence
specimenTypeCodes: Type: array specimenTypeCodes

List of specimen type codes.
studyNames: Type: array studyNames

List of study names.

Nested Schema : anatomicalSiteCodes

Type: array

List of anatomical site codes.

Example

"anatomicalSiteCodes": ["SPCMN_ANA_SITE_CD_CODE_7", "SPCMN_ANA_SITE_CD_CODE_4"]

Items

Type: string

Nested Schema : fileWids

Type: array

List of file load record ids.

Example

"fileWids" : [1,2]

Items

Type: integer (int64)

Nested Schema : geneHugoNames

Type: array

List of gene hugo names. Export definition must have either allDataOption or genomicPosition/bedFileNameUploadService or set of genes (geneHugoNames, pathwayNames, geneSetIds).

Example

"geneHugoNames": ["CASZ1","CAMTA1-IT1","RP3-453P22.2"]

Items

Type: string

Nested Schema : geneSetIds

Type: array

List of gene set ids. Export definition must have either allDataOption or genomicPosition/bedFileNameUploadService or set of genes (geneHugoNames, pathwayNames, geneSetIds).

Example

"geneSetIds" : [1,2]

Items

Type: integer (int64)

Nested Schema : genomicPosition

Type: array

Genomic positions. CHROMOSOME ID, START POSITION, END POSITION. START POSITION, END POSITION are optional. Can be sourced from Gene reference APIs or Genomic position APIs. Export definition must have either allDataOption or genomicPosition/bedFileNameUploadService or set of genes (geneHugoNames, pathwayNames, geneSetIds).

Example

"genomicPosition": [{
        "chromosomeId": 10,
        "startPosition": 89682891,
        "endPosition": 100682893
    }, {
        "chromosomeId": 7,
        "startPosition": 89682891
    }, {
        "chromosomeId": 5
    }]

Items

Type: object GenomicPositionFileExport

Nested Schema : OdbIdentifier

Type: object

Identifier assigned by a given system

Properties

system: Type: string

System which assigned this identifier
value: Type: string

Identifier value

Nested Schema : pathwayNames

Type: array

List of pathway names. Export definition must have either allDataOption or genomicPosition/bedFileNameUploadService or set of genes (geneHugoNames, pathwayNames, geneSetIds).

Example

"pathwayNames": ["PATHWAY1","PATHWAY2"]

Items

Type: string

Nested Schema : patientSubjectId

Type: array

List of patient or subject record ids. The export definition must have either a source of patients/subjects or a source of specimens. If both are provided the specimen source takes precedence

Example

"patientSubjectId" : [1,2]

Items

Type: integer (int64)

Nested Schema : OracleDBQueryDS

Type: object

Contains all the Query Criteria

Properties

allCriteriaList: Type: array allCriteriaList

Required: true

Minimum Number of Items: 1

Maximum Number of Items: 2147483647

List of Criteria Eg.DemographicsCriteria,MedicationCriteria,DiagnosisCriteria,SequenceVariantsCriteria,ConsentCriteria,DiagnosisCriteria,EncounterCriteria,ObservationCriteria,HistoryCriteria,ProceduresCriteria,SpecimenCriteria,StudyCriteria,MicroarrayExpressionCriteria,RNASeqExpressionCriteria,CopyNumberVariationCriteria,RelativeTimeEventsCriteria

Nested Schema : specimenIdsCdm

Type: array

List of specimen ids from CDM schema. The export definition must have either a source of patients/subjects or a source of specimens. If both are provided the specimen source takes precedence

Example

"specimenIdsCdm" : [1,2]

Items

Type: integer (int64)

Nested Schema : specimenIdsOdb

Type: array

List of specimen ids from ODB schema. The export definition must have either a source of patients/subjects or a source of specimens. If both are provided the specimen source takes precedence

Example

"specimenIdsOdb" : [1,2]

Items

Type: integer (int64)

Nested Schema : specimenTypeCodes

Type: array

List of specimen type codes.

Example

"specimenTypeCodes": ["SPCMN_TYP_CD_FECAL", "SPCMN_TYP_CD_URNE"]

Items

Type: string

Nested Schema : studyNames

Type: array

List of study names.

Example

"studyNames": ["STUDY1","STUDY2"]

Items

Type: string

Nested Schema : GenomicPositionFileExport

Type: object

Properties

chromosomeId: Type: integer (int64)

Record identifier of the chromosome.
endPosition: Type: integer (int64)

Optional. End location of sequence
startPosition: Type: integer (int64)

Optional. Start location of sequence

Nested Schema : allCriteriaList

Type: array

Minimum Number of Items: 1

Maximum Number of Items: 2147483647

List of Criteria Eg.DemographicsCriteria,MedicationCriteria,DiagnosisCriteria,SequenceVariantsCriteria,ConsentCriteria,DiagnosisCriteria,EncounterCriteria,ObservationCriteria,HistoryCriteria,ProceduresCriteria,SpecimenCriteria,StudyCriteria,MicroarrayExpressionCriteria,RNASeqExpressionCriteria,CopyNumberVariationCriteria,RelativeTimeEventsCriteria

Items

Type: object criteria

Discriminator: type

Nested Schema : criteria

Type: object

Discriminator: type

Properties

exclude: Type: boolean

Default Value: false

Response

Supported Media Types

application/json
application/xml

200 Response

successful operation

Body

Root Schema : FileExportDefResponse

Type: object

Properties

bedFileParsingErrors: Type: array bedFileParsingErrors

Will appear if bedFileNameUploadService is input and there are errors.
exportDefId: Type: object Identifier

Identifier assigned by a given system
link: Type: string

A link containing href to submit the file export job

Example: {rel: 'submit',href: '/exports/{exportId}/jobs'}

Nested Schema : bedFileParsingErrors

Type: array

Will appear if bedFileNameUploadService is input and there are errors.

Example

"bedFileParsingErrors": [
    "Problem converting line 15 from BED file /u01/app/file_uploads/BedFileReaderUtilTest.txt to valid name, start position, end position.",
    "Problem converting line 18 from BED file /u01/app/file_uploads/BedFileReaderUtilTest.txt to valid name, start position, end position.",
    "Problem converting line 19 from BED file /u01/app/file_uploads/BedFileReaderUtilTest.txt to valid name, start position, end position.",
    "For bed file [/u01/app/file_uploads/BedFileReaderUtilTest.txt] cannot find chromosome id for chromosome names [12345 CHR ]"
  ]

Items

Type: string

Nested Schema : Identifier

Type: object

Identifier assigned by a given system

Properties

system: Type: string

System which assigned this identifier
value: Type: string

Identifier value

Examples

The following example submits a POST request. See the Criteria Classes for this endpoint.

API URL

http://localhost:7001/HSDataService-web/api/3.2.0/exports

Example 1 of Request Body — (List of genomicPosition, serviceProviderIdentifier, patientSubjectCohortListId, anatomicalSiteCodes, specimenTypeCodes)

{
    "context": "SUBJECT",
    "genomicPosition": [{
        "chromosomeId": 10,
        "startPosition": 89682891,
        "endPosition": 100682893
    }, {
        "chromosomeId": 7,
        "startPosition": 89682891
    }, {
        "chromosomeId": 5
    }],
    "alignmentId": 1,
    "serviceProviderIdentifier": "vcf",
    "patientSubjectCohortListId": 10000000635009,
    "anatomicalSiteCodes": ["SPCMN_ANA_SITE_CD_CODE_7", "SPCMN_ANA_SITE_CD_CODE_4"],
    "specimenTypeCodes": ["SPCMN_TYP_CD_FECAL", "SPCMN_TYP_CD_URNE"]
}

Example 2 of Request Body — (queryCriteria with a single geneHugoNames item)

{
    "context": "patient",
    "geneHugoNames": ["CASZ1"],
    "alignmentId": 1,
    "queryCriteria": {
        "allCriteriaList": [{
            "type": "DemographicsCriteria",
            "patientIdList": ["1", "2"],
            "ageRange": {
                "value": 60,
                "secondValue": 80,
                "op": {
                    "code": "COMP_OP_BETWEEN"
                }
            }
        }, {
            "type": "DiagnosisCriteria",
            "diagnosisNameList": ["D1", "D2"],
            "onsetDateRange": {
                "value": "01/30/2016",
                "secondValue": "01/30/2017",
                "op": {
                    "code": "COMP_OP_BETWEEN"
                }
            }
        }]
    }
}

Example 3 of Request Body — (queryName with geneHugoNames)

{
  "context" : "patient",
  "alignmentId" : 1,
  "geneHugoNames": ["CASZ1","CAMTA1-IT1","RP3-453P22.2"],
  "queryName" : "Variant_multipleRegions"
}

Example 4 of Request Body — (bedFileNameUploadService with {bucket name}/{object name} format)

{
  "context" : "patient",
  "alignmentId" : 1,
  "specimenIdsOdb" : [63],
  "bedFileNameUploadService" : "julian-test/julian-chrMT-test.txt"
}

Example 5 of Request Body — (bedFileNameUploadService with {file name} format)

{
  "context" : "patient",
  "alignmentId" : 1,
  "specimenIdsOdb" : [63],
  "bedFileNameUploadService" : "julian-chrMT-test.txt"
}

Example 6 of Request Body — (patientSubjectId with allDataOption)

{
  "context" : "patient",
  "alignmentId" : 1,
  "patientSubjectId" : [1,2],
  "allDataOption" : true
}

Example of Response Body

The following example shows the response in JSON format.

{
  "exportDefId": {
    "system": "ODB",
    "value": "10605"
  },
    "link": {
    "rel": "SUBMITJOB",
    "href": "/HSDataService-web/api/3.2.0/exports/10605/jobs"
  }
}

Example of Request Body — (with bedFileParsingErrors)

The following example shows the response in JSON format.

Note:

bedFileParsingErrors will only appear if bedFileNameUploadService is input and there are errors.

{
  "exportDefId": {
    "system": "ODB",
    "value": "10605"
  },
  "bedFileParsingErrors": [
    "Problem converting line 15 from BED file /u01/app/file_uploads/BedFileReaderUtilTest.txt to valid name, start position, end position.",
    "Problem converting line 18 from BED file /u01/app/file_uploads/BedFileReaderUtilTest.txt to valid name, start position, end position.",
    "Problem converting line 19 from BED file /u01/app/file_uploads/BedFileReaderUtilTest.txt to valid name, start position, end position.",
    "For bed file [/u01/app/file_uploads/BedFileReaderUtilTest.txt] cannot find chromosome id for chromosome names [12345 CHR ]"
  ],
  "link": {
    "rel": "SUBMITJOB",
    "href": "/HSDataService-web/api/3.2.0/exports/10605/jobs"
  }
}