...
TrialKit is a cloud-based data collection and trial management system. A single sign-in can get you access to a host or hosts across multiple clouds, seamlessly. As a developer, you should have a thorough understanding of the process involved with switching hosts. Especially when those hosts exist on different clouds. This Overview will detail that process.
...
The possibility of having access to multiple Hosts and Studies requires that you set the given host and study as the default for your user account prior to making calls to accomplish something on that study. By doing so, you make subsequent calls to query data from the host and study by authenticating. Once authenticated, the system pulls the current host and/or study when servicing calls. This restricts developers to only accessing data for the hosts and studies in to which they belong.
| Info |
|---|
To use the API on a host or study, you must set the host or study as the default first. If the API user only belongs to a single study, the default will always be the same. |
...
By learning the system, you can see exactly how roles are created. Each role is granted access rights to Apps and functions within the various apps. There are over 100 different Apps that make up the TrialKit and TrialKit systems. The Host/Study Admin Users determine which user roles can access which Apps and App functions. For the most part, Admins should be granted access to everything, with the possible exception of the plethora of delete functions. Learning the Role Security system within TrialKit , will greatly increase your ability to access the various data through the API with your current role or to create new apps and features and limit them to certain roles and rights.
...
There are two call types; TOC and Host Web Service. Both are web services. Sometimes you must call the TOC, especially when changing hosts. The TOC will return to you the URL of the Host Web Service. Then, all calls you make for that host and it's corresponding its corresponding studies, you will use the Host Web Service URL.
...
E-Mail / Password combination. This is assigned to you by your study administrator. You You can (and should) download TrialKit and Sign In with these credentials.
From Access Key. The From Access Key is assigned to you by CDS. It is an email address address that allows you access to the calls you will need to make.
...
It is of great importance that you understand there are two ways that the REST standard can can report errors. There are standard web service errors such as 401 and 404. Those errors mean mean you probably have an error in the URL being used to call the web service.
The second and most important error condition sends back a 200 code (success), but the return return dictionary contains the key: "error". The value of the key is the actual error message. The call call failed any time that the "error" key appears in the return dictionary. Your code should always check check for an "error" key first on any 200 return condition. Here is a quick snippet of how Objective C handles this condition:
...
Passing Different Field Type Values
Date/time
Example The example assumes user preference is dd-mon-yyyy (4) hh:mi24 (2)
...
Stored in DB as Double Precision floating-point numbers
| Code Block |
|---|
{
"fld_id": "99",
"fld_value": "34.67",
"fld_name": "age"
} |
...
Common Calls
The list below are is the most commonly needed calls. Please contact support if there are any functions you need access to which are not published here.
Remember from the basics covered above, calls require a URL that depends on where a controller/method is being called. URLs which that are always the same will be referenced below. For any that depend on the user’s server, it will be referenced in the following format:
...
TrialKit is a multi-cloud platform. Basically, that means that TrialKit data is stored across clouds. In order to access that data, you must first Sign In. That gives you information about your user account, but also it tells you the server that your current current host resides on. That server has a Host Web service URL and you will collect that and use it to to access data from that host, including all study and patient data.
...
Next, click the SEND button to send your send your request to the server. You should receive a 200 code in return. The following is the documentation for the Sign-In method:
In your code, you will want to store this data. The server_webservice_url is of particular particular importance. You will use it to access all your study and patient data from the current host. All of the REST calls are made in a similar fashion. You just need to distinguish between a call to the TOC and a call to the Host Webservice.
...
If you will be accessing data across different hosts, then this method is very important. Prior to changing changing a host, you must know something about the host. Calling this method is very simple and straight forwardand straightforward:
Get the Current Default Host and Study
...
We must first capture the web service URL for the default host. This can be done in a variety of of ways, but when you set the default host, this URL was returned. Depending on the cloud you are working on it will look something like this:
https://webapi.clinicalstudio.com/api
We will use this web service now to retrieve host, study, and patient information.
The first step is to get a list of studies, this is another very simple operation. Remember it it operates on the default host. We will be calling the study controller to get a list of studies that that belong to the default host. The call should look something like this:
https://webapi.clinicalstudio.com/api/study/12
...
This service returns nothing if it works. Like all other services, if it does does not work it will return "error" as a key in the dictionary. Services do not have to return return anything. The 200 status is enough for some services. 200 along with an empty dictionary dictionary means the call succeeded and you can move on.
...
We want to get a list of all the sites to which we belong. We are going to call the site controller controller to accomplish this.
Set a Default Site
...
This is the first GET service where you are passing two parameters. The two parameters tell REST how to route the call. Once routed the first parameter routes the call within the the controller. In this case, you are saying route this call to the Subject Controller. From there, find the get procedure that requires 2 header parameters. Once there, check the first parameter for the route within the subject controller. In this case, get all subjects for the passed site.
...
By retrieving a list of subjects for any given site to which you belong, you are now ready to to access the subject data.
Get All Records For a Subject
...
With the list of subjects previously retrieved, it is time to ask the web service to return all the the completed records for a given subject. Optionally, you can pass a specific form_id and filter by just that form. If you do not want to filter by form, simply pass a -1.
...
Usually, the important factor being retrieved from this information are is the trans_id of each record. With the trans_id, it will be possible to then get the data from that record next.
...
The trans_id was received in the prior call to get all subject records. Simply passing that to this method method returns all of the data required to read a record.
Records are dynamic in TrialKit. That means that forms are created by Study Builders on the fly. There are no hard-coded form layouts. In order to make sense of the data you actually actually need to parse the form data dictionary, which is returned in the method.
...
| Info |
|---|
This is important to verify the correct date format is being passed later on when doing any data updates on date or time fields. |
In order to send a receive dates to the API, we must know the date and time format for our user user account. This can all be hard codedhardcoded, but if you want to be to able freely change those formats, and still have your code work, you will need to retrieve those formats from the User Preferences.
Date Formats Format options are listed below.
Pay particular attention to the ID column in the above tables. That ID is what the API will pass to to you when retrieving the user preferences.
...
All that is required by TrialKit is to have a date of registration. Any other field data depends on how the form was designed. The first date is known as the Registration Start Date and is used to calculate visit intervals and other items based on rules created by the study builder. For us, when registering a new subject, this is the only data that we need to pass.
All that has to be passed passed is the actual form data for the registration form. Optionally, you can pass another key/value pair to override the system-generated Subject Profile ID. The Subject Profile ID is used to identify a subject. If, when registering a new subject, you want to override the Subject Profile ID, you can pass that in the body of the the call as well.
Here is a look at the body of the Post which is a JSON string:
...
Notice the last key/value pair is the sub_profile_id. This tells TrialKit to override the system and and use the value of this key as the Subject Profile ID.
...
If updating an existing record, the trans_id is needed. This is obtained from the subject/3 call. The trans_id is the primary key for all subject visit/event records. For example, an Adverse Event Event form is considered a subject visit/event record and uses the trans_id as its primary key. That visit/event record is related to the subject by the sub_id. In addition, records can be scheduled, unscheduled, or considered log forms.
...
There are a few rules with scheduled and unscheduled visits; the most important is you can can only have a single form completed for a single interval. That means in the baseline interval, you you can only save a single inclusion/exclusion form. If you want to update that form, you must first first retrieve that form's trans_id. Log forms can have multiple records as they are just stored longitudinallylongitudinally. However, if your study builder restricts log forms to a single record and you try and and save multiple records, the API will return an error.
...
Depending on what you are trying to accomplish, you may be to retrieve the scheduled visits for for a given subject. Remember, the visit schedule for subjects within a study can differ based on the the Scheduled Visit Cohort that is assigned to a particular subject. Fortunately, this is very easy using the API.
...
<URL>/activity/5 with the body as follows:
| Note |
|---|
Prerequisite: The study must be enabled by CDS for accessing wearable data. |
Prerequisite: The study must be enabled by CDS for accessing wearable data.
...