JMP Clinical User Guide › Configuration

JMP Clinical: Configuration Quick Start

A practical overview for configuration managers and system administrators
On this page
  1. What is a Configuration?
  2. Sharing Studies & Notes
  3. Key Locations at a Glance
  4. What Drives Your Configuration
  5. Setting Up a Configuration
  6. User Roles
  7. Medical Query Files (OCMQ & SMQ) ↕
  8. AE Narrative Templates & Custom Study Attributes ↕
  9. Connecting to JMP Live ↕
  10. Troubleshooting ↕
  11. Further Reading ↕

What is a Configuration?

A JMP Clinical Configuration is a named collection of settings which specify file paths and system preferences that tells JMP Clinical where to read and write studies, metadata, notes, outputs, and other resources. Configurations are the primary way administrators control who sees what and where data lives — whether that is on a single analyst's laptop or a shared network environment used by dozens of reviewers.

Sharing Studies & Notes

Configurations can be set up to support multiple levels of sharing. In one possible setting, a user runs a fully local configuration where all data, notes, and output stay on their own machine. In another, a shared network configuration lets an entire team work from the same study list, share notes and review templates, and write output to common locations.

There are two ways to deploy configurations to users:

Interactive (GUI)

Use the Manage Configurations… window (Settings tab) to add a configuration by pointing to an existing root folder. Suitable for individuals or small teams. See Adding a New Configuration.

File Deployment (Scripted / IT)

For enterprise or multi-user server deployments (Citrix, Windows Terminal Services), administrators can pre-populate installation.configuration.preferences in the installation folder to push Installed Configurations to every user on the machine — no per-user GUI steps required.

Each configuration entry in the file follows this pattern:

["name" => "Local", "installationconfigurationroot" => "$LS_HOME"],
["name" => "Share", "installationconfigurationroot" => "\\\\server\\ClinicalShare"]

Each entry names the configuration and points to the folder containing its installation.path.preferences file. Users see the combined list at launch. JMP Clinical must be relaunched for changes to take effect.

Configuration Files Reference ↗
Mac and Windows configurations are not cross-compatible Configurations created in JMP Clinical are not compatible across Mac and Windows machines. JMP Clinical's path structures, folder separators, and default locations differ fundamentally between operating systems. To avoid errors, share configurations within the same operating system environment only.

Key Locations at a Glance

The diagram below shows the core folder locations for local and shared configurations.

Figure 1 — Core JMP Clinical configuration locations (Windows example)
LOCAL MACHINE INSTALLATION FOLDER C:\ProgramData\JMP\JMPClinical\ <VERSION>\Clinical Stores Installed Configurations USER DOCUMENTS FOLDER %DOCUMENTS%\JMPClinical<VERSION> Stores User Configurations (visible to this user only) At launch: combined config list presented to user CONFIGURATION ROOT FOLDER (one per configuration) installation.path.preferences All folder paths for this configuration system.clinical.preferences System options & user role assignments e.g., C:\ClinicalShare\ or a mapped network drive STUDY INPUT /input/studies/ browsestart/adam browsestart/sdtm NOTES & OUTPUT /user/clinical/notes /user/clinical/output /user/clinical/reviews MedDRA / SMQ /user/smq /user/OCMQ METADATA /user/clinical/ metadata studies SHARED / NETWORK DRIVE (optional) Shared Config Root Folder installation.path.preferences system.clinical.preferences SHARED STUDIES ADaM / SDTM input data repositories SHARED NOTES & OUTPUT notes / reviews / review templates ⚠ OS PERMISSIONS ENFORCED HERE Read/write access to shared folders is controlled by OS — JMPC cannot override. Multiple Users, Same Config Each user references the shared root via their own User Configuration entry. OS permissions control access. mapped drive

What Drives Your Configuration

Three independent mechanisms combine to produce the access and behavior experience for each user. Understanding all three is essential before making any configuration changes.

1 — OS Permissions

Windows or macOS file-system permissions are the outermost layer. JMP Clinical never overrides them. If a user lacks read/write access to the configuration root folder, the configuration will not work for that user — regardless of any JMPC setting.

Details in User Guide ↗

2 — JMPC-Defined Paths

Folder path settings map logical path keys (e.g., /user/clinical/notes) to real folder locations. These determine where studies, notes, output, MedDRA files, and other resources are read from and written to. All path settings are managed through the File Path Options tab in Manage Configurations…

File Path Options ↗

3 — JMPC User Roles

Role assignments control which tabs and operations are visible in JMP Clinical — from running reports to managing study lists to editing configurations. Roles are assigned per-user through the Role Assignments tab in Manage Configurations…

Role Assignments ↗
Important These three mechanisms are independent. Granting a user the Configuration Manager role in JMPC does nothing if the OS has not given them write access to the configuration root folder. Always verify all three elements when troubleshooting access problems.

Setting Up a Configuration (Overview)

The steps below outline the typical process for creating a new shared configuration. For full details see the Adding a New Configuration section of the User Guide.

  1. 1
    Identify the root folder location — either a local path or a mapped/UNC network share. Create the folder. Ensure the appropriate users have OS-level read/write access.
  2. 2
    Open JMP Clinical, go to the Settings tab, and click Manage Configurations…. You must have the Configuration Manager role.
  3. Figure 2 — Settings tab showing the Manage Configurations… button
    JMP Clinical Settings tab with Manage Configurations button highlighted
  4. 3
    Click Add, give the configuration a name, browse to the root folder, and select either User Configuration (you only) or Installed Configuration (all users on this machine).
  5. Figure 3 — The Add dialog for creating a new configuration
    Manage Configurations Add dialog showing Configuration Name, Path, and Type fields
  6. 4
    Change any file paths as needed under the File Path Options tab, or leave the defaults as-is. See the File Path Options reference for a description of each configurable path.
  7. 5
    Set System Preferences (study management options, lock settings, review options) and configure Role Assignments for individual users as required. Leaving all options at their defaults is fine for most deployments. See the System Preferences reference for a description of each option.
  8. 6
    Click OK. Other users can now add a reference to the same shared root from their own machines by repeating steps 2–3.

User Roles Reference

By default, all users are assigned every role except Study List Manager. Roles can be restricted per-user via the Manage Configurations… window. See Role Assignments for more details.

Role What it allows Default?
Study Manager Add, combine, refresh, rename, move, and delete studies; update snapshots and risk data. ✓ Yes
Study List Manager Everything Study Manager can do, plus remove studies from shared locations (useful for cleaning up stale entries). ✗ No
Review Author Create, edit, and save Review Templates and Reviews; run ad hoc analyses; manage Risk Threshold data sets. ✓ Yes
Configuration Manager Add and define configurations, including file paths, system preferences, and role assignments. ✓ Yes
Settings Editor Access the Settings tab to select configurations and manage documentation. Rarely advisable to restrict. ✓ Yes
Note The tabs and options visible on the JMP Clinical Main Window change based on the user's assigned roles. See The JMP Clinical Main Window Changes Depending on the Assigned User Role for details.

Adding a User and Assigning Roles

Role assignments are made per-user in Manage Configurations… → Role Assignments. The screenshot below shows the Role Assignments panel. The Defaults row at the top shows which roles are enabled for all users by default. To restrict or expand roles for a specific user, click the add button to enter their username and override the defaults. Note that there is no separate "Reviewer" role — this was removed in a previous release. Review Authors can open and interact with all reviews in their configuration. See Role Assignments for full instructions.

Figure 4 — Role Assignments panel in Manage Configurations
Role Assignments panel showing default roles and the Username/Assignments table
▶ Medical Query Files (OCMQ & SMQ) Download locations, folder layout, path configuration

JMP Clinical's adverse event reports — most notably the Medical Query Risk Report — rely on external medical query definition files that must be downloaded separately and placed in specific folders before they can be used. There are two types, and each comes from a different source.

OCMQ — FDA Office of New Drugs Custom Medical Queries

OCMQs are Excel-based (.xlsm) files published by the FDA to standardize descriptions of medical conditions for adverse event review. These are the default query type in JMP Clinical.

Download from:
fda.gov → OCMQ page
No subscription required.

Save to:
$DOCUMENTS\OCMQ\<VersionNumber>\
e.g., Documents\OCMQ\2.1\

Auto-generated JMP files:
Three JMP tables are automatically written into each versioned OCMQ folder when JMP Clinical is installed. These files are required specifically by the Algorithmic OCMQ Risk Report and define the algorithm criteria, hypersensitivity preferred terms, and hypoglycemia supplemental terms used to classify subjects against each query. Do not delete or move them — they are read alongside the .xlsm file each time the report runs.

▶ Video: Downloading OCMQ files

SMQ — Standard Medical Queries (MedDRA)

SMQs are ASCII flat files (.asc) maintained by the MedDRA MSSO. They are widely used by industry and regulatory agencies for signal detection. JMP Clinical uses four specific files from the SMQ package.

Download from:
meddra.org
A MedDRA subscription is required. SMQs are bundled with each semi-annual MedDRA version release.

Save to:
$DOCUMENTS\SMQ\
(place all .asc files for a given version in the same folder)

Required SMQ files JMP Clinical uses four specific ASCII files from the MedDRA SMQ package. All four must be present in the SMQ folder: smq_list.asc    smq_content.asc    pt.asc    llt.asc

Folder Structure for Multiple Versions

You can keep multiple versions of either file type on disk simultaneously. JMP Clinical will automatically use the latest version, or you can pin a specific version per study using the Version of OCMQ Files / Version of SMQ Files widget in Set Study Preferences.

Recommended folder layout Documents\
  OCMQ\
    2.1\    ← one subfolder per OCMQ version
      OCMQ_v2.1.xlsm
      AlgorithmicOCMQ_Criteria.jmp  ← auto-generated; required for Algorithmic OCMQ report
      AlgorithmicOCMQ_Hypersensitivity.jmp
      AlgorithmicOCMQ_Hypoglycemia.jmp
    2.0\
      OCMQ_v2.0.xlsm    AlgorithmicOCMQ_Criteria.jmp    ...
  SMQ\      ← one subfolder per MedDRA release; all 4 .asc files go inside
    28.0\
      smq_list.asc
      smq_content.asc
      pt.asc
      llt.asc
    27.1\
      smq_list.asc    smq_content.asc    pt.asc    llt.asc

Specifying a Non-Default Location

If you cannot save files to the default $DOCUMENTS\OCMQ or $DOCUMENTS\SMQ paths (for example, in a shared or Citrix deployment), you must update the path keys in your configuration:

  1. 1
    Go to the Settings tab and open Manage Configurations…
  2. 2
    Select the relevant configuration and navigate to File Path Options.
  3. 3
    Update the /user/OCMQ key to point to your OCMQ folder and/or the /user/smq key to point to your SMQ folder.
  4. 4
    Click OK. JMP Clinical will read query files from the new locations immediately.
Multi-language SMQ files If the SMQ folder contains files for multiple languages, JMP Clinical must be pointed to the subfolder matching the language version of JMP Clinical you are running. Use the /user/smq path key in Manage Configurations to specify the correct language-specific folder.
▶ AE Narrative Templates & Custom Study Attributes Built-in templates, custom .vm files, configuration-wide metadata fields

AE Narrative Templates

The Adverse Events Narrative report generates RTF documents describing individual adverse events in formatted prose. JMP Clinical ships with four built-in templates, and administrators can make additional custom templates available to users within a configuration.

Users select which template to apply at report run time via the AE Narrative Template widget in the Set Study Preferences dialog or directly in the Adverse Events Narrative report options. For a detailed walkthrough of template design and the Velocity syntax, see the AE Narrative Template reference page.

Custom Study Attributes

Custom Study Attributes let configuration managers define a standard set of free-text metadata fields that appear on every study in the configuration — above all other preferences in the Set Study Preferences dialog and in the study information panel of study selector windows. They are a lightweight way to capture study-level context (indication, sponsor, phase, data cut date, etc.) in a consistent, searchable form without modifying study data.

Scope Custom Study Attributes are configuration-wide — every study in the configuration displays the same set of attribute fields. They are defined once by the configuration manager and filled in per-study by any user with access to Set Study Preferences.

Built-in Attributes

Two attributes are available by default on every study without any configuration change:

AttributePurpose
Indication A short phrase describing the study's therapeutic focus or the drug's presumptive use.
Description A longer, open-ended field for any study details relevant to reviewers or other users.

Adding Custom Attributes

  1. 1
    Open Manage Configurations… from the Settings tab.
  2. 2
    Navigate to System Preferences → Study Management → Custom Study Attributes.
  3. 3
    Click Add and enter a key name for each new attribute (e.g., Phase, DataCutDate, Sponsor).
  4. 4
    Click OK. The new attributes will appear in the Set Study Preferences → Custom Study Attributes section for every study in the configuration.
Visibility The Custom Study Attributes section only appears in Set Study Preferences when at least one custom attribute key has been defined in System Preferences. If the section is not visible, no custom attributes have been configured yet for that configuration.

For the full reference see Custom Study Attributes in Set Study Preferences.

▶ Connecting to JMP Live URL configuration, preference keys, publishing reports

JMP Live is JMP's secure, web-based collaboration hub. Once configured, JMP Clinical users can publish any report or complete review directly to JMP Live — where colleagues can explore, filter, and interact with results in a browser without needing JMP Clinical installed. Configuration is done per-configuration via the Manage Configurations… window and requires two values that your JMP Live administrator must supply.

Prerequisites You must have an active JMP Live license and your organization must have a running JMP Live instance before completing the steps below. Contact your system administrator for the JMP Live URL and a display name for your instance.

Required System Preference Keys

JMP Live integration is controlled by two keys in system.clinical.preferences, set via Manage Configurations. Both must be present — JMP Live will not work if either is missing or blank.

Preference Key What it specifies Example value
JMPLiveURL The URL of your JMP Live instance. For multiple instances, separate each URL with a vertical bar ( | ). https://jmplive.example.com
JMPLiveName A display name of your choice for the JMP Live instance, shown in the publishing dialog. Separate multiple names with a vertical bar, in the same order as their corresponding URLs. Clinical Live
JMPLiveSpaceKeys Keys of the JMP Live Spaces available to the current user. Set by your system administrator. Provided by admin
JMPLiveMaximumPackageSizeInMB Maximum upload size for a JMP Live report package. Set by your system administrator. Provided by admin

Configuration Steps

  1. 1
    Open JMP Clinical and go to the Settings tab. Click Manage Configurations…
  2. 2
    Select the configuration you want to enable JMP Live for, then navigate to System Preferences.
  3. 3
    Find the JMP Live section. Enter your JMPLiveURL and JMPLiveName in the corresponding rows. If your organization runs multiple JMP Live instances, separate each URL and each name with a vertical bar ( | ), keeping the order consistent between the two fields.
  4. 4
    Click Close to save.
  5. 5
    Close and relaunch JMP Clinical. Changes to Manage Configurations do not take effect until JMP Clinical is restarted.
Shared configurations If multiple users share a configuration, setting JMPLiveURL and JMPLiveName in system.clinical.preferences once makes JMP Live available to all users of that configuration automatically — no per-user setup required.

Publishing a Report or Review

Once configured, users with the Review Author role can publish to JMP Live directly from the Review Builder using the Create Live Report action button (Live Report icon). The publishing dialog lets users choose:

  • Single report or full review — publish just the active report or the entire open review
  • Publish Data — include underlying data sets with the report for full interactivity
  • Best Interactivity vs. Best Performance — for large data sets, Best Performance keeps tabular data interactive while rendering graphs as static images
  • Publish Notes — append the study's notes to the published report
  • JMP Live Space and Folder — destination within your JMP Live instance

For full details on the publishing workflow see Create Live Report in the User Guide, and JMP Live Help for working with reports once they are published.

▶ Common Troubleshooting Preference files, I/O errors, missing tabs, orphaned studies, JMP Live publishing failures
📄 Preference files reference — what the three configuration files do

Each configuration is anchored by a root folder containing two definition files:

  • installation.path.preferences — all folder path locations
  • system.clinical.preferences — system options and user role assignments

A third file, installation.configuration.preferences, registers the name and root path of every configuration added to JMP Clinical. At launch, JMP Clinical reads this file and presents the combined list to the user.

⚠ Never open and directly edit these files in a text editor. All changes should be made through the Manage Configurations… window in JMP Clinical (Settings tab) by a system administrator.

❓ A user is getting an I/O error after IT changed folder permissions

This is almost always an OS permissions issue, not a JMP Clinical configuration issue. JMP Clinical cannot override file-system access controls. Have your IT group verify the affected user has read and write access to all folders referenced in the configuration's installation.path.preferences — especially <userRoot>, the notes folder, and the output folder. Re-check access on both the configuration root and any sub-paths that were adjusted.

For systematic diagnosis, use the Configuration Qualification Add-In (see JMPCLINICAL-3595), which checks configuration paths and permissions and reports actionable results without requiring manual file inspection.

❓ A user cannot see the Settings tab or cannot switch configurations

The user likely has the Settings Editor role revoked. This role should only be restricted when you intend to severely limit that user's interaction with JMP Clinical. Re-enable it via the Manage Configurations window under Role Assignments.

❓ A study name appears in other users' lists but cannot be accessed or reused

The study data was likely deleted without being removed from the shared metadata file. A user with the Study List Manager role can resolve this by filtering the Studies tab to Unlisted (no access) and deleting the orphaned study name entry. See Role Assignments.

❓ The Create Live Report button does nothing, or publishing fails immediately

This likely means JMPLiveURL or JMPLiveName is missing or blank in the active configuration's system preferences. Open Manage Configurations…, verify both values are present under System Preferences → JMP Live, then close and relaunch JMP Clinical. Changes to Manage Configurations are not applied until the application is restarted. If the values are correct but publishing still fails, confirm that the user's machine can reach the JMP Live URL over the network and that the user has an active JMP Live license.

▶ Further Reading User Guide references, external links, and resources by topic
Configuration Setup
Medical Query Files (OCMQ & SMQ)
AE Narrative Templates & Custom Study Attributes
JMP Live