The EHR Sample Manager module (EHR_SM) is a data link between an EHR project and a Sample Manager project to link sample data with the animal data the sample originated from. This is done by connecting EHR animal records with an animal Source type in Sample Manager. The animal source can then be added to the lineage of the samples which will allow viewing sample data and animal data in the same grid, and searching, sorting and filtering samples based on animal data.
Setup
This setup assumes there is already an EHR project on the server and a Sample Manager project on the server.
You can link multiple Sample Manager projects on a server to the same EHR project, however they will each require separate set up of the EHR Sample Manager module.
EHR Project Setup
- Navigate to your EHR folder.
- In the module properties, verify the property EHRStudyContainer has the "Site Default" field set to the folder path of your EHR project. This will allow the EHR Sample Manager module to find the EHR folder.
Sample Manager Project Setup
1. In the Sample Manager application,
create a new Source Type with the following properties:
- Name must be "Animal" to link in the animal record.
- Manually add one Text Field named "Id". No lookups or any other metadata is necessary. Add no other fields.
- Set the Naming Pattern to something that contains the animal Id. Only the animal Id is fine (${Id}) or some other generated value with the Id (Animal-${Id}).
2. Next,
switch to the LabKey Server view of the project using
> LabKey Server > Project Name.
- Go to > Folder > Management.
- Click the Folder Type tab.
- Check the boxes for both the EHR_SM and DataIntegration modules.
- Click Update Folder. This enables the modules in this container.
3. An ETL is required to bring in the list of animal Ids you want in the Sample Manager project. Once the Ids are ETLed in, the rest of the animal record will be linked to the animal source Ids. An ETL is provided included incremental updates to keep the list of Ids in sync with the EHR project.
To set up the ETL, first download this template to use as a starting place:
Return to the LabKey Server view of the project using
> LabKey Server > Project Name.
- Go to > Folder > Management.
- Click the ETLs tab.
- Create a new ETL, following these steps:
- Copy all but the first line from the ETL template you downloaded, into the ETL creation UI.
- Change the name and description of the ETL to anything besides the template name.
- Where the comments indicate, change the folderPath variable to the actual path of your EHR project using dot notation. This occurs twice in the template. For example, where the template reads "Site.folderPath.study", you might edit to read something like: "Site.MYPRC.EHR.study".
- Often, labs using Sample Manager don't need the full set of demographic information, in that case in the ETL source you can change the queryName from demographics to another query in your EHR project that filters to a subset of animal Ids you'll manage samples for. The query only needs to return the list of animal Ids.
- Change the schedule if you want the ETL to run more or less frequently.
4. Now go to the dataintegration scheduler page and click Run Now to run the ETLs and bring in the Ids. Once that is complete go back to the dataintegration page and enable the ETL for scheduled updates.
5. Go to the Sample Manager app and verify the Animal source has the list of Ids and by default there should be a set of columns from its EHR animal record.
6.
Create your Sample Types in Sample ManagerIn some cases, labs may have some Sample Types that are taken from Animals, while other sample types may not be from an animal. The EHR Sample Manager module provides an Admin UI to configure which Sample Types are animal derived samples. In order to get all the features, the sample types derived from an Animal must be selected from this UI.
- In the Sample Manager project, navigate to the LabKey Server interface via > LabKey Server > Project Name.
- Select > Go To Module > EHR_SM.
- Select Admin Page
- Check the boxes next to the Sample Types for animal derived samples.
- Click Save.
7. The EHR Sample Manager currently provides one "At Sample Time" calculated field. Animal age at sample time. This is calculated using the birth date of the animal from the EHR record and a sample "received" column from the sample data. The sample "received" column can be configured in the admin page described above.
8. To associate Animals as
Sources of samples, follow the Sample Manager documentation for
importing or creating samples with source parents, with the Animal source as the parent.
Using EHR Sample Manager Features
Animal Record Columns in Sample Grids
In the Animal Source Type, you can add any EHR Animal Record columns to the view by customizing the view and expanding "Id". The default view will be used in various detail pages in Sample Manager.
Animal data can be viewed in the same grid as sample data for animal samples. When adding columns to a samples grid view in Sample Manager, the Animal Record is available for diving into the animal data and adding anything from the EHR animal record.
Learn about customizing grid views in Sample Manager in this topic:
Filter by Animal Data
Once added to the sample grids, samples can be filtered and sorted based on animal data, such as
Species code shown here:
Age At Sample
A calculated
Age At Sample column will be added to sample grids. Calculates an approximate age of the animal when the sample was taken. Decimal value of years old.
Animal Lineage
The lineage view for a sample will include the Source animal and display a set of Animal Record info.
Links to EHR Reports
Animal data links in grids and detail views will navigate to the associated EHR reports.
Related Topics
