Page Comparison

openspecimen/rest/ng/collection-protocols

Use this resource to create new collection protocol in the openSpecimen application. Use HTTP POST method to call this API by passing the below details in JSON format.

Below are the attributes which need to be sent in the request body:

Parameter

Details

title Collection protocol title. Should be unique in the application

shortTitle

Collection protocol short title. Should be unique in the application

code[optional] Collection protocol code

startDate Collection protocol starting date

endDate[optional] Collection protocol end date. If given then, the endDate should not be later than start date.

principalInvestigator

Principal investigator of CP

Mainly contains following parameters :

loginName : User login name. For this specified user must be present in application.

domainName: Name of domain to which user belongs to. By default it will be catissue.

coordinators [optional]

Collection of coordinators. It is collection of user info mainly contains following parameters :

loginName : User login name. For this specified user must be present in application.

domainName: Name of domain to which user belongs to. By default it will be catissue.

irbId[optional]

anticipatedParticipantsCount[optional] Anticipated participants count

activityStatus Activity status of a collection protocol

visitNameFmt[optional] Visit name format

specimenLabelFmt[optional] Specimen label format

derivedLabelFormat[optional] Derived label format

aliquotLabelFormat[optional] Aliquot label format

ppIdFormat[optional] PPId format

cpSites Sites

events[optional]

It is collection of collection protocol event details

Mainly contains following parameters :

collectionPointLabel Collection point label. It should be unique in CP

studyCalendarEventPoint[optional] Study calendar event point

labelFormat[optional] Collection protocol event label format

activityStatus Activity status of collection protocol event

defaultSiteName [optional] Site name

specimenRequirementDetails [optional]

It is collection of specimen requirement details

Mainly contains following parameters :

collectionTimestamp [optional]	Collection timestamp
collector [optional]	Collector of specimen Mainly contains following parameters : loginName : User login name. For this specified user must be present in application. domainName: Name of domain to which user belongs to. By default it will be catissue.
collectionComments[optional]	Comments while collecting specimen
collectionProcedure[optional]	Collection procedure
collectionContainer[optional]	Collection container
receivedQuality[optional]	Received quality
receivedTimestamp[optional]	Received Timestamp
receiver[optional]	Receiver of specimen Mainly contains following parameters : loginName : User login name. For this specified user must be present in application. domainName: Name of domain to which user belongs to. By default it will be catissue.
receivedComments[optional]	Comments while receiving specimen
childSpecimenRequirementCollection[optional]	Collection of the child specimen requirements
tissueSite[optional]	Tissue site
tissueSide[optional]	Tissue side
pathologicalStatus[optional]	Pathological Status
lineage[optional]	Lineage, Should be `New` if the specimen requirement doesn't have parrent
initialQuantity[optional]	Initial quantity
specimenClass[optional]	Specimen class
specimenType[optional]	Specimen type
labelFormat[optional]	Label format for specimen requirement
specimenRequirementLabel[optional]	Label for specimen requirement
activityStatus[optional]	Activity status of specimen requirement

cpSiteRoles[optional]

It is collection of Sites and Roles with respect to CP. By default it will be none. i.e. Blank collection.

Mainly contains following parameters :

roleName : Role of user like Scientist, Admin etc. For this attribute role must be present in application.

siteName: Site name. For this attribute Site must be present in application.

http[s]:<host>:<port>/openspecimen/rest/ng/collection-protocols

Use this URL to add collection protocol in openSpecimen application.

Result:

The response of this request will contains the details of the created collection protocol.

Below is the example of the create collection protocol:

...

Response

{

id: 158

title: "LiverCancer Study"

shortTitle: "LCS"

cpType: "Parent"

startDate: 1391299200000

endDate: null

activityStatus: "Active"

labelFormat: null

derivedLabelFormat: null

aliquotLabelFormat: null

ppIdFormat: null

cpeDetails:

{

id: 1038

collectionPointLabel: "First Follow-up"

studyCalendarEventPoint: null

labelFormat: null

activityStatus: "Active"

defaultSiteName: null

specimenRequirementDetails:

{

id: 14295

collectionTimestamp: 1410480000000

collector:

{

loginName: "admin@admin.com"

domainName: "catissue"

}

collectionComments: null

collectionProcedure: "Needle Aspirate"

collectionContainer: "Frizeer"

receivedQuality: "Acceptable"

receivedTimestamp: null

receiver:

{

loginName: "admin@admin.com"

domainName: "catissue"

}

receivedComments: null

collectionProtocolEvent: null

childSpecimenRequirementCollection:

{

id: 14296

collectionTimestamp: 1410480000000

collector:

{

loginName: "admin@admin.com"

domainName: "catissue"

}

collectionComments: null

collectionProcedure: "Needle Aspirate"

collectionContainer: "container"

receivedQuality: "Acceptable"

receivedTimestamp: null

receiver:

{

loginName: "admin@admin.com"

domainName: "catissue"

}

receivedComments: null

collectionProtocolEvent: null

childSpecimenRequirementCollection:

[0]

tissueSite: null

tissueSide: null

pathologicalStatus: null

lineage: "Aliquot"

initialQuantity: null

specimenClass: null

specimenType: null

labelFormat: null

specimenRequirementLabel: null

activityStatus: "Active"

}

tissueSite: null

tissueSide: null

pathologicalStatus: null

lineage: "New"

initialQuantity: null

specimenClass: null

specimenType: null

labelFormat: null

specimenRequirementLabel: null

activityStatus: "Active"

}

coordinators:

[0 ]

investigator:

{

loginName: "admin@admin.com"

domainName: "catissue"

}

...

openspecimen/rest/ng/collection-protocols

Use this resource to create new collection protocol in the openSpecimen application. Use HTTP POST method to call this API by passing the below details in JSON format.

Below are the attributes which need to be sent in the request body:

Parameter	Details
title	Full title of the collection protocol, which is normally used in the regulatory approval documents.
shortTitle	User friendly short string to uniquely identify the collection protocol.
code [optional]	A short code to uniquely identify the CP in the system.
startDate [optional]	Collection protocol starting date
endDate [optional]	Collection protocol end date. If given then, the endDate should be later than start date.
principalInvestigator	Principal investigator of CP Mainly contains following parameters : loginName : User login name. For this specified user must be present in application. domainName: Name of domain to which user belongs to. By default it will be catissue.
coordinators [optional]	Collection of coordinators. It is collection of user info mainly contains following parameters : loginName : User login name. For this specified user must be present in application. domainName: Name of domain to which user belongs to. By default it will be catissue.
irbId [optional]	Ethics approval id
anticipatedParticipantsCount [optional]	Anticipated participants count. This is ignored for specimen centric CPs.
activityStatus	Activity status of a collection protocol
visitNameFmt [optional]	Visit name format. This is ignored for specimen centric CPs.
specimenLabelFmt [optional]	Specimen label format
derivedLabelFormat [optional]	Derived label format
aliquotLabelFormat [optional]	Aliquot label format
ppidFmt [optional]	PPID format. This is ignored for specimen centric CPs.
cpSites	Array of sites at which the collection protocol is being run or active. Mainly contains following parameters : siteName: Site name. code[optional]: Site code
manualPpidEnabled [optional]	When enabled, users have to manually enter the participant PPID.
manualVisitNameEnabled [optional]	When enabled, users have to manually enter the visit names.
manualSpecLabelEnabled [optional]	When enabled, users have to manually enter the specimen (primary, derived, aliquot) labels.
specimenCentric	Boolean indicating whether the CP is participant or specimen centric. When the value of this attribute is null or false, a participant centric CP is created. However, when the value is true, a specimen centric CP is created. Note: This flag is effective only when a CP is being created. The value of this attribute is ignored in the CP update APIs. In other words, a participant centric CP cannot be converted to specimen centric and vice-versa.

http[s]:<host>:<port>/openspecimen/rest/ng/collection-protocols

Use this URL to add collection protocol in openSpecimen application.

Result:

The response of this request will contains the details of the created collection protocol.

Below is the example of the create collection protocol:

URL	`http://<host>:<port>/`openspecimen/rest/ng/collection-protocols
Method	POST
Request	application/json
json	{ "shortTitle": "A Planned Clinical Study FD", "title": "Planned Clinical Study", "code": null, "principalInvestigator": { "loginName": "admin@admin.com", "domain": "openspecimen" }, "startDate": 1427653800000, "endDate": 1454178600000, "ppidFmt": "DWP%05d", "manualPpidEnabled": false, "coordinators": [], "cpSites": [ { "siteName": "Arkansas Repository", "code": "CS_123" }, { "siteName": "Arkansas Hospital", "code": "CS_34" } ], "consentsWaived": false, "irbId": "65465", "anticipatedParticipantsCount": null, "descriptionUrl": null, "specimenLabelFmt": "%PPI%.%SP_TYPE%.%SYS_UID%", "derivativeLabelFmt": "%PPI%.%SP_TYPE%.%SYS_UID%", "aliquotLabelFmt": "%PSPEC_LABEL%.%PSPEC_UID%", "visitNameFmt": null, "manualVisitNameEnabled": false, "manualSpecLabelEnabled": true, "aliquotsInSameContainer": null, "activityStatus": "Active" }
Response	{ "id": 2, "shortTitle": "A Planned Clinical Study FD", "title": "Planned Clinical Study", "code": null, "principalInvestigator": { "id": 1, "firstName": "Admin", "lastName": "Admin", "loginName": "admin@admin.com", "domain": "openspecimen", "emailAddress": "openspecimendemo@gmail.com", "admin": true, "cpCount": 0, "creationDate": null }, "startDate": 1427653800000, "endDate": 1454178600000, "participantCount": null, "specimenCount": null, "ppidFmt": "DWP%05d", "manualPpidEnabled": false, "coordinators": [], "cpSites": [ { "id": 2, "siteName": "Arkansas Repository", "code": "CS_123" }, { "id": 25, "siteName": "Arkansas Hospital", "code": "CS_34" } ], "consentsWaived": false, "irbId": "65465", "anticipatedParticipantsCount": null, "descriptionUrl": null, "specimenLabelFmt": "%PPI%.%SP_TYPE%.%SYS_UID%", "derivativeLabelFmt": "%PPI%.%SP_TYPE%.%SYS_UID%", "aliquotLabelFmt": "%PSPEC_LABEL%.%PSPEC_UID%", "visitNameFmt": null, "manualVisitNameEnabled": false, "manualSpecLabelEnabled": true, "aliquotsInSameContainer": null, "activityStatus": "Active", "consents": null, "events": null }

Error Cases :

code	Applies to	Status Message
200	All resources	Collection Protocol has been created successfully
400	All requests	Invalid parameters, e.g duplicate CP title, blank CP title etc
401	All requests	Authorization failed, user doesn’t have authority
500	All requests	Internal server error, encountered server error while performing operations

...

Versions Compared

Old Version 10

New Version Current

Key