Protocol

From ToxBank API Wiki
(Difference between revisions)
Jump to: navigation, search
m (PUT: Update Protocol metadata)
 
(112 intermediate revisions by 2 users not shown)
Line 1: Line 1:
{{REST_resource
+
{{REST_resource}}
}}
+
  
= Retrieve the List of Protocols =
+
A [[API_Protocol|Protocol]] contains a single MSWord or PDF document, describing how to perform certain experiment (lab or in-silico), and metadata. A Protocol defines a [[API_Protocol:RetrieveTemplate|Data template]].
{{:API_Protocol:RetrieveList}}
+
The results of performing the experiment are recorded in a (set of) [[Investigation|Investigations]].
 +
A [[API_Protocol|Protocol]] may have [[API_Protocol#Protocol_versions_REST_interface|versions]]. A Protocol version is another [[API_Protocol|Protocol]].
  
= Upload a new Protocol =
+
A Protocol includes links to [[API_User|Author(s)]], related [[Project]] and [[Organisation]]. The protocol [[API_User|Owner]] is assigned automatically, when the protocol is uploaded by a logged-in user.
{{:API_Protocol:Upload}}
+
  
= Retrieve a single Protocol =
+
TBD: Parameter names to be added to the protocol representation, as in ISA-TAB
{{:API_Protocol:Retrieve}}
+
  
= Retrieve Metadata of a single Protocol =
+
= REST interface =
{{:API_Protocol:RetrieveMetadata}}
+
== Protocol ==
  
[[http://api.toxbank.net/index.php/Special:FormEdit/REST_OperationsForm/API_Protocol Edit 'Protocol' API ]]
+
=== GET: Retrieve the list of Protocols ===
 +
{{HasOperation |id=API_Protocol:RetrieveList}}
 +
Example: [http://toxbanktest1.opentox.org:8080/toxbank/protocol http://toxbanktest1.opentox.org:8080/toxbank/protocol]
 +
==== cURL example ====
 +
curl -X GET -H 'Accept:text/uri-list' -H 'subjectid:TOKEN' http://toxbanktest1.opentox.org:8080/toxbank/protocol
 +
 
 +
curl -X GET -H 'Accept:application/rdf+xml' -H 'subjectid:TOKEN' http://toxbanktest1.opentox.org:8080/toxbank/protocol?search=Tox
 +
 
 +
curl -X GET -H 'Accept:text/uri-list' -H 'subjectid:TOKEN' http://toxbanktest1.opentox.org:8080/toxbank/protocol?page=0&pagesize=5
 +
 
 +
curl -X GET -H 'Accept:text/uri-list' -H 'subjectid:TOKEN' http://toxbanktest1.opentox.org:8080/toxbank/protocol?modifiedSince=1293837000000
 +
 
 +
=== GET: Retrieve Metadata of a single Protocol ===
 +
{{HasOperation |id=API_Protocol:RetrieveMetadata}}
 +
Example: [http://toxbanktest1.opentox.org:8080/toxbank/protocol/SEURAT-Protocol-1-1  http://toxbanktest1.opentox.org:8080/toxbank/protocol/SEURAT-Protocol-1-1]
 +
==== cURL example ====
 +
curl -X GET -H 'Accept:application/rdf+xml' -H 'subjectid:TOKEN' http://toxbanktest1.opentox.org:8080/toxbank/protocol/SEURAT-Protocol-1-1
 +
 
 +
=== POST: Upload a new Protocol ===
 +
{{HasOperation |id=API_Protocol:Upload}}
 +
==== cURL example ====
 +
curl -X POST -H 'subjectid:TOKEN' -H 'Content-Type:multipart/form-data' -F 'filename=@FILE_NAME' \
 +
-d 'title=VALUE' -d 'anabstract=VALUE' -d 'author_uri=VALUE' -d 'author_uri=VALUE' -d 'author_uri=VALUE' \
 +
-d 'keywords=VALUE' -d 'summarySearchable=VALUE' -d 'project_uri=Project URI' -d 'organisation_uri=Organisation URI'
 +
-d 'user_uri=Owner User URI' http://toxbanktest1.opentox.org:8080/toxbank/protocol
 +
 
 +
=== PUT: Update Protocol metadata ===
 +
{{HasOperation |id=API_Protocol:Update}}
 +
==== cURL example - update protocol metadata ====
 +
curl -X PUT -H 'subjectid:TOKEN' -H 'Content-Type:multipart/form-data' \
 +
-F 'title=VALUE' -F 'anabstract=VALUE' -F 'author_uri=VALUE' \
 +
-F 'keywords=VALUE' -F 'summarySearchable=VALUE' http://toxbanktest1.opentox.org:8080/toxbank/protocol/SEURAT-Protocol-1-1
 +
 
 +
==== cURL example - Update metadata, protocol file and the published flag ====
 +
curl -X PUT -H 'subjectid:TOKEN' -H 'Content-Type:multipart/form-data' \
 +
-F 'title=VALUE' -F 'anabstract=VALUE' -d 'published=true' \
 +
-F "file=@updated.pdf" http://toxbanktest1.opentox.org:8080/toxbank/protocol/SEURAT-Protocol-1-1
 +
 
 +
==== cURL example - Update the published flag only ====
 +
$ curl -X PUT -H "subjectid:TOKEN" -H "Content-Type:multipart/form-data" \
 +
-F "published=true" http://toxbanktest1.opentox.org:8080/toxbank/protocol/SEURAT-Protocol-269-25 -iv
 +
 
 +
Note all update (PUT) and create (POST) examples use multipart/form-data, regardless of whether file is uploaded or not.
 +
 
 +
The published flag is part of the RDF representation
 +
 
 +
http://toxbanktest1.opentox.org:8080/toxbank/protocol/SEURAT-Protocol-269-25 -H "Accept:text/n3"
 +
@prefix tb:      <http://onto.toxbank.net/api/> .
 +
[output skipped]
 +
tbpl:SEURAT-Protocol-269-25
 +
      a      tb:Protocol ;
 +
        tb:isPublished "true"^^xsd:boolean ;
 +
  [output skipped]
 +
 
 +
=== POST: Publish a protocol ===
 +
 
 +
To change only the publish flag, use POST to /protocol/{id}/publication resource
 +
 
 +
==== cURL example - Update metadata, protocol file and the published flag ====
 +
curl -X POST -H 'subjectid:TOKEN' -H 'Content-Type:multipart/form-data' \
 +
-d 'published=true'  http://toxbanktest1.opentox.org:8080/toxbank/protocol/SEURAT-Protocol-1-1/publication
 +
 
 +
== Documents ==
 +
=== GET: Retrieve the protocol file ===
 +
{{HasOperation |id=API_Protocol:Retrieve}}
 +
Example [http://toxbanktest1.opentox.org:8080/toxbank/protocol/SEURAT-Protocol-30-3/document?media=application%2Fpdf http://toxbanktest1.opentox.org:8080/toxbank/protocol/SEURAT-Protocol-30-3/document]
 +
==== cURL example ====
 +
 
 +
  curl -X GET -H 'Accept:application/pdf' -H 'subjectid:TOKEN' \
 +
                    http://toxbanktest1.opentox.org:8080/toxbank/protocol/SEURAT-Protocol-30-3/document
 +
 
 +
  curl -X GET -H 'Accept:application/msword' -H 'subjectid:TOKEN' \
 +
                    http://toxbanktest1.opentox.org:8080/toxbank/protocol/SEURAT-Protocol-30-3/document
 +
 
 +
=== POST: Upload the protocol file ===
 +
 
 +
Once uploaded via [http://api.toxbank.net/index.php/Protocol#POST:_Upload_a_new_Protocol], a protocol file can't be modified. However, a new version of the protocol could be uploaded.
 +
 
 +
== Versions ==
 +
A Protocol may have versions. A Protocol version is another Protocol.
 +
=== GET: Retrieve versions of a single Protocol ===
 +
{{HasOperation |id=API_Protocol:RetrieveVersions }}
 +
==== cURL example ====
 +
curl -X GET -H 'Accept:SUPPORTED-MEDIA-TYPE' -H 'subjectid:TOKEN' \
 +
                http://toxbanktest1.opentox.org:8080/toxbank/protocol/SEURAT-Protocol-30-4/versions
 +
 
 +
=== POST: Upload a new Protocol version ===
 +
{{HasOperation |id=API_Protocol:UploadVersion}}
 +
====cURL example====
 +
curl -X POST -H 'subjectid:TOKEN' -H 'Content-Type:multipart/form-data' -F 'filename=@FILE_NAME' \
 +
              -d 'title=VALUE' -d 'anabstract=VALUE' -d 'author_uri=VALUE' -d 'author_uri=VALUE'  \
 +
              -d 'keywords=VALUE' -d 'summarySearchable=VALUE' -d 'project_uri=Project URI' \
 +
              -d 'organisation_uri=Organisation URI' -d 'user_uri=Owner User URI' \
 +
              -d 'allowReadByUser=User URI' \
 +
              http://toxbanktest1.opentox.org:8080/toxbank/protocol/SEURAT-Protocol-30-4/versions
 +
 
 +
= Security =
 +
 
 +
==== SEURAT-1 access ====
 +
 
 +
All SEURAT-1 members are allowed to upload protocols.
 +
 +
This is ensured by allowing POST and GET to http://services.toxbank.net/toxbank/protocol to the members of groups coach,scrtox,hemibio,notox,cosmos,toxbank,detective,sep.
 +
 
 +
The policies can be browsed
 +
[https://services.toxbank.net/toxbank/admin/policy?search=https%3A%2F%2Fservices.toxbank.net%2Ftoxbank%2Fprotocol here].
 +
A XACML policy template [[File:Policy-allconsortia.xml]]
 +
 
 +
 +
Note: During the alpha test only a Principal Investigator (PI) is allowed to upload protocols.
 +
This was ensured by allowing POST and GET to http://toxbanktest1.opentox.org:8080/toxbank/protocol to the LDAP '''PI''' group members only. This is now changed!
 +
 
 +
==== Protocol read rights are specified on upload, and can be modified later by the protocol owner ====
 +
 
 +
Access levels, entered via GUI are translated into an OpenSSO policy by the protocol service. The following fields are added to the multipart web form, sent on PUT or POST. There could be more than one field of each type:
 +
 
 +
*'''allowReadByUser''' : An URI of an existing ToxBank user, e.g. http://toxbanktest1.opentox.org:8080/toxbank/user/U1
 +
*'''allowReadByGroup''' : An URI of existing ToxBank [http://toxbanktest1.opentox.org:8080/toxbank/project/G1 consortium] or [http://toxbanktest1.opentox.org:8080/toxbank/organisation/G1 organisation].
 +
 
 +
The protocol service reads the multipart web form, generates OpenAM [http://en.wikipedia.org/wiki/XACML XACML] policy and sends it to the [http://opensso.in-silico.ch/opensso/policy OpenTox policy service], upon successful POST or PUT operation. The old policy for the same URI is deleted.
 +
 
 +
The UI generates the web form fields as follows:
 +
 
 +
*Only authors  - Fills '''allowReadByUser''' fields with the authors URIs. The users are associated with the corresponding LDAP user names via [http://toxbanktest1.opentox.org:8080/toxbank/user/U1?media=text%2Fn3 tb:hasAccount]
 +
*Consortium - Fills '''allowReadByGroup''' fields with the project URIs. The projects are associated with the corresponding LDAP groups via [http://toxbanktest1.opentox.org:8080/toxbank/project/G2?media=text%2Fn3 tb:hasAccount]
 +
*SEURAT -  Fills '''allowReadByGroup''' fields with all project URIs, which are defined as [http://toxbanktest1.opentox.org:8080/toxbank/project?media=text%2Fn3 tb:subOrganisationOf SEURAT-1]
 +
*Public -  Fills '''allowReadByGroup''' field with the URI of a [http://toxbanktest1.opentox.org:8080/toxbank/organisation/G176 "Public" organisation]. The public organisation is associated to the LDAP group "'''member'''"
 +
*Custom access - Fills '''allowReadByUser''' fields with selected user URIs
 +
 
 +
=====Only the protocol owner can update the protocol =====
 +
 
 +
The protocol service adds to the policy a rule, allowing full access for the protocol owner.
 +
 
 +
 
 +
==== cURL example - Update the access rights  only ====
 +
$ curl -X PUT -H "subjectid:TOKEN" -H "Content-Type:multipart/form-data" \
 +
--form "allowReadByUser=http://toxbanktest1.opentox.org:8080/toxbank/user/U1" http://toxbanktest1.opentox.org:8080/toxbank/protocol/SEURAT-Protocol-269-25 -iv
 +
 
 +
Note all update (PUT) and create (POST) examples use multipart/form-data, regardless of whether file is uploaded or not.
 +
 
 +
=====Implementation =====
 +
*[https://github.com/vedina/opentox-aa-cli/blob/master/src/main/java/org/opentox/aa/policy/PolicyParser.java Generates XML policy, (without sending)], part of the [http://vedina.github.com/opentox-aa-cli/ Java OpenTox AA client]. The OpenTox AA client supports login in and sending / retrieving the policies.
 +
*[https://github.com/ToxBank/toxbank-api-beans/tree/master/src/main/java/net/toxbank/client/policy Java beans] for access rights and policy rules;
 +
*[https://github.com/ToxBank/toxbank-api-client/blob/master/src/main/java/net/toxbank/client/TBClient.java Java Client], convenience methods for communication with the policy service. The real work is done by the [http://vedina.github.com/opentox-aa-cli/ Java OpenTox AA client].
 +
 
 +
= RDF representation =
 +
 
 +
== Stable version ==
 +
[http://jenkins.toxbank.net/job/production-toxbank-api-beans/ws/target/test-classes/Protocol.full.n3]
 +
 
 +
This RDF representation is automatically generated by the production version of the [https://github.com/ToxBank/toxbank-api-beans/tree/toxbank-api-beans-0.0.2 Toxbank Java client library]
 +
 
 +
== Alpha test version ==
 +
[http://jenkins.toxbank.net/job/alpha-toxbank-api-beans/ws/target/test-classes/Protocol.full.n3]
 +
 
 +
This RDF representation is automatically generated by the alpha test version of the [https://github.com/ToxBank/toxbank-api-beans/tree/alphatest Toxbank Java client library]
 +
 
 +
== Development version ==
 +
[http://jenkins.toxbank.net/job/dev-toxbank-api-beans/ws/target/test-classes/Protocol.full.n3]
 +
 
 +
This RDF representation is automatically generated by the latest version of the [https://github.com/ToxBank/toxbank-api-beans Toxbank Java client library]
 +
 
 +
== Example in RDF/XML  ==
 +
 
 +
<pre>
 +
 
 +
<?xml version="1.0"?>
 +
<!DOCTYPE rdf:RDF [
 +
  <!ENTITY tb 'http://onto.toxbank.net/api/'>
 +
  <!ENTITY foaf 'http://xmlns.com/foaf/0.1/'>
 +
  <!ENTITY tbpl 'http://toxbanktest1.opentox.org:8080/toxbank/protocol/'>
 +
  <!ENTITY SEURAT-Protocol-3-1 'http://toxbanktest1.opentox.org:8080/toxbank/protocol/SEURAT-Protocol-3-1/'>
 +
  <!ENTITY tbo 'http://toxbanktest1.opentox.org:8080/toxbank/organisation/'>
 +
  <!ENTITY xsd 'http://www.w3.org/2001/XMLSchema#'>
 +
  <!ENTITY rdf 'http://www.w3.org/1999/02/22-rdf-syntax-ns#'>
 +
  <!ENTITY tbpt 'http://toxbanktest1.opentox.org:8080/toxbank/project/'>
 +
  <!ENTITY tbu 'http://toxbanktest1.opentox.org:8080/toxbank/user/'>
 +
  <!ENTITY dcterms 'http://purl.org/dc/terms/'>]>
 +
<rdf:RDF
 +
    xmlns:SEURAT-Protocol-3-1="&SEURAT-Protocol-3-1;"
 +
    xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
 +
    xmlns:foaf="&foaf;"
 +
    xmlns:tbo="&tbo;"
 +
    xmlns:tbu="&tbu;"
 +
    xmlns:dcterms="&dcterms;"
 +
    xmlns:xsd="&xsd;"
 +
    xmlns:tbpt="&tbpt;"
 +
    xmlns:tbpl="&tbpl;"
 +
    xmlns:tb="&tb;">
 +
  <tb:Protocol rdf:about="&tbpl;SEURAT-Protocol-3-1">
 +
    <tb:isSummarySearchable rdf:datatype="&xsd;boolean">true</tb:isSummarySearchable>
 +
    <tb:hasProject>
 +
      <tb:Project rdf:about="&tbpt;G2">
 +
        <tb:subOrganisationOf rdf:resource="SEURAT-1"/>
 +
        <tb:hasAccount rdf:datatype="&xsd;string">toxbank</tb:hasAccount>
 +
        <dcterms:title rdf:datatype="&xsd;string">ToxBank</dcterms:title>
 +
      </tb:Project>
 +
    </tb:hasProject>
 +
    <tb:hasKeyword rdf:datatype="&xsd;string">http://www.owl-ontologies.com/toxbank.owl/K347</tb:hasKeyword>
 +
    <tb:hasKeyword rdf:datatype="&xsd;string">http://www.owl-ontologies.com/toxbank.owl/K258</tb:hasKeyword>
 +
    <dcterms:dateSubmitted rdf:datatype="&xsd;long">1338406901000</dcterms:dateSubmitted>
 +
    <dcterms:title rdf:datatype="&xsd;string">TDx/TDxFLx Acetaminophen assay</dcterms:title>
 +
    <tb:hasOwner rdf:resource="&tbu;U115"/>
 +
    <tb:hasVersionInfo rdf:datatype="&xsd;long">1</tb:hasVersionInfo>
 +
    <tb:hasAuthor>
 +
      <foaf:Person rdf:about="&tbu;U184">
 +
        <foaf:holdsAccount>
 +
          <foaf:OnlineAccount rdf:about="mailto:null">
 +
            <foaf:accountServiceHomepage rdf:datatype="&xsd;string"
 +
            >mailto</foaf:accountServiceHomepage>
 +
          </foaf:OnlineAccount>
 +
        </foaf:holdsAccount>
 +
        <foaf:family_name rdf:datatype="&xsd;string">Peterson</foaf:family_name>
 +
        <foaf:givenname rdf:datatype="&xsd;string">C.</foaf:givenname>
 +
      </foaf:Person>
 +
    </tb:hasAuthor>
 +
    <dcterms:identifier rdf:datatype="&xsd;string">SEURAT-Protocol-3-1</dcterms:identifier>
 +
    <tb:hasAbstract rdf:datatype="&xsd;string">The TDx/TDxFLx Acetaminophen assay is a reagent system for the&#xD;
 +
quantitative measurement of acetaminophen in human serum or plasma.&#xD;
 +
Measurements obtained are used in the diagnosis and treatment of&#xD;
 +
acetaminophen overdose.</tb:hasAbstract>
 +
    <tb:hasDocument rdf:resource="&SEURAT-Protocol-3-1;document"/>
 +
    <tb:isPublished rdf:datatype="&xsd;boolean">true</tb:isPublished>
 +
    <tb:hasOrganisation>
 +
      <tb:Organization rdf:about="&tbo;G274">
 +
        <dcterms:title rdf:datatype="&xsd;string">Abbott</dcterms:title>
 +
      </tb:Organization>
 +
    </tb:hasOrganisation>
 +
    <tb:hasStatus rdf:datatype="&xsd;string">SOP</tb:hasStatus>
 +
    <dcterms:modified rdf:datatype="&xsd;long">1338475897000</dcterms:modified>
 +
  </tb:Protocol>
 +
</rdf:RDF>
 +
 
 +
 
 +
</pre>

Latest revision as of 04:26, 18 July 2014

Protocol


A Protocol contains a single MSWord or PDF document, describing how to perform certain experiment (lab or in-silico), and metadata. A Protocol defines a Data template. The results of performing the experiment are recorded in a (set of) Investigations. A Protocol may have versions. A Protocol version is another Protocol.

A Protocol includes links to Author(s), related Project and Organisation. The protocol Owner is assigned automatically, when the protocol is uploaded by a logged-in user.

TBD: Parameter names to be added to the protocol representation, as in ISA-TAB

Contents

REST interface

Protocol

GET: Retrieve the list of Protocols

Description Retrieves list of protocols
Resource Protocol
Method GET
URI /protocol
Parameters none, or ?search=name or paging parameters: page, pagesize or modefiedSince=UNIX-TIME-STAMP-in-ms
Header Parameters subjectid:SECURITY-TOKEN
Media Type (input) none
Results The protocol representation in supported media type
Media Type (output) text/uri-list;application/rdf+xml;text/n3
Status code 200, 400, 401, 402, 403

Links: Page, Edit with form


Example: http://toxbanktest1.opentox.org:8080/toxbank/protocol

cURL example

curl -X GET -H 'Accept:text/uri-list' -H 'subjectid:TOKEN' http://toxbanktest1.opentox.org:8080/toxbank/protocol 
curl -X GET -H 'Accept:application/rdf+xml' -H 'subjectid:TOKEN' http://toxbanktest1.opentox.org:8080/toxbank/protocol?search=Tox
curl -X GET -H 'Accept:text/uri-list' -H 'subjectid:TOKEN' http://toxbanktest1.opentox.org:8080/toxbank/protocol?page=0&pagesize=5
curl -X GET -H 'Accept:text/uri-list' -H 'subjectid:TOKEN' http://toxbanktest1.opentox.org:8080/toxbank/protocol?modifiedSince=1293837000000

GET: Retrieve Metadata of a single Protocol

Description Retrieves the protocol metadata
Resource Protocol
Method GET
URI /protocol/{id}
Parameters none
Header Parameters subjectid:SECURITY-TOKEN
Media Type (input) none
Results The metadata representation in supported media type
Media Type (output) text/uri-list;application/rdf+xml;text/n3
Status code 200,400,401,402,403

Links: Page, Edit with form


Example: http://toxbanktest1.opentox.org:8080/toxbank/protocol/SEURAT-Protocol-1-1

cURL example

curl -X GET -H 'Accept:application/rdf+xml' -H 'subjectid:TOKEN' http://toxbanktest1.opentox.org:8080/toxbank/protocol/SEURAT-Protocol-1-1

POST: Upload a new Protocol

Description Uploads a protocol
Resource Protocol
Method POST
URI /protocol
Parameters (see cURL example)
Header Parameters subjectid:SECURITY-TOKEN
Media Type (input) multipart/form-data
Results Task representation in supported MIME formats
Media Type (output) text/uri-list;application/rdf+xml;text/n3
Status code 200,202,400,401,402,403,500

Links: Page, Edit with form


cURL example

curl -X POST -H 'subjectid:TOKEN' -H 'Content-Type:multipart/form-data' -F 'filename=@FILE_NAME' \
-d 'title=VALUE' -d 'anabstract=VALUE' -d 'author_uri=VALUE' -d 'author_uri=VALUE' -d 'author_uri=VALUE' \
-d 'keywords=VALUE' -d 'summarySearchable=VALUE' -d 'project_uri=Project URI' -d 'organisation_uri=Organisation URI' 
-d 'user_uri=Owner User URI' http://toxbanktest1.opentox.org:8080/toxbank/protocol

PUT: Update Protocol metadata

Description Updates a protocol
Resource Protocol
Method PUT
URI /protocol/{id}
Parameters (see cURL example)
Header Parameters subjectid:SECURITY-TOKEN
Media Type (input) application/x-www-form-urlencoded
Results Task representation in supported MIME formats
Media Type (output) text/uri-list;application/rdf+xml;text/n3
Status code 200,202,400,401,402,403,500

Links: Page, Edit with form


cURL example - update protocol metadata

curl -X PUT -H 'subjectid:TOKEN' -H 'Content-Type:multipart/form-data' \
-F 'title=VALUE' -F 'anabstract=VALUE' -F 'author_uri=VALUE' \
-F 'keywords=VALUE' -F 'summarySearchable=VALUE' http://toxbanktest1.opentox.org:8080/toxbank/protocol/SEURAT-Protocol-1-1

cURL example - Update metadata, protocol file and the published flag

curl -X PUT -H 'subjectid:TOKEN' -H 'Content-Type:multipart/form-data' \
-F 'title=VALUE' -F 'anabstract=VALUE' -d 'published=true' \
-F "file=@updated.pdf" http://toxbanktest1.opentox.org:8080/toxbank/protocol/SEURAT-Protocol-1-1

cURL example - Update the published flag only

$ curl -X PUT -H "subjectid:TOKEN" -H "Content-Type:multipart/form-data" \
-F "published=true" http://toxbanktest1.opentox.org:8080/toxbank/protocol/SEURAT-Protocol-269-25 -iv

Note all update (PUT) and create (POST) examples use multipart/form-data, regardless of whether file is uploaded or not.

The published flag is part of the RDF representation

http://toxbanktest1.opentox.org:8080/toxbank/protocol/SEURAT-Protocol-269-25 -H "Accept:text/n3"
@prefix tb:      <http://onto.toxbank.net/api/> .
[output skipped] 
tbpl:SEURAT-Protocol-269-25
     a       tb:Protocol ;
       tb:isPublished "true"^^xsd:boolean ;
 [output skipped]

POST: Publish a protocol

To change only the publish flag, use POST to /protocol/{id}/publication resource 

cURL example - Update metadata, protocol file and the published flag

curl -X POST -H 'subjectid:TOKEN' -H 'Content-Type:multipart/form-data' \
-d 'published=true'  http://toxbanktest1.opentox.org:8080/toxbank/protocol/SEURAT-Protocol-1-1/publication

Documents

GET: Retrieve the protocol file

Description Retrieves the document, describing the protocol
Resource Protocol
Method GET
URI /protocol/{id}/document
Parameters none
Header Parameters subjectid:SECURITY-TOKEN
Media Type (input) none
Results Protocol content in one of supported MIME format
Media Type (output) application/pdf;application/msword
Status code 200,400,401,402,403

Links: Page, Edit with form


Example http://toxbanktest1.opentox.org:8080/toxbank/protocol/SEURAT-Protocol-30-3/document

cURL example

 curl -X GET -H 'Accept:application/pdf' -H 'subjectid:TOKEN' \
                    http://toxbanktest1.opentox.org:8080/toxbank/protocol/SEURAT-Protocol-30-3/document
 curl -X GET -H 'Accept:application/msword' -H 'subjectid:TOKEN' \
                    http://toxbanktest1.opentox.org:8080/toxbank/protocol/SEURAT-Protocol-30-3/document

POST: Upload the protocol file

Once uploaded via [1], a protocol file can't be modified. However, a new version of the protocol could be uploaded.

Versions

A Protocol may have versions. A Protocol version is another Protocol.

GET: Retrieve versions of a single Protocol

Description Retrieves the protocol versions
Resource Protocol
Method GET
URI /protocol/{id}/versions
Parameters none, or ?search=name or paging parameters: page, pagesize
Header Parameters subjectid:SECURITY-TOKEN
Media Type (input) none
Results The protocol URI or other supported representation
Media Type (output) text/uri-list;application/rdf+xml;text/n3
Status code 200,400,401,402,403

Links: Page, Edit with form


cURL example

curl -X GET -H 'Accept:SUPPORTED-MEDIA-TYPE' -H 'subjectid:TOKEN' \
               http://toxbanktest1.opentox.org:8080/toxbank/protocol/SEURAT-Protocol-30-4/versions

POST: Upload a new Protocol version

Description Uploads a newprotocol version
Resource Protocol
Method POST
URI /protocol/{id}/versions
Parameters (see cURL example)
Header Parameters subjectid:SECURITY-TOKEN
Media Type (input) multipart/form-data
Results Task representation in supported MIME formats
Media Type (output) text/uri-list;application/rdf+xml;text/n3
Status code 200,202,400,401,402,403

Links: Page, Edit with form


cURL example

curl -X POST -H 'subjectid:TOKEN' -H 'Content-Type:multipart/form-data' -F 'filename=@FILE_NAME' \
             -d 'title=VALUE' -d 'anabstract=VALUE' -d 'author_uri=VALUE' -d 'author_uri=VALUE'  \
             -d 'keywords=VALUE' -d 'summarySearchable=VALUE' -d 'project_uri=Project URI' \
             -d 'organisation_uri=Organisation URI' -d 'user_uri=Owner User URI' \
             -d 'allowReadByUser=User URI' \
             http://toxbanktest1.opentox.org:8080/toxbank/protocol/SEURAT-Protocol-30-4/versions

Security

SEURAT-1 access

All SEURAT-1 members are allowed to upload protocols.

This is ensured by allowing POST and GET to http://services.toxbank.net/toxbank/protocol to the members of groups coach,scrtox,hemibio,notox,cosmos,toxbank,detective,sep.

The policies can be browsed here. A XACML policy template File:Policy-allconsortia.xml


Note: During the alpha test only a Principal Investigator (PI) is allowed to upload protocols. This was ensured by allowing POST and GET to http://toxbanktest1.opentox.org:8080/toxbank/protocol to the LDAP PI group members only. This is now changed!

Protocol read rights are specified on upload, and can be modified later by the protocol owner

Access levels, entered via GUI are translated into an OpenSSO policy by the protocol service. The following fields are added to the multipart web form, sent on PUT or POST. There could be more than one field of each type:

The protocol service reads the multipart web form, generates OpenAM XACML policy and sends it to the OpenTox policy service, upon successful POST or PUT operation. The old policy for the same URI is deleted.

The UI generates the web form fields as follows:

  • Only authors - Fills allowReadByUser fields with the authors URIs. The users are associated with the corresponding LDAP user names via tb:hasAccount
  • Consortium - Fills allowReadByGroup fields with the project URIs. The projects are associated with the corresponding LDAP groups via tb:hasAccount
  • SEURAT - Fills allowReadByGroup fields with all project URIs, which are defined as tb:subOrganisationOf SEURAT-1
  • Public - Fills allowReadByGroup field with the URI of a "Public" organisation. The public organisation is associated to the LDAP group "member"
  • Custom access - Fills allowReadByUser fields with selected user URIs
Only the protocol owner can update the protocol

The protocol service adds to the policy a rule, allowing full access for the protocol owner.


cURL example - Update the access rights only

$ curl -X PUT -H "subjectid:TOKEN" -H "Content-Type:multipart/form-data" \
--form "allowReadByUser=http://toxbanktest1.opentox.org:8080/toxbank/user/U1" http://toxbanktest1.opentox.org:8080/toxbank/protocol/SEURAT-Protocol-269-25 -iv

Note all update (PUT) and create (POST) examples use multipart/form-data, regardless of whether file is uploaded or not.

Implementation

RDF representation

Stable version

[2]

This RDF representation is automatically generated by the production version of the Toxbank Java client library

Alpha test version

[3]

This RDF representation is automatically generated by the alpha test version of the Toxbank Java client library

Development version

[4]

This RDF representation is automatically generated by the latest version of the Toxbank Java client library

Example in RDF/XML


<?xml version="1.0"?>
<!DOCTYPE rdf:RDF [
  <!ENTITY tb 'http://onto.toxbank.net/api/'>
  <!ENTITY foaf 'http://xmlns.com/foaf/0.1/'>
  <!ENTITY tbpl 'http://toxbanktest1.opentox.org:8080/toxbank/protocol/'>
  <!ENTITY SEURAT-Protocol-3-1 'http://toxbanktest1.opentox.org:8080/toxbank/protocol/SEURAT-Protocol-3-1/'>
  <!ENTITY tbo 'http://toxbanktest1.opentox.org:8080/toxbank/organisation/'>
  <!ENTITY xsd 'http://www.w3.org/2001/XMLSchema#'>
  <!ENTITY rdf 'http://www.w3.org/1999/02/22-rdf-syntax-ns#'>
  <!ENTITY tbpt 'http://toxbanktest1.opentox.org:8080/toxbank/project/'>
  <!ENTITY tbu 'http://toxbanktest1.opentox.org:8080/toxbank/user/'>
  <!ENTITY dcterms 'http://purl.org/dc/terms/'>]>
<rdf:RDF
    xmlns:SEURAT-Protocol-3-1="&SEURAT-Protocol-3-1;"
    xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
    xmlns:foaf="&foaf;"
    xmlns:tbo="&tbo;"
    xmlns:tbu="&tbu;"
    xmlns:dcterms="&dcterms;"
    xmlns:xsd="&xsd;"
    xmlns:tbpt="&tbpt;"
    xmlns:tbpl="&tbpl;"
    xmlns:tb="&tb;">
  <tb:Protocol rdf:about="&tbpl;SEURAT-Protocol-3-1">
    <tb:isSummarySearchable rdf:datatype="&xsd;boolean">true</tb:isSummarySearchable>
    <tb:hasProject>
      <tb:Project rdf:about="&tbpt;G2">
        <tb:subOrganisationOf rdf:resource="SEURAT-1"/>
        <tb:hasAccount rdf:datatype="&xsd;string">toxbank</tb:hasAccount>
        <dcterms:title rdf:datatype="&xsd;string">ToxBank</dcterms:title>
      </tb:Project>
    </tb:hasProject>
    <tb:hasKeyword rdf:datatype="&xsd;string">http://www.owl-ontologies.com/toxbank.owl/K347</tb:hasKeyword>
    <tb:hasKeyword rdf:datatype="&xsd;string">http://www.owl-ontologies.com/toxbank.owl/K258</tb:hasKeyword>
    <dcterms:dateSubmitted rdf:datatype="&xsd;long">1338406901000</dcterms:dateSubmitted>
    <dcterms:title rdf:datatype="&xsd;string">TDx/TDxFLx Acetaminophen assay</dcterms:title>
    <tb:hasOwner rdf:resource="&tbu;U115"/>
    <tb:hasVersionInfo rdf:datatype="&xsd;long">1</tb:hasVersionInfo>
    <tb:hasAuthor>
      <foaf:Person rdf:about="&tbu;U184">
        <foaf:holdsAccount>
          <foaf:OnlineAccount rdf:about="mailto:null">
            <foaf:accountServiceHomepage rdf:datatype="&xsd;string"
            >mailto</foaf:accountServiceHomepage>
          </foaf:OnlineAccount>
        </foaf:holdsAccount>
        <foaf:family_name rdf:datatype="&xsd;string">Peterson</foaf:family_name>
        <foaf:givenname rdf:datatype="&xsd;string">C.</foaf:givenname>
      </foaf:Person>
    </tb:hasAuthor>
    <dcterms:identifier rdf:datatype="&xsd;string">SEURAT-Protocol-3-1</dcterms:identifier>
    <tb:hasAbstract rdf:datatype="&xsd;string">The TDx/TDxFLx Acetaminophen assay is a reagent system for the
quantitative measurement of acetaminophen in human serum or plasma.
Measurements obtained are used in the diagnosis and treatment of
acetaminophen overdose.</tb:hasAbstract>
    <tb:hasDocument rdf:resource="&SEURAT-Protocol-3-1;document"/>
    <tb:isPublished rdf:datatype="&xsd;boolean">true</tb:isPublished>
    <tb:hasOrganisation>
      <tb:Organization rdf:about="&tbo;G274">
        <dcterms:title rdf:datatype="&xsd;string">Abbott</dcterms:title>
      </tb:Organization>
    </tb:hasOrganisation>
    <tb:hasStatus rdf:datatype="&xsd;string">SOP</tb:hasStatus>
    <dcterms:modified rdf:datatype="&xsd;long">1338475897000</dcterms:modified>
  </tb:Protocol>
</rdf:RDF>


Personal tools