Create Specimen

POST openspecimen/rest/ng/specimens

This API is used to create specimen for particular visit under participant. Using this API the specimen is also collected while creation.

Parameter Details:

The API accepts the specimen details in JSON format with following parameters:

Parameter

Details

label

Label given to specimen

specimenClass

Class of the specimen.

type

Specimen type of specimen. The specimen type should belong to specimen class.

pathology

Pathology status of specimen.

anatomicSite

Anatomic site of the specimen.

laterality

Laterality of the specimen.

initialQty

Initial quantity of the specimen.

availableQty

Available quantity of the specimen.

lineage

Lineage of the specimen. For new specimen the value would be "New".

visitId

Visit ID of the participant under which the specimen will be collected.

status

Status of the specimen. For collecting specimen the value would be "Collected".

storageLocation [optional]

Storage location to store the created specimen.

The location detail is also a JSON object, which contains :

name	Name of Container
positionX [optional]	X Position in container
positionY [optional]	Y Position in container

As Position is optional, If not given then specimen will be stored virtually.
If only container name is given then first available position will be allocated in specified container.If position is not available then throws error message.

concentration [optional]

Concentration of specimen.

biohazards [optional]

Biohazards of that specimen.

comments [optional]

Comments for that specimen.

collectionEvent

This is the JSON object containing the details of collection event.

It has below parameters:

user : The user who is creating the specimen. This is JSON object containing user details.
time : The timestamp on which the specimen is collected.
container [optional] : This is the container type in which the specimen will be collected.
procedure [optional] : The procedure of collecting the specimen.

receivedEvent

This is the JSON object containing the details of received event.

It has below parameters :

user : The user who received the specimen. This is JSON object containing user details.
time : Timestamp when specimen is received.
receivedQuality : Quality of specimen when it is received.

extensionDetail [optional]

This is the JSON object containing the details of custom-fields.

It has the below parameters:

useUdn: This allows the usage of attributes UDN name.
attrsMap: This is a map of the attribute name-value.

Result :

Response of this request contains the details of specimen.

API Example:

URL	openspecimen/rest/ng/specimens
Request type	application/json
Method	POST
json	{ "lineage":"New", "visitId":1, "status":"Collected", "availableQty":"10", "storageLocation":{}, "collectionEvent":{ "user":{ "id":1, "firstName":"Admin", "lastName":"Admin", "loginName":"admin@admin.com", "domain":"openspecimen", "emailAddress":"admin@admin.com", "admin":true,"cpCount":0, "creationDate":null }, "time":"2015-12-04T04:14:36.333Z", "container":"Not Specified", "procedure":"Not Specified" }, "receivedEvent":{ "user":{ "id":1, "firstName":"Admin", "lastName":"Admin", "loginName":"admin@admin.com", "domain":"openspecimen", "emailAddress":"admin@admin.com", "admin":true, "cpCount":0, "creationDate":null }, "time":"2015-12-04T04:14:36.333Z", "receivedQuality":"Acceptable" }, "initialQty":"10", "concentration":"", "label":"unplanned specimen 1", "specimenClass":"Fluid", "type":"Bone Marrow Plasma", "pathology":"Non-Malignant, Diseased", "anatomicSite":"External ear", "laterality":"Right", "extensionDetail": { "useUdn": true, "attrsMap": { "usb_ext_lab_number": "Ext_Lab_UK_12342", "visited": ["India", "USA"] } } }
Response	{ "id": 9, "cpId": 1, "cprId": 1, "eventId": null, "visitId": 1, "visitName": "first visit", "cpShortTitle": "blood", "reqId": null, "sortOrder": null, "label": "unplanned specimen 1", "barcode": null, "type": "Bone Marrow Plasma", "specimenClass": "Fluid", "lineage": "New", "anatomicSite": "External ear", "laterality": "Right", "status": "Collected", "reqLabel": null, "pathology": "Non-Malignant, Diseased", "initialQty": 10, "availableQty": 10, "available": true, "concentration": null, "parentId": null, "parentLabel": null, "storageLocation": { "id": -1, "name": null, "positionX": null, "positionY": null }, "storageType": null, "collectionContainer": null, "activityStatus": "Active", "createdOn": 1449202440000, "code": null, "distributed": null, "collectionEvent": null, "receivedEvent": null, "labelFmt": null, "biohazards": [], "comments": null, "closeAfterChildrenCreation": null, "children": [], "pooledSpecimenId": null, "pooledSpecimenLabel": null, "specimensPool": null, "closeParent": null, "poolSpecimen": null, "extensionDetail": { "id": 1302, "objectId": 850, "formId": 201, "formCaption": "External Fields", "attrs": [{ "name": "ST3", "udn": "usb_ext_lab_number", "caption": "External Laboratory Number", "value": "Ext_Lab_UK_12342", "type": "stringTextField", "displayValue": "Ext_Lab_UK_12342" }, { "name": "MLB4", "udn": "visited", "caption": "Visited", "value": ["India", "USA"], "type": "multiSelectListbox", "displayValue": "India, USA" }], "useUdn": false } }

Error Cases :

code	Applies to	Status Message
200	All resources	Specimen has been created successfully
400	All requests	Invalid parameters, e.g duplicate label, invalid class Name etc
401	All requests	Authorization failed, User doesn’t have Authority to create specimen for the given visit.
500	All requests	Internal server error, Encountered server error while performing operations