Create Specimen Event

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

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

appData

formCtxtId	Identifies level at which form is associated.
objectId	Domain entity (specimen, visit or registration) object identifier for which form data entry is being made.
useUdn	Boolean specifying whether form fields in request are using user defined names

recordId

Identifies form record that is being updated. This parameter is used only when updating an already saved form data

field1

Form field name. Should be UDN when useUdn is set to true or auto-generated field name

field2

Another form field name. Should be UDN when useUdn is set to true or auto-generated field name

Example of request JSON (Cell Review Event)

{
  "appData":{
     "formCtxtId": 6,
     "objectId": 11632,
     "useUdn": true
  },
  "neoPlasticCellularityPct": "21",
  "viableCellPct": "12",
  "user": 1,
  "time": "10-29-2014 1:15",
  "comments": ""
}

Example of response JSON

"{
  \"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:

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
```
GET openspecimen/rest/ng/forms
```

List associations of form

GET openspecimen/rest/ng/forms/{formId}/contexts

Error codes

code	Applies to	Status Message
200	All resources	Form data 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