# 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