JMP Clinical Study Management API
Overview
The JMP Clinical Study Management API enables users to programmatically get information, add, update, and remove studies in the their JMP Clinical configurations. In conjunction with the operating system's batch scripting and scheduling functionality, it's possible to automate repetitive tasks on a schedule or in response to some external trigger (e.g. update/existence of a data file). This guide will describe the functions that are available in the API, as well as provide some simple examples of how they may be used in a batch scripted environment.
Note: The guide and usage of the API require the user has an understanding of the Study Management operations in JMP Clinical and at least minimum proficiency in JSL scripting.
Functions for Getting Information
The general usage pattern of the following functions is to supply the name of the study for which you want information. The only exception is the JMPClinicalStudyManagerAPI:getStudyList function, which takes no arguments and returns the list of the study names in the configuration. An operating system environment variable, JMPClinicalBatchConfiguration, can be set prior to launching JMP Clinical to set the active configuration. If that variable is not set, the last configuration used will be in effect.
All output for each operation is written to the JMP log. As such, when using the API in batch mode, the script writer will want to save the JMP log to a file at the end of the session. Another environment variable, JMPClinicalBatchLogPath, can be set prior to launching JMP Clinical to set the path where the log file should be written. It would be up to the script writer to utilize this variable when saving the path.
JMPClinicalStudyManagerAPI:getStudyList - Gets the list of studies for the current configuration (use the JMPClinicalBatchConfiguration environment variable)
return - a List of the names of the studies
JMPClinicalStudyManagerAPI:getSDTMFolder - returns the path of the SDTM folder for the given study.
study - String - name of the study
return - a String of the path for the SDTM folder
JMPClinicalStudyManagerAPI:getADaMFolder - returns the path of the ADaM folder for the given study.
study - String - name of the study
return - a String of the path for the ADaM folder
JMPClinicalStudyManagerAPI:getInitialDate - returns the numeric date the given study was added.
study - String - name of the study
return - a Number (date). Use asDate(...) to get date representation
JMPClinicalStudyManagerAPI:getLastUpdatedDate - returns the numeric date the given study was last modified.
study - String - name of the study
return - a Number (date). Use asDate(...) to get date representation
JMPClinicalStudyManagerAPI:getEnableSnapshot - returns String for the snapshot status of the given study.
study - String - name of the study
return - a String "Yes" == snapshots are enabled, "No" == snapshots are not enabled
JMPClinicalStudyManagerAPI:getSnapshotNumber - returns number for the snapshot of the given study.
study - String - name of the study
return - a number of the snapshot. If snapshots aren't enabled, 0 is returned.
JMPClinicalStudyManagerAPI:getDomainList - returns the list of domains for the given study.
study - String - name of the study
return - a list of Strings of the domains
JMPClinicalStudyManagerAPI:getSizeOnDisk - returns the number of MB on disk for all domains registered for the given study.
study - String - name of the study
return - a number that is the number of MB used by the data files on disk for the given study
JMPClinicalStudyManagerAPI:getCreatedBy - returns the userid that created the given study.
study - String - name of the study
return - a String of the userid that added the study
JMPClinicalStudyManagerAPI:getLastUpdatedBy - returns the userid that last updated the given study.
study - String - name of the study
return - a String of the userid that last updated the study
Functions for Adding, Updating, and Removing
The general usage pattern of the following functions is to supply the name of the study for which you want add, modify or remove. The only exceptions are the JMPClinicalStudyManagerAPI:refreshStudies and JMPClinicalStudyManagerAPI:deleteStudies functions, which take lists of the names for which you want to apply the operation. Additionally, each function accepts arguments that are relevant to each function and control the behavior of each operation. Those specific options are described below. Finally, due to the asynchronous nature of all of the functions below, each function accepts a listener function argument. If specified, the listener function will get called at the completion of the operation. When the listener function is called, no arguments will passed so the specification of the function should have no required parameters (e.g. function({}, ...).
As with the information gathering functions above, an operating system environment variable, JMPClinicalBatchConfiguration, can be set prior to launching JMP Clinical to set the active configuration. If that variable is not set, the last configuration used will be in effect.
All output for each operation is written to the JMP log. As such, when using the API in batch mode, the script writer will want to save the JMP log to a file at the end of the session. Another environment variable, JMPClinicalBatchLogPath, can be set prior to launching JMP Clinical to set the path where the log file should be written. It would be up to the script writer to utilize this variable when saving the path.
JMPClinicalStudyManagerAPI:addStudy - adds the study to current configuration (use the JMPClinicalBatchConfiguration environment variable).
name - String - name of the study
SDTMFolder - String - path to the SDTM data folder. Use "" if no SDTM data (at least one of SDTMFolder or ADaMFolder must be specified)
ADaMFolder - String - path to the ADaM data folder. Use "" if no ADaM data (at least one of SDTMFolder or ADaMFolder must be specified)
useTransportFiles - String - "Yes" (default) to import XPT files if they exist in the data folder(s). "No" if only sas7bdat files should be used
enableSnapshots - String - "Yes" if snapshots will be supported for this study. "No" (default) if snapshots will not be used.
SDTMDomains - List of Strings - The subset of domains in the SDTM folder to use in the study. Use empty() (default) to use all domains found
ADaMDomains - List of Strings - The subset of domains in the ADaM folder to use in the study. Use empty() (default) to use all domains found
completedListener - function - The function to call at the completion of the add study, which is an asynchronous process.
return - N/A
JMPClinicalStudyManagerAPI:refreshStudies - refreshes the metadata of the studies in the current configuration (use the JMPClinicalBatchConfiguration environment variable).
names - List of Strings - names of the studies to refresh
completedListener - function - The function to call at the completion of the refreshing of the studies, which is an asynchronous process.
return - N/A
JMPClinicalStudyManagerAPI:deleteStudies - deletes the studies from the current configuration (use the JMPClinicalBatchConfiguration environment variable).
names - List of Strings - names of the studies to delete
completedListener - function - The function to call at the completion of the delete studies, which is an asynchronous process.
keepOnDelete - String - "PREF" (default) honor the preference for keeping notes and Reviews even after delete, "NO" override the preference and do not keep notes or Reviews, "YES" override the preference and keep notes and Reviews
return - N/A
JMPClinicalStudyManagerAPI:updateSnapshot - update the snapshot of the study in the current configuration (use the JMPClinicalBatchConfiguration environment variable).
name - String - name of the study
SDTMFolder - String - path to the SDTM data folder. Use "" if no SDTM data (at least one of SDTMFolder or ADaMFolder must be specified)
ADaMFolder - String - path to the ADaM data folder. Use "" if no ADaM data (at least one of SDTMFolder or ADaMFolder must be specified)
useTransportFiles - String - "Yes" (default) to import XPT files if they exist in the data folder(s). "No" if only sas7bdat files should be used
includeSuppVars - String - "YES" if supp variables should be honored in comparisons. "No" (default) if supp variables should not be honored in comparisons.
SDTMDomains - List of Strings - The subset of domains in the SDTM folder to use in the study. Use empty() (default) to use all domains found
ADaMDomains - List of Strings - The subset of domains in the ADaM folder to use in the study. Use empty() (default) to use all domains found
completedListener - function - The function to call at the completion of the update snapshot, which is an asynchronous process.
options - List of 8 0/1 (binary) options for what to exclude in snapshot comparisons:
list index
1 - Treatment variables (1) - exclude (default), (0) - include
2 - Sponsor-defined identifier (1) - exclude (default), (0) - include
3 - Sequence number (1) - exclude (default), (0) - include
4 - Domain (1) - exclude (default), (0) - include
5 - Group id (1) - exclude (default), (0) - include
6 - Reference id (1) - exclude (default), (0) - include
7 - Link id (1) - exclude (default), (0) - include
8 - Link group id (1) - exclude (default), (0) - include
e.g. {1, 1, 1, 1, 1, 1, 1, 1}
return - N/A
JMPClinicalStudyManagerAPI:changeFolders - changes the folders for the study in the current configuration (use the JMPClinicalBatchConfiguration environment variable).
name - String - name of the study
SDTMFolder - String - path to the SDTM data folder. Use "" if no SDTM data (at least one of SDTMFolder or ADaMFolder must be specified)
ADaMFolder - String - path to the ADaM data folder. Use "" if no ADaM data (at least one of SDTMFolder or ADaMFolder must be specified)
useTransportFiles - String - "Yes" (default) to import XPT files if they exist in the data folder(s). "No" if only sas7bdat files should be used
SDTMDomains - List of Strings - The subset of domains in the SDTM folder to use in the study. Use empty() (default) to use all domains found
ADaMDomains - List of Strings - The subset of domains in the ADaM folder to use in the study. Use empty() (default) to use all domains found
completedListener - function - The function to call at the completion of the change folders, which is an asynchronous process.
return - N/A
JMPClinicalStudyManagerAPI:precomputeProfileData - precomputes profile data for the study in the current configuration (use the JMPClinicalBatchConfiguration environment variable).
name - String - name of the study
template - String - name of the data template to use for the precompute. "None" is the default data template which includes all domains.
completedListener - function - The function to call at the completion of the precompute, which is an asynchronous process.
return - N/A