Overview
A report template defines a subject clinic report. It can be a combination of formatted text, variable values, and JavaScript code. A subject report is run from the Reports tab on the Subject Overview page. The report template is created on the Report Templates tab on the Project Overview page.
To create a Report Template, click on the green Add icon, enter a name in the Name field and create the layout for report. Use the formatting buttons to layout the text as desired. For more control over the layout, you may need to use the HTML view. At the bottom of the page are buttons to select the desired view (Design, HTML, or Preview).
To access a subject's variable value in the report, use the following syntax: <%= #VarCode %>, where <%= %> is the syntax used to indicate that a subject's variable value is to be placed in this location, and #VarCode is a "#" prefixed to a variable's code. If the variable is a categorical variable, the pick list display name for the variable's value can be accessed with the following syntax: <%= #VarCode.Name %>.
Report Types
There are two basic types of reports: those tied to intervals and those global to a subject. Create a report tied to intervals if you wish the report to be run for a particular encounter. In the Reports tab of the Subject Overview page, the reports tied to intervals will be available to run for every encounter the subject has for the report's associated intervals. When the report is run, it will use the variable values from the selected encounter for the encounter variables defined in the report.
If a report refers to any encounter variables, the report will tied to the subset of intervals at which all the variables are collected. To ensure consistency, report validation ensures all encounter variables referenced in the report share at least one interval.
If a report does not access any encounter variables directly, it will not be associated with any intervals. In the Reports tab of the Subject Overview page, these reports will be listed under Project Reports.
Incorporating JavaScript Code
Most reports can be created without writing any JavaScript code. However, if the report includes complex calculations or needs access to encounter data other than the encounter it is being run against, JavaScript is required. To add JavaScript code to the report, enclose the code within the following symbols: <% %>
Any variables defined in a script block can be accessed elsewhere in the code with the <%= varName %> syntax. For example, if at the top of the report you include the following script block <% var notBmi = #height/#weight; %>, which does a calculation using subject variable values and sets the result on variable "notBmi". You can access the value anywhere in the report as follows: <%= notBmi %>. Alternatively, you can put out HTML directly from a script block using the "Write()" method of the special object "Output" as follows:
<%
var notBmi = #height/#weight;
Output.Write("<b>My incorrect BMI calculation is </b>" + notBmi);
%>
Assuming a value of "0.45" for the variable "notBmi", the following will be the output: My incorrect BMI calculation is 0.45
Null Objects
A null object is returned whenever the referenced object (encounter or medication) cannot be located. The null objects allow you to access the object as if one were found making it much easier to create reports. Null objects are returned for encounters and medications.
Encounter Object
Properties
- EncounterDateObject – The date value of the encounter. Will return DateTime.MinValue if the encounter is null.
- EncounterDate – the string value of the encounter. Will return an empty string if the encounter is null.
- IsBaseline – returns true if the encounter is the baseline encounter, otherwise false.
- IsFixed – returns true if the encounter is for a fixed interval, otherwise false.
- IsNull – returns true if the encounter is null, otherwise false.
- #VariableCode – returns the value of the variable with the specified variable code. If the value is null, an empty string is returned.
- #VariableCode.Name – returns the pick list name associated with the value of the variable with the specified variable code. If the value is null, an empty string is returned.
- #VariableCode.ID – returns the ID of the variable with the specified variable code. This is used for methods that take a variableId.
Methods
- GetVariableLabel(variableId) – if the variable is categorical (pick list or radio buttons), it will return the display name, otherwise it will return the value of the variable.
Encounter Collection (ENCOUNTERS)
Overview
Data (including variable values) about any of the subject's encounters can be accessed via a special object named "ENCOUNTERS". This object is a collection of "Encounter" objects (described above). Following is an example of using this collection in code:
To access encounter variables, either loop through the ENCOUNTERS collection or use one of the properties or methods described below to obtain a reference to an Encounter object. At that point you can access a variable value with the encounter.#VariableCode syntax as described above.
See Examples.
Properties
- Count – returns the number of encounters in the collection.
- FirstEncounter – returns the first encounter in the collection. If no encounter is found, a null encounter is returned.
- LastEncounter – returns the last encounter in the collection. If no encounter is found, a null encounter is returned.
Methods
- Average(variableId) – returns the average value of the variable specified by variableId for all encounters in the collection. Returns NaN if any values are null.
- Sum(variableId) – returns the sum of the variable specified by variableId for all encounters in the collection. Returns NaN if any values are null.
- Filter(variableId, compareOperator, compareValue) – returns a collection of encounters that are not excluded by the specified filter. The valid values for compareOperator are:
- IS NOT NULL
- IS NULL
- =
- !=
- <>
- <
- <=
- >
- >=
- GetCount(variableId) – returns the number of encounters in the collection that have a non-null value for the specified variableId.
- GetEncounter(encounterDate) – returns the first encounter in the collection with the specified encounterDate if found, otherwise it returns a null encounter.
- GetEncounter(encounterDateString) – attempts to convert the string to a date and then returns the first encounter in the collection with the specified encounterDate, if found, otherwise it returns a null encounter.
- GetEncounter(index) – returns the encounter at the specified index in the collection. If the index is greater than the number of items in the collection, a null encounter is returned.
- GetFirstEncounter()- returns the same as the FirstEncounter property. If no encounter is found, a null encounter is returned.
- GetNextEncounter(encounterObject) – returns the encounter in the collection that follows the specified encounter. If no encounter is found, a null encounter is returned.
- GetNextEncounter(encounterDate) – returns the encounter in the collection that follows the encounter with the specified date. If no encounter is found, a null encounter is returned.
- GetNextEncounter(encounterDateString) – attempts to convert the string to a date and then returns the encounter in the collection that follows the encounter with the specified date. If no encounter is found, a null encounter is returned.
- GetPriorEncounter(encounterObject) – returns the encounter in the collection that precedes the specified encounter. If no encounter is found, a null encounter is returned.
- GetPriorEncounter(encounterDate) – returns the encounter in the collection that precedes the encounter with the specified date. If no encounter is found, a null encounter is returned.
- GetPriorEncounter(encounterDateString) – attempts to convert the string to a date and then returns the encounter in the collection that precedes the encounter with the specified date. If no encounter is found, a null encounter is returned.
- IndexOf(encounterObject) – returns the index of the specified encounter object. If no encounter is found, a null encounter is returned.
- IndexOf(encounterDate) – returns the index of the first encounter with the specified encounterDate. If no encounter is found, a null encounter is returned.
- IndexOf(encounterDateString) – attempts to convert the string to a date and then returns the index of the first encounter with the specified encounterDate. If no encounter is found, a null encounter is returned.
- MaxEncounter(variableId) – returns the first encounter in the collection containing the max value for the specified variableId. If no encounter is found, a null encounter is returned.
- MaxValue(variableId) – return the max value for the specified variableId. An empty string is returned if no values are found.
- MinEncounter(variableId) – returns the first encounter in the collection containing the min value for the specified variableId. If no encounter is found, a null encounter is returned.
- MinValue(variableId) – return the min value for the specified variableId. An empty string is returned if no values are found.
- Offset(encounter, offset) – returns the encounter that is offset positions away from the specified encounter. If no encounter is found, a null encounter is returned. Offset can be negative. Ex.
// returns the second to last encounter.
ENCOUNTERS.Offset(ENCOUNTERS.LastEncounter, -1)* Offset(encounterDate, offset) – returns the encounter that is offset positions away from the encounter with the specified Date. If no encounter is found, a null encounter is returned. Offset can be negative. - Offset(encounterDateString, offset) – attempts to convert the string to a date and then returns the encounter that is offset positions away from the encounter with the specified Date. If no encounter is found, a null encounter is returned. Offset can be negative.
- Sort(variableId, ascending) – returns a collection of encounters sorted by the values of the specified variableId. If ascending is true, the collection will be sorted in ascending order, otherwise it will be sorted in descending order.
Medication Object
Properties
- Administration Route – the administration route for this medication. Will be an empty string on a null medication.
- AR – a shortcut for Administration Route.
- Description – the description of the medication. Will be an empty string on a null medication.
- DoseValue – the numeric value for the dose. Will be decimal.MinValue on a null medication.
- Dose – the string value for the dose. Will be an empty string on a null medication.
- DoseNTZ – the same as Dose with trailing zeros removed.
- ED – Shortcut for End Date
- EndDate – the string value for the end date. Will be an empty string on a null medication. Uses the format MM/DD/YYYY
- EndDateDate- the date value for the end date. Will be SqlDateTime.Null on a null medication.
- GenericName- the generic name for this medication. Will be an empty string on a null medication.
- GN – a shortcut for GenericName.
- IsNull – true if medication is null, otherwise false.
- SD – shortcut for StartDate.
- StartDate – the string value for the start date. Will be an empty string on a null medication.
- StartDateDate – the date value for the start date. Will be SqlDateTime.Null on a null medication.
- TimesPerDay – the string value for times per day. Will be an empty string on a null medication.
- TimesPerDayValue – the numeric value for times per day. Will be int.MinValue on a null medication.
- TN – shortcut for TradeName.
- TPD – shortcut for TimesPerDay.
- TradeName – the trade name for the medication. Will be an empty string on a null medication.
- UnitOfMeasure – the unit of measure for the medication. Will be an empty string on a null medication.
- UOM – shortcut for UnitOfMeasure.
Medication Collection (MEDICATIONS)
All of the subject's medications are stored in a collection for each report. These medications can be accessed via the MEDICATIONS collection. See the Medication Object description for a list of properties.
Properties
- Count – returns the number of medications in the collection.
- Medications - returns a list of all the medications contained in this collection.
Methods
- CurrentMedications() – returns a collection of the current medications. This includes any medication whose start date is before the current date and the end date is null or after the current date.
- MedicationAsOf(date) – returns a collection of medications whose start date is before the specified date and the end date is null or after the specified date.
- Sort(field, ascending) – returns a collection of medications sorted by the specified field. If ascending is true, the collection will be sorted in ascending order, otherwise it will be sorted in descending order.
Valid values for field:
...
The Subject Reports page defines a report that is viewed for a subject. The report can include static text, variable values, and JavaScript code.
