Appendixes | Configuring JMP Clinical

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 exist in the product install directory (C:\Program Files\SASHome\JMPClinical\12\LifeSciences) to control configurations, path preferences, and system preferences.
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.
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\12).
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.
*
Click Manage Configurations... 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.
*
*
In this example, the shared drive is defined as drive U:. Note: Your file path will be different.
*
In this case, we will name the folder ClinicalShare. This folder will serve as the root directory for the new shared configuration.
*
*
Click Manage Configurations... to open the Manage Configurations... window.
*
*
In this case, the configuration is named Share.
*
Click Browse... to open a Choose Directory window.
*
Navigate into the ClinicalShare folder and click Select Folder.
*
The Add window appears as shown below:
*
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.
*
Click OK 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
Specifies the location of the system.clinical.preferences file.
By default for JMP Clinical 7.0, this path is set to: $DOCUMENTS\JMPClinical\<CONFIGURATION><JMPC_7.0>, where <CONFIGURATION> is the name of the configuration. You can change this path to any directory for which you have write privileges.
Advanced File Path Options1
Specifies the location of the system.clinical.preferences file.
By default for JMP Clinical 7.0, this path is set to: $DOCUMENTS\JMPClinical\<CONFIGURATION><JMPC_7.0>, where <CONFIGURATION> is the name of the configuration. You can change this path to any directory for which you have write privileges.
/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 /user/clinical/reviews (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.
Templates used by the Adverse Events Narrative report.
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.
Example Resolved Value1

1
Your value resolution might differ depending on your operating system configuration, environment and path variable definitions, and user-defined JMP Clinical path wildcard definitions made elsewhere in installation.path.preferences.

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
Checked - Automatically check at start-up. If updates are found, a notification is shown on the Settings > About JMP Clinical pane.
Unchecked - Disable automatic checks at start-up. You can manually check for updates using Settings > About JMP Clinical > Check for Updates button.
Documentation
Labeling
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 label1 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)
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)
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

1
The label displayed is the version specified using the DomainLabelSupplySource option.

Study Management Options
Checked - When a study is deleted, do not delete notes or reviews associated with it. Choose this option to preserve study artifacts when you do not anticipate using the same study name in the future.
Unchecked - When a study is deleted, delete notes and reviews associated with it.
Lock File Options
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.
0...1e+308, with fractional hours permissible.
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.
0...1e+308, with fractional hours permissible.
Review Options
Checked - Wait until a report tab is given focus before loading its content. This is particularly useful when manipulating very large reviews on slower machines, as it divides and shifts the load penalty into individual reports.
Unchecked - Load all content from all report tabs at once, when the review is opened. All loading is done in one operation.
Checked - Ensure that the creation date of a study found on disk matches the creation date of an identically named study recorded in the review, before using the study for any subsequent operations.
Unchecked - Allow a study on disk with the same name but different creation date as a study referenced in a review, to be considered as a valid match for use in subsequent operations. Choose this option for greater flexibility if the creation date safeguard is not needed for your work environment.
Checked - Ensure that the update date of a study found on disk matches the update date of an identically named study recorded in the review, before using the study for any subsequent operations.
Unchecked - Allow a study on disk with the same name but different update date as a study referenced in a review, to be considered as a valid match for use in subsequent operations. Choose this option for greater flexibility if the update date safeguard is not needed for your work environment.
Checked - Ensure that the snapshot number of a study found on disk matches the snapshot number of an identically named study recorded in the review, before using the study for any subsequent operations.
Unchecked - Allow a study on disk with the same name but different snapshot number as a study referenced in a review, to be considered as a valid match for use in subsequent operations. Choose this option for greater flexibility if the snapshot number safeguard is not needed for your work environment.
Checked - Show a detailed warning notification if the review template specifies options that are not available for the current study. Offending and replacement values are shown, and offending values are replaced as needed.
Unchecked - Do not show a warning notification if the review template specifies options that are not available for the current study. Offending values are replaced as needed.
Checked - Reviewers are allowed to view the report data tables. The Show Tables action button is available for this purpose, on applicable reports.
Unchecked - Reviewers are not allowed to view the report data tables.
Checked - Adds the icon to the options bar for each report. Checked by default. Options include:
Save current options as defaults: Report uses and saves the options that are currently set and reuse those options whenever that report is added to the Review.
Reload saved options defaults: Loads the currently saved options. This is useful if an author has added the Report to the Review, made changes to the options, and then wants to return to whatever was previously saved.
Clear and reset factory defaults: Deletes the saved options for the current Report and reloads the factory defaults.
Unchecked - Options listed above are not available
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.
Checked - The JMP access button appears on the JMP Clinical Main .
Unchecked - The JMP access button does not appear on the JMP Clinical Main Window.
Checked - Uses compression. This option is selected by default.
Unchecked - Does not use compression.
Icon Only: Label report tabs with an icon only. This is the most compact labeling option.
Label Only- Label report tabs with a text label only. This takes up more horizontal space than an icon.
Icon and label - Label report tabs with both an icon and a text label. This is the least compact labeling option.
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.
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.
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:
*
Click the Studies tab.
*
Click the Name drop-down menu and select Unlisted (no access).
*
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.
Reviewer
A user with this role can open and interact with the finalized Reviews that have been created for them. Typically, the Reviewer does not have Author or Study Manager rights and thus cannot make changes to a review.
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\sasajf is a Study manager only.
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:
*
*
*
*
Check the appropriate boxes to Grant the new user a role not already checked in Defaults.
*
Check the appropriate boxes to Revoke from the new user a role that is checked in Defaults.
*
Click OK to add the user.
To edit a user’s role assignments:
*
*
Click to open the Edit window.
*
Check the appropriate boxes to Grant the user one or more additional roles.
*
Check the appropriate boxes to Revoke from the user one or more assigned roles.
*
Click OK to save the changes.
To delete a user:
*
*
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.
 

1
Advanced file path options can be viewed by checking the Show Advanced path options check box.