Genome File Based Jobs

Genome file based jobs are jobs to generate different reports and their PDFs, that require a genome file to be uploaded.

Before generating a job, you need to create a profile for which you intend to generate the job for and to whom the genome file belongs to. To do so, please refer to the POST /profile/ endpoint.

Once you have your profile generated, and have acquired its profile_id, the next step is to create the desired job.

There are 6 genome file based jobs available over the SD API:

Jobs	Endpoint to Create Job
Report Job (for health reports)	POST /report-job/
Ancestry Job (for ancestry related reports)	POST /ancestry-job/
PGx Job (for Pharmacogenomic report)	POST /pgx-job/
Longevity Screener Job (for Longevity Screener report)	POST /longevity-screener-job/
BioChemistry Job (for Methylation report)	POST /bio-chemistry-job/
Clinical Overview Job (for Clinical Overview report)	POST /clinical-overview-job/

Each job allows

1. generating report
2. generating report + generating PDF for that report

In a single request, you can either just generate the desired report, or generate the PDF along with the report. You can control the desired end state through the desired_status field at the time of creating the job.

Valid options for desired_status are:

1. report_generated (would only generate the report)
2. pdf_generated (would generate the report + report PDF)

Creating a Job for the First Time - Uploading + Processing Genome File

If you're generating a genome file based job for the first time against a new profile, you need to go through an extra step of uploading + processing the genome file for the new profile. This step would be required only once per profile, allowing you to create as many subsequent jobs of any type for the said profile. Accepted DNA file formats are listed here.

The steps to upload a genome file are given below.

1. Call the /genome-file/upload-file endpoint. This will return a presigned POST URL to s3 with authentication fields and a file_id.

   📘

   The fields returned in the response are dependent on AWS and should be treated like a dictionary that is subject to change without notice. See example below to understand how to use it for a subsequent request.

   The file_id returned from the response is not your genome file ID. It is a temporary ID to identify the uploaded file. A genome file is created either on successful POST to /{job-type}-job/ with said file_id, e.g. if you're creating a report job, it would be POST /report-job/, or successful POST to /genome-file-job/ with said file_id (refer to 2nd point below).

   Note: File IDs will expire after a couple of hours.

   Refer to first example below to get a better idea on how to upload the file to s3.

2. After completing the file upload, you can:
   1. Either include the file_id directly in the payload when creating the desired job (POST /{job-type}-job/), e.g. POST /report-job/ as shown in the example below. This would trigger the genome file processing.
   2. Or first create a genome-file-job using the Genome File Job API, and pass the file_id in the payload for that job, which is specifically for genome file processing and tracking. You don't have to wait for file processing to finish. You can create a job of your choice like report-job after having created the genome-file-job , but this time, the subsequent job will be created without file_id, as you've already provided file_id in the genome-file-job which has already initiated file processing.

Examples:

Python example code to upload file to s3 + create a report job with file_id to trigger genome file processing.

Python

import requests

headers = {"Authorization": "Token XYZ"}
base_url = "https://qa-b2b.selfdecode.com/service/b2b-integrations/"

# Step 1: Upload your DNA file to s3

# get presgined POST url
response = requests.post(base_url + "genome-file/upload-file/", headers=headers, timeout=30).json()
url, fields, file_id = response["url"], response["fields"], response["file_id"]
file_path = "genome_file.txt"

# upload file to s3, assuming your file is named "genome_file.txt" and placed in the same directory as this Python module
with open(file_path, "rb") as f:
    files = {"file": ("genome_file.txt", f)}
    requests.post(url, data=fields, files=files, timeout=60)

# Step 2: Trigger your genome file processing, by passing the `file_id` to the first job you create.

# generate report job with file_id
# base payload would vary based on the type of job
# refer to the relevant job's API doc to get a list of fields for the payload
# this is a sample payload specifically for POST /report-job/
base_payload = {
  "profile_id": "1ca85f64-5717-4562-b3fc-2c963f66afa6",
  "report_id": "ff4f5b07-89fe-4a02-a151-60ff0de8b721",
  "file_id": file_id,
  "desired_status": "pdf_generated",
}
response = requests.post(base_url + "report-job/", headers=headers, json=base_payload)

POST https://selfdecode.com/service/b2b-integrations/{job-type}-job/

Payload to generate only report sans PDF

JSON

{
  "profile_id": "1ca85f64-5717-4562-b3fc-2c963f66afa6",
  "file_id": "162357df-e111-4792-8c42-6369d43d52fd", // only for first job
  "desired_status": "report_generated",
  ...  // any other fields specific to job type
}

Payload to generate report + PDF

JSON

{
  "profile_id": "1ca85f64-5717-4562-b3fc-2c963f66afa6",
  "file_id": "162357df-e111-4792-8c42-6369d43d52fd", //only for first job
  "desired_status": "pdf_generated",
  "pdf_config": {
    "lang": "es",
    ... // any other PDF configs specific to job type and customization needs
  },
  "pdf_file_name": "John Doe PDF",
  ... // any other fields specific to job type
}

Fetching Jobs

List

GET /{job-type}-job/ supports listing by parameters: profile_id, status. Refer to individual job type's API docs for any additional query parameters.

Retrieve

Individual jobs can be retrieved by their job ID at GET {job-type}-job/:job_id. The job ID can be obtained from the response of either the create or list endpoint.

Completion of Job

Upon fetching the job, if the actual status returned in the response is equal to the desired_status at the time of job creation, the report job is finished and the report has been successfully generated.

If you're interested in downloading the PDF of the generated report, refer to the section below.

Acquiring PDFs

Downloading

Please refer to Acquiring PDFs.

Configuration

You can customise the PDFs according to your needs, by passing in certain supported configurations in the pdf_config field at the time of job creation, as shown in the example payload above.

For PDF configurations of all genome file based jobs, refer here. Additionally, see Report PDF Configurations for report jobs.