Introduction You have the flexibility to customize the derivative/aliquot page according to specific criteria. This customization enables you to remove unnecessary fields from the derivative/aliquot pages.
In OpenSpecimen, you have the option to tailor the derivative/aliquot page settings at both the 'Collection Protocol' level and the 'System Level'.
Protocol-level configuration To configure the derivative/aliquot page for a particular collection protocol, utilize CP level workflow JSON.
Refer to the 'Protocol Level Configuration' page to set the JSON file to the specific CP.
Derivative Page Configuration To set up the derivative page, users should include the "derivedSpecimens" section within the "data" block specified in the JSON below.
Click here to expand...
Example: In the below example, the specified fields like 'Parent Label', 'Type', 'Derived Type', 'Yield' etc. fields only displayed when you create the derived specimen from the 'Tissue' type sample.
JSON code
{
"name": "common",
"view": null,
"ctrl": null,
"data": {
"derivedSpecimens":[
{
"title" : "Create Derivative: Solid Tissue",
"criteria": {
"op": "AND",
"rules": [{
"field": "specimen.parent.id",
"op": "exists"
},
{
"field": "specimen.parent.specimenClass",
"op": "==",
"value": "'Tissue'"
}
]
},
"enableCofrc" : false,
"fields" : [
{
"name": "specimen.parent.label",
"caption": "Parent Specimen",
"type": "span",
"url": "specimen({specimenId: specimen.parent.id})"
},
{
"name": "specimen.parent.type",
"caption": "Specimen Type",
"type": "span"
},
{
"name": "specimen.type",
"caption": "Derivative Type",
"type" : "specimen-type",
"specimen" : "specimen",
"optional": false,
"width": "170px"
},
{
"name": "specimen.concentration",
"caption": "Concentration",
"type": "specimen-quantity",
"specimen" : "specimen",
"measure": "concentration",
"optional": true,
"width": "120px"
},
{
"name": "specimen.extensionDetail.attrsMap.ST15",
"baseField": "specimen.extensionDetail.attrsMap.ST15",
"width": "80px"
},
{
"name": "specimen.initialQty",
"caption": "Volume",
"type" : "specimen-quantity",
"specimen": "specimen",
"optional": true,
"width": "80px"
},
{
"name": "specimen.extensionDetail.attrsMap.ST16",
"baseField": "specimen.extensionDetail.attrsMap.ST16",
"width": "90px"
},
{
"name": "specimen.extensionDetail.attrsMap.ST17",
"baseField": "specimen.extensionDetail.attrsMap.ST17",
"width": "90px"
},
{
"name": "specimen.storageLocation",
"caption": "Location",
"type" : "storage-position",
"optional": true,
"cpId": "specimen.cpId",
"entity": "specimen",
"width": "240px",
"copyValueFn": "function(firstRowVal, currentVal) { if ((!!currentVal && !!currentVal.reservationId) && (!!firstRowVal && !!firstRowVal.reservationId)) { return currentVal;} else if (firstRowVal) { return { id: '', name: firstRowVal.name, mode: firstRowVal.mode, positionX: '', positionY: '', position: '', reservationId: '' };} else { return {}; }}"
},
{
"name": "specimen.printLabel",
"caption": "Print",
"icon": "fa fa-print",
"type": "toggle-checkbox",
"width": "30px"
},
{
"name": "specimen.closeParent",
"caption": "Close Parent",
"icon": "fa fa-ban",
"type": "toggle-checkbox",
"width": "30px",
"defaultValue": true /*Close parent sample checkbox configuration, checked when set to true, unchecked when set to false
}
]
},
{
"title" : "Create Derivative: Biofluid",
"criteria": {
"op": "AND",
"rules": [{
"field": "specimen.parent.id",
"op": "exists"
},
{
"field": "specimen.parent.specimenClass",
"op": "==",
"value": "'Fluid'"
}
]
},
"enableCofrc" : false,
"fields" : [
{
"name": "specimen.parent.label",
"caption": "Parent Specimen",
"type": "span",
"url": "specimen({specimenId: specimen.parent.id})"
},
{
"name": "specimen.parent.type",
"caption": "Specimen Type",
"type": "span"
},
{
"name": "specimen.extensionDetail.attrsMap.DD11",
"baseField": "specimen.extensionDetail.attrsMap.DD11",
"width": "120px"
},
{
"name": "specimen.type",
"caption": "Derivative Type",
"type" : "specimen-type",
"specimen" : "specimen",
"optional": false,
"width": "170px"
},
{
"name": "specimen.initialQty",
"caption": "Volume",
"type" : "specimen-quantity",
"specimen": "specimen",
"optional": true,
"width": "80px"
},
{
"name": "specimen.concentration",
"caption": "Concentration",
"type": "specimen-quantity",
"specimen" : "specimen",
"measure": "concentration",
"optional": true,
"width": "120px"
},
{
"name": "specimen.extensionDetail.attrsMap.DD24",
"baseField": "specimen.extensionDetail.attrsMap.DD24",
"width": "150px"
},
{
"name": "specimen.extensionDetail.attrsMap.DP25",
"baseField": "specimen.extensionDetail.attrsMap.DP25",
"width": "150px",
"type" : "date",
"optional" : true
},
{
"name": "specimen.printLabel",
"caption": "Print",
"icon": "fa fa-print",
"type": "toggle-checkbox",
"width": "30px"
},
{
"name": "specimen.closeParent",
"caption": "Close Parent",
"icon": "fa fa-ban",
"type": "toggle-checkbox",
"width": "30px",
"defaultValue": true
}
]
}
]
}
}
Screenshot: Create a derivative page after JSON configured columns.
Aliquot Page Configuration To set up the aliquot page, users should include the "aliquotsCollection" section within the "data" block specified in the JSON snippet below.
Example: In the below example, the specified fields like 'Parent Label', 'Type', 'Tissue Status', 'Length' etc., are displayed only when you create the aliquot from the 'Tissue' type sample.
JSON code
{
"name": "common",
"view": null,
"ctrl": null,
"data": {
"aliquotsCollection": [{
"title": "Aliquots",
"criteria": {
"op": "AND",
"rules": [{
"field": "specimen.parent.id",
"op": "exists"
},
{
"field": "specimen.specimenClass",
"op": "==",
"value": "'Tissue'"
}
]
},
"enableCofrc": false,
"fields": [
{
"name": "specimen.parent.label",
"caption": "Parent Specimen",
"type": "span",
"url": "specimen({specimenId: specimen.parent.id})"
},
{
"name": "specimen.parent.availableQty",
"caption": "Parent Quantity",
"type": "span",
"width": "120px"
},
{
"name": "specimen.type",
"caption": "Type",
"type" : "specimen-type",
"specimen" : "specimen",
"optional": false,
"width": "185px"
},
{
"name": "specimen.noOfAliquots",
"caption": "Count",
"type": "text",
"pattern" : "/^[1-9][0-9]*$/",
"modelOpts": {"allowInvalid": true},
"optional": true,
"width": "80px",
"showIf": {
"tabMode": true,
"op": "OR",
"rules": [
{
"field": "viewCtx.inputLabels",
"op": "==",
"value": "false"
}
]
}
},
{
"name": "specimen.labels",
"caption": "Labels",
"type": "textarea",
"optional": false,
"showIf": {
"tabMode": true,
"op": "OR",
"rules": [
{
"field": "viewCtx.inputLabels",
"op": "==",
"value": "true"
}
]
},
"copyValueFn" : "function(firstRowVal, currentVal) { if (!!currentVal) { return currentVal; } else { return ''; } }"
},
{
"name": "specimen.qtyPerAliquot",
"caption": "Quantity",
"type" : "specimen-quantity",
"specimen": "specimen",
"optional": true,
"width": "100px"
},
{
"name": "specimen.createdOn",
"caption" : "Created On",
"type" : "date",
"optional" : true,
"defaultValue" : "current_date"
},
{
"name": "specimen.createdBy",
"caption": "Created By",
"type": "user",
"defaultValue": "current_user",
"optional": true,
"listSource": {
"queryParams": {
"static": {
"excludeType": "CONTACT"
}
}
}
},
{
"name": "specimen.extensionDetail.attrsMap.DD2",
"baseField": "specimen.extensionDetail.attrsMap.DD2",
"optional": false
},
{
"name": "specimen.storageLocation",
"caption": "Location",
"type" : "storage-position",
"optional": true,
"cpId": "specimen.cpId",
"entity": "specimen",
"width": "240px",
"copyValueFn": "function(firstRowVal, currentVal) { if ((!!currentVal && !!currentVal.reservationId) && (!!firstRowVal && !!firstRowVal.reservationId)) { return currentVal;} else if (firstRowVal) { return { id: '', name: firstRowVal.name, mode: firstRowVal.mode, positionX: '', positionY: '', position: '', reservationId: '' };} else { return {}; }}"
},
{
"name": "specimen.printLabel",
"caption": "Print",
"icon": "fa fa-print",
"type": "toggle-checkbox",
"width": "30px"
},
{
"name": "specimen.closeParent",
"caption": "Close Parent",
"icon": "fa fa-ban",
"type": "toggle-checkbox",
"width": "30px",
"defaultValue": false
}
]
}]
}
}
Screenshot : Create an aliquot page after JSON-configured columns
System-level configuration Refer to the 'System-Level Configuration ' page to set the System-Level Workflow.
Once the derivative or aliquot is configured at the system level, it impacts all collection protocols within OpenSpecimen.
When choosing specimens from multiple collection protocols in the cart view or any other interface and then selecting "Create Aliquots" or "Create Derivatives," a customizable table containing derivative or aliquot data is shown. This table is visible exclusively if the Specimen Data Extension (SDE) is enabled and derivative or aliquot fields are set up at the system level.
JSON code
[
{
"name": "common",
"view": null,
"ctrl": null,
"data": {
"derivedSpecimens":[
{
"title" : "Create Derivative: Solid Tissue",
"criteria": {
"op": "AND",
"rules": [{
"field": "specimen.parent.id",
"op": "exists"
},
{
"field": "specimen.parent.specimenClass",
"op": "==",
"value": "'Tissue'"
}
]
},
"enableCofrc" : false,
"fields" : [
{
"name": "specimen.parent.label",
"caption": "Parent Specimen",
"type": "span",
"url": "specimen({specimenId: specimen.parent.id})"
},
{
"name": "specimen.parent.type",
"caption": "Specimen Type",
"type": "span"
},
{
"name": "specimen.type",
"caption": "Derivative Type",
"type" : "specimen-type",
"specimen" : "specimen",
"optional": false,
"width": "170px"
},
{
"name": "specimen.concentration",
"caption": "Concentration",
"type": "specimen-quantity",
"specimen" : "specimen",
"measure": "concentration",
"optional": true,
"width": "120px"
},
{
"name": "specimen.extensionDetail.attrsMap.ST15",
"baseField": "specimen.extensionDetail.attrsMap.ST15",
"width": "80px"
},
{
"name": "specimen.initialQty",
"caption": "Volume",
"type" : "specimen-quantity",
"specimen": "specimen",
"optional": true,
"width": "80px"
},
{
"name": "specimen.extensionDetail.attrsMap.ST16",
"baseField": "specimen.extensionDetail.attrsMap.ST16",
"width": "90px"
},
{
"name": "specimen.extensionDetail.attrsMap.ST17",
"baseField": "specimen.extensionDetail.attrsMap.ST17",
"width": "90px"
},
{
"name": "specimen.storageLocation",
"caption": "Location",
"type" : "storage-position",
"optional": true,
"cpId": "specimen.cpId",
"entity": "specimen",
"width": "240px",
"copyValueFn": "function(firstRowVal, currentVal) { if ((!!currentVal && !!currentVal.reservationId) && (!!firstRowVal && !!firstRowVal.reservationId)) { return currentVal;} else if (firstRowVal) { return { id: '', name: firstRowVal.name, mode: firstRowVal.mode, positionX: '', positionY: '', position: '', reservationId: '' };} else { return {}; }}"
},
{
"name": "specimen.printLabel",
"caption": "Print",
"icon": "fa fa-print",
"type": "toggle-checkbox",
"width": "30px"
},
{
"name": "specimen.closeParent",
"caption": "Close Parent",
"icon": "fa fa-ban",
"type": "toggle-checkbox",
"width": "30px",
"defaultValue": true
}
]
},
{
"title" : "Create Derivative: Biofluid",
"criteria": {
"op": "AND",
"rules": [{
"field": "specimen.parent.id",
"op": "exists"
},
{
"field": "specimen.parent.specimenClass",
"op": "==",
"value": "'Fluid'"
}
]
},
"enableCofrc" : false,
"fields" : [
{
"name": "specimen.parent.label",
"caption": "Parent Specimen",
"type": "span",
"url": "specimen({specimenId: specimen.parent.id})"
},
{
"name": "specimen.parent.type",
"caption": "Specimen Type",
"type": "span"
},
{
"name": "specimen.type",
"caption": "Derivative Type",
"type" : "specimen-type",
"specimen" : "specimen",
"optional": false,
"width": "170px"
},
{
"name": "specimen.initialQty",
"caption": "Volume",
"type" : "specimen-quantity",
"specimen": "specimen",
"optional": true,
"width": "80px"
},
{
"name": "specimen.concentration",
"caption": "Concentration",
"type": "specimen-quantity",
"specimen" : "specimen",
"measure": "concentration",
"optional": true,
"width": "120px"
},
{
"name": "specimen.printLabel",
"caption": "Print",
"icon": "fa fa-print",
"type": "toggle-checkbox",
"width": "30px"
},
{
"name": "specimen.closeParent",
"caption": "Close Parent",
"icon": "fa fa-ban",
"type": "toggle-checkbox",
"width": "30px",
"defaultValue": true
}
]
}
],
"aliquotsCollection": [{
"title": "Aliquots",
"criteria": {
"op": "AND",
"rules": [{
"field": "specimen.parent.id",
"op": "exists"
},
{
"field": "specimen.specimenClass",
"op": "==",
"value": "'Tissue'"
}
]
},
"enableCofrc": false,
"fields": [{
"name": "specimen.parent.label",
"caption": "Parent Specimen",
"type": "span",
"url": "specimen({specimenId: specimen.parent.id})"
},
{
"name": "specimen.type",
"baseField": "specimen.type"
},
{
"name": "specimen.extensionDetail.attrsMap.DD20",
"baseField": "specimen.extensionDetail.attrsMap.DD20"
},
{
"name": "specimen.noOfAliquots",
"caption": "Aliquots Count",
"type": "text"
},
{
"name": "specimen.qtyPerAliquot",
"baseField": "specimen.initialQty"
},
{
"name": "specimen.extensionDetail.attrsMap.NT21",
"baseField": "specimen.extensionDetail.attrsMap.NT21"
},
{
"name": "specimen.extensionDetail.attrsMap.NT22",
"baseField": "specimen.extensionDetail.attrsMap.NT22"
},
{
"name": "specimen.extensionDetail.attrsMap.NT23",
"baseField": "specimen.extensionDetail.attrsMap.NT23"
},
{
"name": "specimen.storageLocation",
"baseField": "specimen.storageLocation",
"caption": "Location"
},
{
"name": "specimen.printLabel",
"caption": "Print",
"icon": "fa fa-print",
"type": "toggle-checkbox",
"width": "30px"
},
{
"name": "specimen.closeParent",
"caption": "Close Parent",
"icon": "fa fa-ban",
"type": "toggle-checkbox",
"width": "30px"
}
]
}]
}
}
]
Screenshot: Create derivatives and aliquots from the cart page
Screenshot : Cart view page → Create Derivative Page
Screenshot : Cart view page → Create Aliquot Page
Extra features 1. Hide the 'Copy first to all' link on both pages A 'Copy first to all' button is available on the aliquots and derivatives pages, enabling users to quickly create similar aliquots and derivatives simultaneously. However, some users may find this feature unnecessary since similar children are typically generated in a single row, making the 'Copy first to all' function confusing.
Starting from version 6.0, it is possible to conceal the 'Copy first to all' button on derived or aliquot pages. To achieve this, you can implement the following setting in JSON within the aliquotsCollection and derivedSpecimens sections.
In version 11, the functionality to hide 'Copy First To All' is not available.
{
...
"aliquotsCollection": [
...
{
"title": ...,
...,
"hideCopyFirstToAll": true
...
},
...
],
"derivedSpecimens": [
...
{
"title": ...,
...,
"hideCopyFirstToAll": true
...
},
...
],
...
} Before configuring the JSON, the "Copy first to all" button is present on the Create derivative page:
After configuring the JSON, "Copy first to all" button is hidden on Create derivative page:
After configuring the JSON, the "Copy first to all" button is hidden on the Create aliquot page:
2. Add the ability to create aliquots from the 'Create Derivatives' page An option has been added to enable users to generate aliquots while creating unplanned derivatives. By default, the system workflow includes this option.
For customized CP workflows, the following JSON can be incorporated into the "derivedSpecimens" workflow to activate this feature:
Code:
{
"name": "specimen.createAliquots",
"caption": "Create Aliquots?",
"icon": "fa fa-share-alt",
"type": "toggle-checkbox",
"width": "30px"
}
Example JSON
Click here to expand...
{
"name" : "common",
"view" : null,
"ctrl" : null,
"data" : {
"derivedSpecimens" : [ {
"title" : "Derived Specimens",
"criteria" : {
"rules" : [ {
"field" : "specimen.parent.id",
"op" : "exists"
} ]
},
"enableCofrc" : false,
"fields" : [ {
"name" : "specimen.parent.label",
"caption" : "Parent Specimen",
"type" : "span",
"url" : "specimen({specimenId: specimen.parent.id})"
}, {
"name" : "specimen.parent.type",
"caption" : "Parent Type",
"type" : "span"
}, {
"name" : "specimen.label",
"caption" : "Label",
"type" : "text",
"optional" : false,
"showIf" : {
"tabMode" : true,
"op" : "OR",
"rules" : [ {
"field" : "viewCtx.inputLabels",
"op" : "==",
"value" : "true"
} ]
},
"copyValueFn" : "function(firstRowVal, currentVal) { if (!!currentVal) { return currentVal; } else { return ''; } }"
}, {
"name" : "specimen.parent.availableQty",
"caption" : "Parent Quantity",
"type" : "span",
"width" : "120px"
}, {
"name" : "specimen.type",
"caption" : "Type",
"type" : "specimen-type",
"specimen" : "specimen",
"optional" : false,
"width" : "185px"
}, {
"name" : "specimen.initialQty",
"caption" : "Quantity",
"type" : "specimen-quantity",
"specimen" : "specimen",
"optional" : true,
"width" : "100px"
}, {
"name" : "specimen.createdOn",
"caption" : "Created On",
"type" : "date",
"optional" : true,
"defaultValue" : "current_date"
}, {
"name" : "specimen.createdBy",
"caption" : "Created By",
"type" : "user",
"defaultValue" : "current_user",
"optional" : true,
"listSource" : {
"queryParams" : {
"static" : {
"excludeType" : "CONTACT"
}
}
}
},
{
"name" : "specimen.storageLocation",
"caption" : "Location",
"type" : "storage-position",
"optional" : true,
"cpId" : "specimen.cpId",
"entity" : "specimen",
"width" : "240px",
"copyValueFn" : "function(firstRowVal, currentVal) { if ((!!currentVal && !!currentVal.reservationId) && (!!firstRowVal && !!firstRowVal.reservationId)) { return currentVal;} else if (firstRowVal) { return { id: '', name: firstRowVal.name, mode: firstRowVal.mode, positionX: '', positionY: '', position: '', reservationId: '' };} else { return {}; }}"
}, {
"name" : "specimen.createAliquots",
"caption" : "Create Aliquots?",
"icon" : "fa fa-share-alt",
"type" : "toggle-checkbox",
"width" : "30px"
}, {
"name" : "specimen.printLabel",
"caption" : "Print",
"icon" : "fa fa-print",
"type" : "toggle-checkbox",
"width" : "30px"
}, {
"name" : "specimen.closeParent",
"caption" : "Close Parent",
"icon" : "fa fa-ban",
"type" : "toggle-checkbox",
"width" : "30px",
"defaultValue" : false
} ]
} ]
}
}, 3. Set the default and hide the field in the derived/aliquots creation page. In the below example, the field is defaulted to its parent value and hidden from the data entry screen.
In version 11, the hideColumn feature doesn't hide fields but displays them in read-only mode. This ensures users cannot update the fields, fulfilling the feature's purpose.
Example JSON
{
"name" : "specimen.extensionDetail.attrsMap.ST4",
"baseField" : "specimen.extensionDetail.attrsMap.ST4",
"defaultValue" : "field: specimen.parent.extensionDetail.attrsMap.ST4",
"hideColumn" : true
}, Add the Specimen Barcode field in the 'Create Aliquot' page To set up the 'Create Aliquot' page with the Barcode field, simply utilize the following code snippet within the aliquotsCollection located in the common section.
Example JSON
{
"name" : "specimen.barcodes",
"caption" : "Barcodes",
"type" : "textarea",
"optional" : false
}, Example Barcode field in aliquots page.json
The distinction between the specimen. barcode field in the dictionary and specimen.barcodes in the common section:
The ‘specimen.barcodes’ field in the aliquot section functions as a textarea field, akin to the labels field for aliquots. Here, you can input comma/newline/tab-delimited barcodes, with each barcode linked to a single aliquot. This input essentially generates the aliquots.
The ‘specimen.barcode ’ field in the dictionary section is a text field designated for specifying a single barcode corresponding to a specimen. Therefore, the barcode entered on the create aliquot page will be saved and presented on the overview page.
