Specimen events in OpenSpecimen are modeled using DE forms. To create specimen event, please use DE form data save API as explained below:
| URI | openspecimen/rest/ng/forms/{formId}/data |
|---|
Use this resource to make data entry for specimen event in the openSpecimen application. Use HTTP POST method to call this API by passing the below details in JSON format. Here formId is the identifier of the event form for which user wants to perform the data entry.
Below are the attributes which need to be sent in the request body:
Parameter | Details | ||||||
|---|---|---|---|---|---|---|---|
| appData | data required to identify the form.
| ||||||
| user | Id of the user, who is performing this event | ||||||
| time | event time stamp | ||||||
| comments | Extra information which user wants to store with event creation. | ||||||
| other fields | Here comes all the event specific fields, like neoPlasticCellularityPct in case of Tissue Review Event. |
http[s]:<host>:<port>/openspecimen/rest/ng/forms/{formId}/data
Use this URL to make data entry for specimen event in openSpecimen application.
Result:
The response of this request will contains the details of the created participant.
Below is the example of the create Cell Review Event event:
| URL | http[s]:<host>:<port>/openspecimen/rest/ng/forms/{formId}/data | ||||||||||||||
| Method | POST | ||||||||||||||
| content-type | text/plain | ||||||||||||||
| Method | POST | ||||||||||||||
| json | { "appData":{ "formCtxtId":6, "objectId":11632 }, "neoPlasticCellularityPct":"21", "viableCellPct":"12", "user":1, "time":"10-29-2014 1:15", "comments":"" } | ||||||||||||||
| response | "{Description | Save or update DE form data. This API can be used to save data for forms associated at any level (Participant, SpecimenCollectionGroup, Specimen, and SpecimenEvent) | |||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| URI Parameters | formId - Identifier of DE form for which data is being saved or updated | ||||||||||||||
| HTTP Methods | POST: To save form data PUT: To update already saved form data | ||||||||||||||
Request Body |
|
Example of request JSON (Cell Review Event)
| Code Block |
|---|
{
"appData":{
"formCtxtId": 6,
"objectId": 11632,
"useUdn": true
},
"neoPlasticCellularityPct": "21",
"viableCellPct": "12",
"user": 1,
"time": "10-29-2014 1:15",
"comments": ""
} |
Example of response JSON
| Code Block |
|---|
"{ \"id\":14313, |
...
\"time\":\"10-29-2014 1:15\", |
...
\"appData\":{ \"formCtxtId\":6.0, \"objectId\":11632.0 }, |
...
\"neoPlasticCellularityPct\":\"21\", |
...
\"user\":1.0, |
...
\"viableCellPct\":\"12\", |
...
\"containerId\":6, |
...
\"comments\":\"\" }" |
Download the sample Java client from here.
NOTE:
To get the formId and formCtxId, execute the below SQL query:
| Code Block |
|---|
select c.name as formName, c.identifier as formId, ctx.identifier as formCtxId, ctx.entity_type as level, cp.title as cp from dyextn_containers c inner join catissue_form_context ctx on ctx.container_id = c.identifier left join catissue_collection_protocol cp on cp.identifier = ctx.cp_id where c.caption = '<form display name>' |
In above SQL form display name refers to caption that user sees in Manage Forms or form data entry view
An alternative to using SQL is using below APIs
List forms available for data entry
Code Block GET openspecimen/rest/ng/formsList associations of form
...
Code Block GET openspecimen/rest/ng/forms/{formId}/contexts
Error codes
code | Applies to | Status Message |
|---|---|---|
| 200 | All resources | Event Form data inserted saved successfully |
| 400 | All requests | Invalid parameters, e.g invalid user etc |
| 401 | All requests | Authorization failed, User doesn’t have privileges to register create events |
| 500 | All requests | Internal server error, Encountered server error while performing operations |
...