Skip Headers

Oracle® Health Sciences ClearTrial Cloud Service Web Services API User Guide Release 5.0 Part Number E39879-01 |
Home | Book List | Contents | Contact Us

Previous
| View PDF

# 9 Track API

The ClearTrial Track Web Services API is a bi-directional API that permits reading and writing of data in and out of the ClearTrial Track application.

The format for Track URLs is: /cleartrial-ws/actuals/{baselinePlanId}/{resourceName}

Where the {baselinePlanId} is the ID of the plan that was chosen as the baseline for the study and {resourceName} is one of the supported Track resources as described in Chapter 7, Plan Resources API.

For example, to obtain ClearTrial Track data and update it, use the Unix command line tool curl:

    curl --user myLogin:myPassword --header"customerCode: myCustomerCode" --header"Accept: application/json" --get https://api.cleartrial.com/cleartrial-ws/actuals/10802/sites

To enter or update Track data for the resource in the previous example, assuming that the data is present in a file called postContent, issue the following command:

    cat postContent | curl --user myLogin:myPassword --header"customerCode: myCustomerCode" --header"Content-Type: application/json" --post302 https://api.cleartrial.com/cleartrial-ws/actuals/10802/sites

To use an XML format, use the headers Accept: application/xml and ContentType: application/xml in the GET and POST requests, respectively. Upon a successful POST, the updated resource representation is echoed back to the ClearTrial Track Web Services API user. The general format of the interaction with the Track API is to GET the current state of the resource, update the representation with the actuals, and POST the updated representation back to the server.

## 9.1 Stale Data Resolution

As you use the ClearTrial Track API to obtain and update track data for a particular resource, the GET method returns may become obsolete or stale because another user has updated the track data for the same resource through the web interface.

If this happens, the ClearTrial Track API rejects the POST request and returns an HTTP Conflict 409 error code with an appropriate error message.

The server detects this situation because every POST request echoes the lockToken element that was sent to it in the preceding GET request for the resource. If the lockToken is missing, or if there is a mismatch between what was returned in the GET and what is being sent in the POST, the update fails and the server generates a Conflict 409 error code.

To proceed with the update, issue a fresh GET and obtain a new lockToken to get the latest view of the track data that you can update as needed.

## 9.2 Data Validation

The ClearTrial Track API performs data validation of all update requests. For each of the numerous validations, the ClearTrial Track API returns an error message detailing the errors. The categories of error messages include:

- Field cannot be empty

- Value of the field has to be in a particular range

- Date is invalid

## 9.3 Sites Track Data

Gets and posts data pertaining to the number of sites completed in each location per week.

Method: GET/POST

URL: /cleartrial-ws/actuals/{baselinePlanId}/sites

Sample output/input:

    {
     "actualSites": {
       "lockToken": 1304370420148,
       "planId": 10802,
       "location": [
          {
           "locationId": 100,
           "locationName":"USA",
           "periods": [
              {
               "period": {
                 "date":"01-Apr-2010",
                 "plannedValue":3,
                 "actualValue": 0
                },
               "period": {
                  …
                  ...
                },
                …
                ...
              }
            ]
          },
          {
           "locationId": 123,
           "locationName":"Japan",
             …
             ...
          }
          …
          ...
        ],
       "url":"/cleartrial-ws/actuals/10802/sites"
      }
    }

## 9.4 Subjects Track Data

Gets and posts data pertaining to the number of subjects enrolled in each location per week.

Method: GET/POST

URL: /cleartrial-ws/actuals/{baselinePlanId}/subjects

Sample output/input:

    {
     "actualSubjects": {
       "lockToken": 1304370420148,
       "planId": 10802,
       "location": [
          {
           "locationId": 100,
           "locationName":"USA",
           "periods": [
              {
               "period": {
                 "date":"01-Apr-2010",
                 "plannedValue":3,
                 "actualValue": 0
                },
               "period": {
                  …
                  ...
                },
                …
                ...
              }
            ]
          },
          {
           "locationId": 123,
           "locationName":"Japan",
             …
             ...
          }
          …
          ...
        ],
       "url":"/cleartrial-ws/actuals/10802/subjects"
      }
    }

## 9.5 Monitoring Track Data

Gets and posts data pertaining to the number of CRF pages completed in each location per week.

Method: GET/POST

URL: /cleartrial-ws/actuals/{baselinePlanId}/crfs

Sample output/input:

    {
     "actualCrfs": {
       "lockToken": 1304370420148,
       "planId": 10802,
       "location": [
          {
           "locationId": 100,
           "locationName":"USA",
           "periods": [
              {
               "period": {
                 "date":"01-Apr-2010",
                 "plannedValue":3,
                 "actualValue": 0
                },
               "period": {
                  …
                  ...
                },
                …
                ...
              }
            ]
          },
          {
           "locationId": 123,
           "locationName":"Japan",
             …
             ...
          }
          …
          ...
        ],
       "url":"/cleartrial-ws/actuals/10802/crfs"
      }
    }