Protocol
(→Implementation) |
(→Protocol read rights are specified on upload, and can be modified later by the protocol owner) |
||
Line 118: | Line 118: | ||
The UI generates the web form fields as follows: | 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] | + | *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] | *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] | *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] |
Revision as of 15:28, 19 April 2012
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]
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:application/x-www-form-urlencoded' -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' \ http://toxbanktest1.opentox.org:8080/toxbank/protocol/SEURAT-Protocol-30-4/versions
Security
Only a Principal Investigator (PI) is allowed to upload protocols
This is ensured by allowing POST and PUT to http://toxbanktest1.opentox.org:8080/toxbank/protocol to the LDAP PI group members only. The policies can be browsed here.
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 consortium or organisation.
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.
Implementation
- Generates XML policy, (without sending), part of the Java OpenTox AA client;
- Java beans for access rights and policy rules;
- Java Client, communicating with the policy service.
RDF representation
This RDF representation is automatically generated by the latest version of the Toxbank Java client library