Generating CSV Reports

info

This REST API documentation is effective as of 21:00 EST, 2 April, 2023.

Request

To begin, queue the CSV document. Be sure your request is formatted as follows:

• Use your work token as the Authorization value.

• Pass in a JSON-formatted string:

  • "ou" id must be passed in at the root

  • "template" value must be "adherence_csv"

  • "params" will have a new attribute called "scope" that must be set as "ou", and you must also pass in the value of the "ou" itself

    {
      "ou": "e9184ef4-296e-485c-872a-585a8c8352aa",
      "template": "adherence_csv",
      "params": {
        "scope": "ou",
        "ou": "e9184ef4-296e-485c-872a-585a8c8352aa"
      }
    }

The complete request should be formatted as follows:

curl 'https://report.app.certiscan.cloud/api/v1/document/report/' \
-H 'Accept: application/JSON' \
-H 'Content-Type: application/json;charset=utf-8' \
-H 'Authorization: Bearer Eyc1ffs9my3Vaki8f4YUujcMSd94qbG-LtdPMcF6PfE.Im88VL5toXcwjiKKoqfnIOg7wQtt_eugU6Gn1J3vPoE' \
--data-raw '{"ou": "e9184ef4-296e-485c-872a-585a8c8352aa", "template":"adherence_csv","params":{"scope": "ou", "ou":"e9184ef4-296e-485c-872a-585a8c8352aa"}}'

Response

A successful result will be similar to this:

{
  "success": true,
  "result": {
    "url": "https://report.app.certiscan.cloud/api/v1/document/report/290b849c-4e2a-4136-9247-6b22abb698ca/",
    "id": "290b849c-4e2a-4136-9247-6b22abb698ca",
    "name": "<project_name> - All Patients 2023-04-03T18:35:14+00:00.Z",
    "ou": "e9184ef4-296e-485c-872a-585a8c8352aa",
    "template": "adherence_csv",
    "scheduled": null,
    "state": "PENDING",
    "params": {
      "scope": "ou",
      "ou": "e9184ef4-296e-485c-872a-585a8c8352aa"
    },
    "download": null,
    "created": "2023-04-03T18:35:14.202800Z",
    "updated": "2023-04-03T18:35:14.202818Z",
    "audit": "6f50e6e8-21e6-4e3d-8395-2bd265b62ef5"
  }
}

Notice that the state of the report is "PENDING". Depending on the load of the services and the amount of dose data to process, the CSV file will be generated within 3 to 10 seconds.

When you query the result URL from above and the state of the report is “SUCCESS”, the file is ready, and you can retrieve it by using the "download" path. That authenticated response will be an HTTP 301 redirect:

{
  "success": true,
  "result": {
    "url": "https://report.app.certiscan.cloud/api/v1/document/report/290b849c-4e2a-4136-9247-6b22abb698ca/",
    "id": "290b849c-4e2a-4136-9247-6b22abb698ca",
    "name": "<project_name> - All Patients 2023-04-03T18:35:14+00:00.Z",
    "ou": "e9184ef4-296e-485c-872a-585a8c8352aa",
    "template": "adherence_csv",
    "scheduled": null,
    "state": "SUCCESS",
    "params": {
      "ou": "e9184ef4-296e-485c-872a-585a8c8352aa",
      "scope": "ou"
    },
    "download": "/api/document/download/290b849c-4e2a-4136-9247-6b22abb698ca",
    "created": "2023-04-03T18:36:11.084332Z",
    "updated": "2023-04-03T18:36:13.814954Z"
  }
}

CSV File Format

File Name

The CSV file name will be <project_name> - All Patients YYYY-MM-DDTHH:MM:SS+00:00.csv

• <project_name> is the name of the study
• - All Patients will be included if the report includes al
• YYYY-MM-DDTHH:MM:SS+00:00 is the UTC timestamp that the report started generating

File Contents

The CSV file is a list of doses, with the following columns:

Column Name	Description	Data Value
Patient	The patient ID (set by the researchers, to uniquely and anonymously identify each participant as a member).	String (arbitrary value)
Project	The study name.	String (arbitrary value)
Package ID	A unique identifier per smart package.	String (arbitrary value)
Regimen ID	An identifier the patient's treatment plan. Typically, this is the drug name and frequency of intake.	String (arbitrary value)
Config Label	A hardware variable that comes from the smart package and describes what medications the package was set up to contain.	String (arbitrary value)
Patient Dose Index	The "nth" dose taken per patient.	Integer (from 1 upwards)
Dose Timestamp	The exact intake time, displayed in the patient's time zone.	String (formatted as an ISO 8601 timestamp)
Dose Timestamp UTC	The exact intake time, displayed in UTC.	String (formatted as an ISO 8601 timestamp)
Dose Group	N/A for eCAP type packaging. For Med-ic blister type packaging, this indicates whether the dose was taken from a particular section of the blister card (for example "Morning" doses).	String (arbitrary value)
Dose Label	Additional information about the dose that was taken. Typically, this is just set as the medication name.	String (arbitrary value)
Adherent	The adherence status of the dose. This value is determined by the patient's regimen (or lack thereof). "TRUE" if dose is adherent,"FALSE" if dose is non-adherent (early, late, or extra), "--" if adherence cannot be determined, "PRN" if regimen is take as needed	String (one of "TRUE", "FALSE", "PRN", "--")
Type	Indicates why a dose is adherent ("On Time") or non-adherent ("Early", "Late", or "Extra"). If adherence could not be determined this column will also indicate why: if a dose is "Unscheduled" (i.e. no regimen was set up to track this dose), "Unrecognized" (there was a mismatch issue when setting the config label on the smart package), or "PRN" (the regimen was set up for the patient to take as needed).	String (one of "On Time", "Early", "Late", "Extra", "PRN", "Unscheduled", "Unrecognized")
eDiary Status	What changes, if any, have been applied to the smart package data. "Logged" if the dose was added by a user rather than captured by a smart package sensor, "Edited" if the dose was captured by a smart package sensor but the timestamp was later changed by a user, "Excluded" if the dose was captured by a smart package sensor but needs to be removed from the patient's record, or "--" if no eDiary actions were applied. The eDiary is not enabled for all projects and therefore this column may not be relevant.	String (one of "Logged", "Edited", "Excluded", "--")
Original Timestamp	If a dose has an eDiary status, this column will indicate the original, unmodified timestamp recorded by the cap electronics. The eDiary is not enabled for all projects and therefore this column may not be relevant.	String (formatted as an ISO 8601 timestamp)