This page describes the Scripting API of TraqBio which can be used by external programs to interact via TraqBio. This API is still work in progress. Currently, the available operations allow the implementation of automated work steps in projects.
The Scripting API is implemented as a RESTful web service. Hence, external programs are not required to run on the TraqBio server and can be implemented in any programming language.
The programs must use a valid TraqBio user account. It is recommended to create a dedicated account so that changes of the program can be traced in the timeline view of TraqBio.
This section describes the available operations in general and provides usage examples for shell scripts.
In the shell script examples the program
curl and the variable
$OPTS will be used:
# use -k only if a self-signed certificate is used OPTS="-f -s -k -b cookies.txt -c cookies.txt"
cookies.txt is used to keep session information between the single invocations of
It is assumed that your TraqBio instance is accessible at
https://traqbio.your.domain.tld (TraqBio as Subdomain).
The TraqBio as Subdirectory and TraqBio Standalone setups work analogously.
First a program is required to post a login request:
Provided that the user account name is stored in
$USER and the password in
$PW a login request via
curl looks as follows:
curl $OPTS "https://traqbio.your.domain.tld/login" -X POST --data-urlencode "username=$USER" --data-urlencode "password=$PW"
After a successful login the session will be stored in the
cookies.txt as specified in
$OPTS and used for every subsequent call.
The list of active projects can be read with the following request:
This returns a list of project ids separated with a newline character
curl invocation is the following:
curl $OPTS "https://traqbio.your.domain.tld/api/active-project-list"
The query whether a given project step
STEPNAME of a given project id
PID is currently the active step that needs to be worked on is done via this request:
If the step is the active step of the project, then its id will be returned. Otherwise, it will return an error.
curl the invocation is the following:
curl $OPTS "https://traqbio.your.domain.tld/api/project/$PID/is-active-step" -G --data-urlencode "name=$STEPNAME"
The error message in the case where step
$STEPNAME is not the active step of project
$PID is shown on the standard output when
-f is removed from the options
$OPTS passed to
The sample sheet of a project
PID can be downloaded with the following request:
The sample sheet download with
curl into a file
samplesheet.csv is done as follows:
curl $OPTS "https://traqbio.your.domain.tld/api/project/$PID/sample-sheet" -o samplesheet.csv
If there is no sample sheet in the given project, then no file will be downloaded.
The error message will be shown, when
-o samplesheet.csv are removed from the
A project step
STEPID of a project
PID can be marked as finished via this request:
Furthermore, the attributes of that work step might be changed as well.
To finish a step and modify its attributes, the following
curl invocation can be used:
curl $OPTS -X POST "https://traqbio.your.domain.tld/api/project/$PID/finish-step/$STEPID" --data-urlencode "description=$DESCR" --data-urlencode "freetext=$TEXT" --data-urlencode "advisor=$ADVISOR"
The exemplary shell script api-script.sh shows the general layout of an automated work step using the Scripting API:
#!/bin/sh SERVER="https://localhost:8443" USERNAME="gv" PASSWORD="gv" # use -k only if a self-signed certificate is used OPTS="-f -s -k -b cookies.txt -c cookies.txt" STEPNAME="S4 D" SAMPLESHEET="samplesheet.csv" # login curl $OPTS "$SERVER/login" -X POST --data-urlencode "username=$USERNAME" --data-urlencode "password=$PASSWORD" for pid in $(curl $OPTS "$SERVER/api/active-project-list") do echo "Active project:" $pid # detect whether the step with the specified name is the active step stepid=$(curl $OPTS "$SERVER/api/project/$pid/is-active-step" -G --data-urlencode "name=$STEPNAME") result=$? if [ $result -ne 0 ] then echo "Step \"$STEPNAME\" is not the active step of project $pid." continue fi echo "Active step \"$STEPNAME\" of project $pid has id $stepid." # get sample sheet curl $OPTS "$SERVER/api/project/$pid/sample-sheet" -f -o $SAMPLESHEET result=$? if [ $result -ne 0 ] then echo "Project $pid has no sample sheet." # we decide to continue if there is no sample sheet continue fi echo "Sample sheet downloaded to $SAMPLESHEET." # do some analysis based on sample sheet # on success finish the active step curl $OPTS -X POST "$SERVER/api/project/$pid/finish-step/$stepid" --data-urlencode "description=Sophisticated analysis" --data-urlencode "freetext=Done. Results are available at ...." --data-urlencode "advisor=John Doe" result=$? if [ $result -ne 0 ] then echo "Marking step $stepid of project $pid as finished failed!" else echo "Step $stepid of project $pid has been marked as finished!" fi done