Configuring JMP Clinical
JMP Clinical supports multiple configurations that can define a distinct set of folders where study metadata and report output is stored. One of the main purposes of this feature is to enable sharing of studies and reviews (at varying levels) using shared (or mapped) network drives across a set of users.
Configuration Files
Three main files are shipped with JMP Clinical and whose purpose is to control configurations, path preferences, and system preferences. On Windows machines, they are found in the C:\Users\<user>\Documents\JMPClinical17\Configurations\Default directory. On Macs, they are found in the /Library/Application Support/JMP/17/Clinical folder.
Note: You should never need to open and directly edit these files. Any changes that need to be made can be done in the Manage Configuration... window and should be made only by an experienced System Administrator.
Note: Whenever any new configuration is created (including Default), the installation.path.preferences and system.clinical.preferences files get copied from the installation folder into the root of the configuration folder (<DOCUMENTS>/JMPClinical17).
installation.configuration.preferences
The installation.configuration.preferences file contains named configuration variations and the root location(s) to look for installation configurations (as defined by the installation.path.preferences file described below). This file should always remain in the installation directory and is used to surface options in the JMP Clinical Main > Settings > Configuration pane to change configurations.
installation.path.preferences
The installation.path.preferences file contains all the path locations that can be configured to change where JMP Clinical reads and writes for system operations. The Default "Local" configuration shipped with the product looks for this file in the install directory. All default paths use a local configuration and store metadata under the JMP Clinical application data USER ROAMING profile (C:\Users\^USER^\AppData\Roaming\SAS\JMPClinical\14).
To set up a new configuration, this file must be copied and placed into the target root directory location as specified in installation.configuration.preferences.
To successfully set up a new configuration, at a minimum we recommend changing the path specifications in the following lines of the file placed in the share root directory.
• | {"<userRoot>", "$HOME"} where $HOME should be changed to reference the root path of the configuration |
• | {"/system/clinical/preferences", "$LS_HOME"} where $LS_HOME should be changed to reference the root path of the configuration (or another location of your choice) |
• | {"<userLocal>", "$DOCUMENTS\JMPClinical\Local"} where "Local" should be changed to reference the name of the share |
system.clinical.preferences
The system.clinical.preferences file contains various system-level options for a given configuration. This file should also be copied and placed in the target location specified for the "/system/clinical/preferences" key in installation.path.preferences.
One of the key components of the system.clinical.preferences file is the specification of user role assignments. A user role defines the level of functional interactivity that a user has in JMP Clinical. The following user roles can be set for individual users.
• | Study Manager - A user with this role can do all of the operations involved in managing studies within JMP Clinical: add, combine, and refresh metadata, rename or move folders, update a review with a new snapshot, update the study risk data set, and delete studies. The code specification for this role is "StudyManager". |
• | Study List Manager - A user with this role can manage and delete studies from shared folders. By default, this role is not assigned. The code specification for this role is "StudyListManager". |
• | Review Author - A user with this role can create/edit/save Review Templates, do ad hoc analyses, and create and save Reviews. They can also manage the Holiday and Event data set and Risk Threshold data sets used by the configuration. A Review Author implicitly has the Reviewer role as well. The code specification for this role is "ReviewerAuthor". |
• | Reviewer - A user with this role can open Reviews. The code specification for this role is "Reviewer". |
• | Configuration Manager - A user with this role can add and define JMP Clinical configurations. This role is assigned to all users by default. The code specification for this role is "ConfigurationManager". |
• | Settings Editor - A user with this role has access to the Settings tab on the JMP Clinical Main Window. This enables them to select different configurations (if defined), and change how they view Documentation and Help. The code specification for this role is "SettingsEditor". |
Important Note: We generally do not recommend restricting the "SettingsEditor" rights from users. This should be done only if you want to severely restrict the use of the system for that user such that they are not able to select configurations.
By default, all users are assigned all roles except Study List Manager. System administrators, however, can restrict individual users to specific user roles using the following procedures. See Adding Users and Specifying Role Assignments for information about specifying user roles.
Note: The tabs and options available on the JMP Clinical Main Window are dependent on the roles assigned to the user. Refer to The JMP Clinical Main Window Changes Depending on the Assigned User Role. for more information.
Manage Configurations
The Manage Configurations... Window
The Manage Configurations... window is accessed from the Settings tab of the JMP Clinical Main Window.
8 | Click to open the Manage Configurations... window, shown below: |
Adding a New Configuration
In this example, we create a new configuration named Share.
Note: You must have a Configuration Manager role assignment and Write privileges to the relevant folders to add a configuration.
Determine the location for your configuration files.
8 | If the planned location is on your local machine, navigate to the folder where you want to put your configuration files. |
8 | If the planned location is on a shared or network drive, use OS commands to map the drive where the new folder is to reside. |
In this example, the shared drive is defined as drive U:. Note: Your file path will be different.
8 | Create a new folder in the mapped location. |
In this case, we will name the folder ClinicalShare. This folder will serve as the root directory for the new shared configuration.
8 | Open JMP Clinical and click the Settings tab. |
8 | Click to open the Manage Configurations... window. |
8 | Click to open the Add window shown below: |
8 | Specify a name for your configuration. |
In this case, the configuration is named Share.
8 | Click to open a Choose Directory window. |
8 | Navigate into the Clinical Share folder and click . |
8 | Click the User Configurations radio button. |
The Add window appears as shown below:
8 | Click . |
The new configuration is added to the Manage Configurations window. If you select it, all of the default paths and system preferences are displayed, as shown below:
Note: While all paths and preferences are editable, you should consult your system administrator before making any changes.
8 | Click to close the Manage Configurations window. |
Note: Anyone with Read and Write privileges on the shared drive has access to a new shared folder. As the creator of this folder you can control level of access by changing the permissions using WinOS commands.
File Path Options for a Configuration
File path options are set defined for the default configuration when JMP Clinical is first installed. File path options for a new configuration are set automatically when the configuration is set up and added. File paths are modifiable.
Note: All paths are defined in the installation.path.preferences file. Most users will never need to manually change any of these paths. You should never open and directly edit the installation.path.preferences file. Any changes that need to be made can be done in the Manage Configuration... window and should be made only by an experienced System Administrator.
File paths are specified using the following syntax:
{“PathKey”, “PathValue”},
Note the braces ({}) enclosing the key-value pair, the key enclosed in double quotation marks (“”), the comma (,) after the key, the value enclosed in double quotation marks, and the comma following the enclosed key-value pair unless it is the final key-value pair in the file.
Paths are described below.
General File Paths
Key |
Description |
Modify? |
||||||
<userRoot> |
Specifies a user-defined path wildcard for the root of the user folder, for use within subsequent path values. |
Yes:
Note: You cannot set <userRoot> to a folder that does not exist. If you attempt this, the value reverts to the prior value. |
||||||
/system/clinical/preferences |
Specifies the location of the system.clinical.preferences file. |
Yes, when setting up a shared configuration. |
||||||
<userLocal> |
Specifies the path used by JMP Clinical to determine where to put files that are processed that are specific to the user. Additionally, filters, localization specific files, and static reports are set to this root folder as well. |
Yes By default for JMP Clinical 17, this path is set to: $DOCUMENTS\JMPClinical\<CONFIGURATION><JMPClinical17.0>, where <CONFIGURATION> is the name of the configuration. You can change this path to any directory for which you have write privileges. |
||||||
/user/fmq | Specifies the location of the FDA Medical Query (FMQ) files. |
Yes. The default location for these files is to $DOCUMENTS\FMQ If you do not place the files in the default location, you must specify the alternate location here. |
||||||
/user/smq | Specifies the location of the MedDRA Standard Medical Query (SMQ) files. |
Yes. The default location for these files is to $DOCUMENTS\SMQ If you do not place the files in the default location, you must specify the alternate location here. |
Advanced File Path Options
Key |
Description |
Modify? |
<userClinicalRoot> |
Specifies a user-defined path wildcard for the root of the user’s Clinical folder, for use within subsequent path values. |
Normally no. |
<userClinicalStudiesRoot> |
Specifies a user-defined path wildcard for the root of the user’s Clinical Studies folder, for use within subsequent path values. |
Only if necessary for your work environment (more likely on a shared configuration than a local configuration). |
<userClinicalStudyRoot> |
Specifies a user-defined path wildcard for the root of an individual study folder. |
Normally no. |
<userClinicalDataDerivedMetadata> |
Specifies the path used by JMP Clinical to determine where to store metadata that contains data with specific SUBJECT ID (e.g. information in the DM domain). A separate folder is used such that permissions to these data may be set more restrictively as necessary. |
Normally no. |
/input/studies/browsestart/adam | Specifies initial location to browse to when loading the ADaM folder when you are adding a study. | Only if your study data is located in a default location, such as a shared location, before you add a study. |
/input/studies/browsestart/sdtm | Specifies initial location to browse to when loading the SDTM folder when you are adding a study. | Only if your study data is located in a default location, such as a shared location, before you add a study. |
/installation Paths
These path keys refer to folders within the JMP Clinical installation location (typically in Program Files). In almost all circumstances, you are strongly advised not to modify their values.
/user Paths
These path keys refer to the user folders created while running JMP Clinical. In most cases, you should not need to change these values, but the most likely values that you might want to change are for the /user/clinical/notes (notes), /user/clinical/output (output), /user/clinical/reviewtemplates (review templates), and Configuring JMP Clinical (reviews) keys. For example, you might decide that each user maintains their own study list (on the ‘same’ set of studies) but that notes, review templates, and reviews should be shared amongst all users. Where location changes are desired, you are encouraged to use path wildcards (see Advanced File Path Options) to reduce future maintenance, should these locations change again.
Key |
Specifies the location of: |
/user |
The configuration root |
/user/clinical |
The configurations’s Clinical root |
/user/clinical/cvsprestudy |
CDISC Variable Intelligence System requirement files used in study management operations. |
/user/clinical/data | Your study data when you want to store this data together with the metadata. |
/user/clinical/data/adam | All ADaM data sets. |
/user/clinical/data/sdtm | All SDTM data sets. |
/user/clinical/dataderivedmetadata | Any derived data sets generated when either adding the study or refreshing the study. |
/user/clinical/dataderivedmetadata/supp | Any derived data sets generated when merging in supplemental data. |
/user/clinical/delta |
Study snapshot difference files. |
/user/clinical/delta/dropped |
Files tracking dropped records across study snapshots. |
/user/clinical/delta/modified |
Files tracking modified records across study snapshots. |
/user/clinical/filters |
User-defined subject filters. |
/user/clinical/livereportpath | Temporary files generated when publishing a report/review to JMP Live. |
/user/clinical/metadata |
Metadata pertaining to an individual study. |
/user/clinical/metadata/adam |
ADaM metadata pertaining to an individual study. |
/user/clinical/metadata/base |
Core metadata pertaining to an individual study. |
/user/clinical/metadata/sdtm |
SDTM metadata pertaining to an individual study. |
/user/clinical/mydefaultsettings |
The default location of report settings files (deprecated). |
/user/clinical/narrativetemplates |
Templates used by the Adverse Events Narrative report. |
Notes recorded for a particular study. |
|
/user/clinical/notesnostudy |
Notes that do not pertain to a particular study. |
Output for a particular study. |
|
/user/clinical/outputnouser |
Output from study management operations for a particular study. |
/user/clinical/populationflags | Any derived data sets generated when creating population flags. |
/user/clinical/processlibrary |
Report dialogs. |
/user/clinical/processresults |
Output not pertaining to a specific study. |
/user/clinical/profiledata | Any derived data sets generated for the patient profiler. In prior versions of JMP Clinical, users managed profile data using the Manage Profile Data utility. In JMP Clinical 17 and later, this function is managed automatically. |
/user/clinical/rbm |
Risk-Based Monitoring (RBM) generated files. |
/user/clinical/rbmsupplemental |
Supplemental Risk-Based Monitoring (RBM) generated files. |
Saved templates for reviews. |
|
/user/clinical/settings |
Settings files for reports (deprecated). |
/user/clinical/staticreportpath |
Saved static reports. |
/user/clinical/studies |
The root of generated study folders. |
/user/clinical/study |
The root of a specific generated study folder. |
/user/clinical/studydata |
Add Study from SDD study data. |
/user/clinical/templates |
Patient Profiler user-defined templates. |
/user/clinical/templates/data |
Patient Profiler user-defined data templates. |
/user/clinical/templates/display |
Patient Profiler user-defined display templates. |
/user/clinical/templocal | Transient location used by reports. |
/user/clinical/transportdata |
Temporary files created from imported transport files. |
/user/clinical/transportdata/adam |
Temporary files created from imported ADaM transport files. |
/user/clinical/transportdata/sdtm |
Temporary files created from imported SDTM transport files. |
/user/documentation |
Local downloaded JMP Clinical documentation. |
/user/localizations |
Generated localization files. |
/user/preferences |
User preference files. |
You can add, modify, or remove path wildcard keys (for example,, <userLocal>) and values, so long as no subsequent path values refer to undefined keys. However, you must not add, modify, or remove standard keys (for example, /user/clinical/notes) -- you can modify only their values.
Path Resolution Examples
For demonstration purposes, pretend that your user name is zzsmith, and your current study is named Nicardipine. $HOME and $DOCUMENTS are reserved JMP path variables that refer to two different user-specific locations. <STUDY> is a reserved JMP Clinical wildcard that refers to the current study. Keys, values, and corresponding example resolved values are shown below.
Key |
Value |
Example Resolved Value2 |
<userRoot> |
$HOME |
C:\Users\zzsmith\Documents\\JMPClinical\17\Configuations\Default |
<userClinicalRoot> |
<userRoot> |
C:\Users\zzsmith\Documents\\JMPClinical\17\Configuations\Default |
/user/documentation |
$DOCUMENTS\JMPClinical\Documentation |
C:\Users\zzsmith\Documents\JMPClinical\Documentation\ |
/user/clinical/notes |
<userClinicalRoot>\Notes\<STUDY> |
C:\Users\zzsmith\Documents\\JMPClinical\17\Configuations\Default\Notes\<Study> |
System Preferences for a Configuration
System preferences are specified in the system.clinical.preferences file.
Notes about the system.clinical.preferences File
Note: All preferences are defined in the system.clinical.preferences file. Most users will never need to manually change any of these preferences. You should never open and directly edit the system.clinical.preferences file. Any changes that need to be made can be done in the Manage Configuration... window and should be made only by an experienced System Administrator.
The original syntax for preferences is of the following form:
/*** Comment about preference group ***/
{“PreferenceKey”, PreferenceValue},
Note the optional comment enclosed by /*** ***/, the left, and right braces ({}) enclosing the key-value pair, the key enclosed in double quotation marks (“”), the comma (,) after the key, the value (the presence of enclosing quotation marks or braces varies depending on its type), and the comma following the enclosed key-value pair unless it is the final key-value pair in the file.
System Preferences
System preferences enable you to set preferred behaviors for JMP Clinical. Options include automatic checking for updates specifying how domains and buttons are identified on the user interface, which dates and snapshots to honor when comparing studies, and so on. Use the available controls to customize your installation of JMP Clinical.
See the tables below for descriptions of each option:
JMP Clinical Updates
Key |
Description |
Settings |
||||||
CheckForUpdatesAtStartup |
Specifies whether automatic update checks occur. |
|
||||||
NewestVersionURL |
Specifies the URL used to determine whether updates are available. |
http://www.jmp.com/support/downloads/jmpls_newest_versions.txt |
Documentation
Key |
Description |
URL |
DocumentationBaseURL |
Specifies the URL containing the online JMP Clinical documentation |
http://www.jmp.com/support/downloads/ |
DocumentationDownloadURL |
Specifies the URL from which to download documentation. |
http://www.jmp.com/support/downloads/JMPC<JMPC_VERSION>_documentation/JMPC<JMPC_VERSION>_documentation.zip |
JMP Live
Key |
Description |
URL |
JMPLiveURL |
URL to the JMP Live instance you are publishing to. |
To be determined by your system administrator. |
JMPLiveName |
Name of the JMP Live instance |
Not applicable |
JMPLiveSpaceKeys | Keys of the JMP Live Spaces available to the current user. | Not applicable |
JMPLiveMaximumPackageSizeInMB | The maximum size of a JMP Live package. Set by your system administrator | Not Applicable. |
Labeling
Key |
Description |
Options |
DomainLabelReviewOptions |
Specifies how domains are identified on the report options. |
Abreviation Only: Defines a domain on the report dialog and all options by its abbreviation only. For example, the Laboratory Test Results domain is defined as LB. Label Only: Defines a domain on the report options by its label3 only. For example, the LB domain is defined as Laboratory Test Results. Abreviation (Label): Defines a domain on the report options by both its label and its abbreviation. For example, the Laboratory Test Results domain is defined as Laboratory Test Results (LB). Label (Abreviation): Defines a domain on the report options by both its abbreviation and its label. For example, the Laboratory Test Results domain is defined as LB (Laboratory Test Results) |
DomainLabelReviewResults |
Specifies how domains are identified on the report results, graphics, and tables. |
Abreviation Only: Defines a domain on the report results by its abbreviation only. For example, the Laboratory Test Results domain is defined as LB. Label Only: Defines a domain on the report results by its label only. For example, the LB domain is defined as Laboratory Test Results. Abreviation (Label): Defines a domain on the report results by both its label and its abbreviation. For example, the Laboratory Test Results domain is defined as Laboratory Test Results (LB). Label (Abreviation): Defines a domain on the report results by both its abbreviation and its label. For example, the Laboratory Test Results domain is defined as LB (Laboratory Test Results) |
DomainLabelSupplySource |
Specifies which label to preferentially display in report options and results: the one found in the study metadata or the one specified by CDISC rules. |
Metadata, then rules: When this option is selected, JMP Clinical first attempts to find and use labels in the study metadata file. It then assigns a label, based on CDISC rules, for any domain missing a label in metadata. Rules, then metadata: When this option is selected, JMP Clinical assigns labels based on CDISC rules. For custom domains, for which CDISC rules are not available, JMP Clinical uses labels found in metadata
|
Study Management Options
Key |
Description |
Options |
||||||
LoadStudiesRequiresOriginalFolderAccess |
Verifies that the user has permitted access to the original study data. Note: JMP Clinical does nothing to subvert permissions. |
Checked - When JMP Clinical is launched and studies are reloaded, the user will not see those studies for which the original study data has either been deleted or have had read access permissions revoked. Unchecked - Users will see all studies previously added so long as the metadata is available. |
||||||
LazyLoadStudies |
Specifies when to load the metadata for one or more studies. |
Checked - Loads metadata when an operation is performed on a selected study. Unchecked - Loads the metadata for all studies when you launch JMP Clinical |
||||||
KeepDeletedStudiesNotes |
Specifies whether to retain the notes associated with studies that you delete. |
|
Lock File Options
Key |
Description |
Supported values |
ClearStaleStudyManagementLocksInHours |
Specifies the amount of time, in hours, to wait before offering users the option to clear a study management lock. A study management lock is a temporary restriction imposed on users to prevent conflict with an ongoing study management operation (for example, adding, combining, refreshing, renaming, and deleting studies). Under normal circumstances, these locks are removed automatically when the study management operation is complete. Operations on very large studies generally take more time. Exceptional system events might prevent the operation from completing, keeping the lock in effect. Lower the value of this option to give users greater freedom to forcibly remove an outstanding study management lock set by another user. |
0...1e+308, with fractional hours permissible. |
ClearStaleStudyUsageLocksInHours |
Specifies the amount of time, in hours, to wait before offering users the option to clear a study usage lock. A study usage lock is a temporary restriction imposed on users to prevent conflict with an ongoing study usage operation (for example,, running reports in Review Builder). Under normal circumstances, these locks are removed automatically when the study usage operation is complete. A user leaving Review Builder open, as well as exceptional system events, might keep the lock in effect. Lower the value of this option to give users greater freedom to forcibly remove an outstanding study usage lock set by another user. |
0...1e+308, with fractional hours permissible. |
Review Options
Key |
Description |
Options |
|||||||||||||||
ValidateTemplateReportOptionsAgainstStudy |
Specifies whether to show a warning if the options specified in a review template are not available for the current study. |
|
|||||||||||||||
ReviewAuthorsCanMangeReportDefaults |
Enables the Review Author to save what the defaults are for each Report. |
|
|||||||||||||||
ShowJMPHomeAccessButton |
Specifies whether to make the JMP button available on the JMP Clinical Main . This button surfaces the JMP Home , which allows easy access to core, non-Clinical specific, JMP functionality. |
|
|||||||||||||||
ButtonIconLabelOption |
Specifies how to label reports in Review Builder. |
|
Role Assignments
By default, a JMP Clinical installation is fully functional with all reports and options available to you. However, the JMP Clinical installed on your machine, might be configured for a specific user role. These roles are set as described in Adding Users and Specifying Role Assignments.
What follows here is a brief description of each of the JMP Clinical user roles and how to specify roles for each user.
Study Manager
A user with this role can do all of the operations involved in managing studies within JMP Clinical: add, combine, and refresh metadata, rename or move folders, update a review with a new snapshot, update the study risk data set, and delete studies.
Study List Manager
A user with this role can remove studies from shared locations. This option is not enabled, by default.
This option is important in the following scenario: a user completes an analysis of a study, deletes the study from the local install of JMP Clinical, and then deletes the study data files from a shared location. Unfortunately, this process does not delete the study name from the shared metadata file. It still appears in other users’ JMP Clinical installations but cannot be accessed. The study name also remains unavailable and cannot be used again. A Study List Manager can remove the study by the following:
8 | Click the Studies tab. |
8 | Click the Name drop-down menu and select Unlisted (no access). |
8 | Highlight the study to be deleted and click . |
Review Author
A user with this role can create/edit/save Review Templates, do ad hoc analyses, and create and save Reviews. They can also manage the Holiday and JMP Life Sciences / SAS Institute Event data set and Risk Threshold data sets used by the configuration. A Review Author implicitly has the Reviewer role as well.
Configuration Manager
A user with this role can create/edit/save configurations. alterable features include file paths, system preferences, role assignments, and order of report sections.
Settings Editor
This role is normally found in conjunction with one or more of the other user roles. A user with this role has access to the Settings tab on the Main Clinical window. This enables them to select different configurations (if defined), change how they view Documentation and Help, and download and install a local copy of the documentation.
Adding Users and Specifying Role Assignments
Use the Role Assignments options to define roles for additional users,
In this example user anisco is assigned all user roles. User CARYNT\sasajfhas all roles except Study manager.
Note: CARYNT\sasajf actually designates both the user name (sasajf) and the network domain (CARYNT) to which the user belongs. This ability to define both the domain and user gives the system administrator flexibility in identifying individual users.
To add a user:
8 | Click to open the Add window. |
8 | Enter the user’s domain (if needed) and Windows user name in the text box. |
8 | By default, the new user has all of the roles checked under Defaults. |
8 | Check the appropriate boxes to Grant the new user a role not already checked in Defaults. |
8 | Check the appropriate boxes to Revoke from the new user a role that is checked in Defaults. |
8 | Click to add the user. |
To edit a user’s role assignments:
8 | Select an existing user. |
8 | Click to open the Edit window. |
8 | Check the appropriate boxes to Grant the user one or more additional roles. |
8 | Check the appropriate boxes to Revoke from the user one or more assigned roles. |
8 | Click to save the changes. |
To delete a user:
8 | Select an existing user. |
8 | Click to delete the user. |
Study Management
Report Management
The Report Management option enables you to specify the order in which the report categories and the reports themselves are presented in the review.
Adverse Events Narrative Template Management
The Adverse Events Narrative Template Management option enables users to add/remove selected templates that are available for the selected configuration. Configurations shared among users are immediately impacted by changes made to the list of available templates.
The Adverse Events Narrative Templates section lists all of the templates currently in the selected configuration. The templates are listed by their names (name of the base VM file) and the date/time of the last modification. You can add, remove, or edit templates using the action buttons.
The button is enabled if there are templates that are in the JMPC installation location (as per the installation.path.preferences file) that are NOT in the configuration's template location (also per the the installation.path.preferences). Note that existence is based on name and modification date/time. That is, a template may appear to be in the configuration and the install (have the same name), but if the modification date/times don't match, it is available for adding. In the cases where there isn't a match between the configuration and installation, the template is marked with a trailing asterisk (*).
The button is used to remove a template from the configuration. In the cases where these isn't a template match, a warning is issued that the selected template cannot be recovered once deleted. This is to handle the cases where a configuration has templates that were added outside of the installation.
Finally, the button attempts to launch (open) the .VM files that comprise the selected template. This is simply delegating the edit action to the OS. The editing program selected depends on you machine's operating system preferences.