Package com.sas.lsaf.clinical.study

Interface StudyService

public interface StudyService
This service provides methods to retrieve studies and to associate clinical components, such as standards and dictionaries, with a study. To associate clinical components with a study, you must have the Manage Study privilege.
Since:
2.2

  • Method Details

    • getStudiesAssociatedWithStandard

      Set<Study> getStudiesAssociatedWithStandard(String standardId) throws StandardNotFoundException
      Gets the studies that are associated with the standard. If you do not have the Manage Standards global privilege, only studies for which you have read access are returned.
      Parameters:
      standardId - The identifier of the standard.
      Returns:
      A set of studies that are associated with the standard.
      Throws:
      StandardNotFoundException - Thrown when the specified standard does not exist.

    • getStudiesAssociatedWithDictionary

      Set<Study> getStudiesAssociatedWithDictionary(String dictionaryId) throws DictionaryNotFoundException
      Gets the studies that are associated with the dictionary. If you do not have the Manage Standards global privilege, only studies for which you have read access are returned.
      Parameters:
      dictionaryId - The identifier of the dictionary.
      Returns:
      A set of studies that are associated with the dictionary.
      Throws:
      DictionaryNotFoundException - Thrown when the specified dictionary does not exist.

    • getStudiesAssociatedWithExternalDictionary

      Set<Study> getStudiesAssociatedWithExternalDictionary(String externalDictionaryId) throws DictionaryNotFoundException
      Gets the studies that are associated with the external dictionary.
      Parameters:
      externalDictionaryId - The identifier of the external dictionary.
      Returns:
      A set of studies that are associated with the external dictionary.
      Throws:
      DictionaryNotFoundException - Thrown when the specified external dictionary does not exist.

    • associateStandards

      void associateStandards(String studyId, Set<String> standardIds) throws StudyNotFoundException, StandardNotFoundException, StandardAssociationExistsException
      Associates the standards with the study.
      Parameters:
      studyId - The identifier of the study.
      standardIds - The identifiers of the standards.
      Throws:
      StudyNotFoundException - Thrown when the specified study does not exist.
      StandardNotFoundException - Thrown when one or more of the specified standards do not exist.
      StandardAssociationExistsException - Thrown when one or more of the specified standards are currently associated with the study.

    • disassociateStandards

      void disassociateStandards(String studyId, Set<String> standardIds) throws StudyNotFoundException, StandardAssociationNotFoundException
      Disassociates the standards that are associated with the study. If a standard is referenced by study tables, or the study has components that reference the base standard and model and it is the last standard of that kind, a StudyStandardReferencedException is thrown.
      Parameters:
      studyId - The identifier of the study.
      standardIds - The identifiers of the standards.
      Throws:
      StudyNotFoundException - Thrown when the specified study does not exist.
      StandardAssociationNotFoundException - Thrown when one or more of the specified standards are not associated with the study.

    • disassociateExternalDictionaries

      void disassociateExternalDictionaries(String studyId, Set<String> externalDictionaryIds) throws StudyNotFoundException, ExternalDictionaryAssociationNotFoundException
      Disassociates the external dictionaries that are associated with the study.
      Parameters:
      studyId - The identifier of the study.
      externalDictionaryIds - The identifiers of the external dictionaries.
      Throws:
      StudyNotFoundException - Thrown when the specified study does not exist.
      ExternalDictionaryAssociationNotFoundException - Thrown when one or more of the specified external dictionaries are not associated.

    • associateExternalDictionaries

      void associateExternalDictionaries(String studyId, Set<String> externalDictionaryIds) throws StudyNotFoundException, DictionaryNotFoundException, ExternalDictionaryAssociationExistsException
      Associates the external dictionaries with the study.
      Parameters:
      studyId - The identifier of the study.
      externalDictionaryIds - The identifiers of the external dictionaries to associate.
      Throws:
      StudyNotFoundException - Thrown when the specified study does not exist.
      ExternalDictionaryAssociationExistsException - Thrown when one or more of the specified external dictionaries are currently associated.
      DictionaryNotFoundException - Thrown when one or more of the specified dictionaries does not exist.

    • associateDictionaries

      void associateDictionaries(String studyId, List<String> dictionaryIds) throws StudyNotFoundException, DictionaryNotFoundException, StudyDictionaryException
      Associates the dictionaries with the study, replacing the current associations. The order of the dictionaries determines the lookup order for codelists. Providing an empty list removes all dictionaries. Note: The current user must have the study component dictionary set as editable in order to perform the update. See setStudyComponentEditableByCurrentUser(String, StudyComponent).
      Parameters:
      studyId - The identifier of the study.
      dictionaryIds - The identifiers of the dictionaries.
      Throws:
      StudyNotFoundException - Thrown when the specified study does not exist.
      DictionaryNotFoundException - Thrown when one or more of the specified dictionaries does not exist.
      StudyDictionaryException - Thrown when one or more of the specified dictionaries cannot be associated.

    • getStandardsAssociatedWithStudy

      Set<StandardDescriptor> getStandardsAssociatedWithStudy(String studyId) throws StudyNotFoundException
      Gets the standards that are associated with the study.
      Parameters:
      studyId - The identifier of the study.
      Returns:
      A set of standards that are associated with the study.
      Throws:
      StudyNotFoundException - Thrown when the specified study does not exist.

    • getDictionariesAssociatedWithStudy

      List<DictionaryDescriptor> getDictionariesAssociatedWithStudy(String studyId) throws StudyNotFoundException
      Gets the dictionaries that are associated with the study. The order of the dictionaries indicates the lookup order for codelists.
      Parameters:
      studyId - The identifier of the study.
      Returns:
      A list of dictionaries that are associated with the study.
      Throws:
      StudyNotFoundException - Thrown when the specified study does not exist.

    • getExternalDictionariesAssociatedWithStudy

      Set<ExternalDictionary> getExternalDictionariesAssociatedWithStudy(String studyId) throws StudyNotFoundException
      Gets the external dictionaries that are associated with the study.
      Parameters:
      studyId - The identifier of the study.
      Returns:
      A set of external dictionaries that are associated with the study.
      Throws:
      StudyNotFoundException - Thrown when the specified study does not exist.

    • getStudyComponentEditableStatus

      StudyComponentEditableStatus getStudyComponentEditableStatus(String studyId, StudyComponent studyComponent) throws StudyNotFoundException
      Gets the study component editable status, that indicates whether the study component is being edited, by whom, and when the editing started.
      Parameters:
      studyId - The identifier of the study.
      studyComponent - The StudyComponent object.
      Returns:
      The editable status of the study component.
      Throws:
      StudyNotFoundException - Thrown when the specified study does not exist.

    • setStudyComponentEditableByCurrentUser

      StudyComponentEditableStatus setStudyComponentEditableByCurrentUser(String studyId, StudyComponent studyComponent) throws StudyNotFoundException, StudyComponentEditException
      Sets the study component as editable by the current user. This action prevents other users from making changes to that component.
      Parameters:
      studyId - The identifier of the study.
      studyComponent - The StudyComponent object.
      Returns:
      The editable status of the study component.
      Throws:
      StudyNotFoundException - Thrown when the specified study does not exist.
      StudyComponentEditException - Thrown when the study component cannot be set as editable by the current user.

    • setStudyComponentAsNotEditable

      StudyComponentEditableStatus setStudyComponentAsNotEditable(String studyId, StudyComponent studyComponent) throws StudyNotFoundException, StudyComponentEditException
      Sets the study component as not editable regardless of whether you or someone else has set it for editing. This action can result in a loss of changes by another user.
      Parameters:
      studyId - The identifier of the study.
      studyComponent - The StudyComponent.
      Returns:
      The editable status of the study component.
      Throws:
      StudyNotFoundException - Thrown when the specified study does not exist.
      StudyComponentEditException - Thrown when the study component cannot be set as not editable.

    • exportStudyDetailsToDataSet

      String exportStudyDetailsToDataSet(String studyId, ExportFileCreateInfo info) throws StudyNotFoundException, ExportException
      Exports the study details to a data set. The details include study name, study description, protocol, and study identifier.
      Parameters:
      studyId - The identifier of the study.
      info - The method to add the exported data set.
      Returns:
      The path to the exported data set.
      Throws:
      StudyNotFoundException - Thrown when the specified study does not exist.
      ExportException - Thrown when there is an issue exporting the metadata.

    • exportStudyStandardsToDataSet

      String exportStudyStandardsToDataSet(String studyId, ExportFileCreateInfo info) throws StudyNotFoundException, ExportException
      Exports to a data set the list of standards that are associated with the study.
      Parameters:
      studyId - The identifier of the study.
      info - The method to add the exported data set.
      Returns:
      The path to the exported data set.
      Throws:
      StudyNotFoundException - Thrown when the specified study does not exist.
      ExportException - Thrown when there is an issue exporting the metadata.

    • importStudyDetails

      void importStudyDetails(String studyId, StudyComponentImportInfo importInfo) throws StudyNotFoundException, StudyUpdateException, ImportException
      Updates the study details from an import file. The details provided replace the current details. The import file must be a SAS data set (.sas7bdat).
      Parameters:
      studyId - The identifier of the study.
      importInfo - The import information.
      Throws:
      StudyNotFoundException - Thrown when the specified study does not exist.
      StudyUpdateException - Thrown when the study metadata cannot be updated.
      ImportException - Thrown when there is an issue processing the import file.

    • exportStudyExternalDictionariesToDataSet

      String exportStudyExternalDictionariesToDataSet(String studyId, ExportFileCreateInfo info) throws StudyNotFoundException, ExportException
      Exports to a data set the list of external dictionaries associated with the study.
      Parameters:
      studyId - The identifier of the study.
      info - The method to add the exported data set.
      Returns:
      The path to the exported data set.
      Throws:
      StudyNotFoundException - Thrown when the specified study does not exist.
      ExportException - Thrown when there is an issue exporting the metadata.

    • exportStudyDictionariesToDataSet

      String exportStudyDictionariesToDataSet(String studyId, ExportFileCreateInfo info) throws StudyNotFoundException, ExportException
      Exports to a data set the list of dictionaries that are associated with the study.
      Parameters:
      studyId - The identifier of the study.
      info - The method to add the exported data set.
      Returns:
      The path to the exported data set.
      Throws:
      StudyNotFoundException - Thrown when the specified study does not exist.
      ExportException - Thrown when there is an issue exporting the metadata.

    • exportStudyCodeListsToDataSet

      String exportStudyCodeListsToDataSet(String studyId, ExportFileCreateInfo info) throws StudyNotFoundException, ExportException
      Exports to a data set the code lists that are defined with the study.
      Parameters:
      studyId - The identifier of the study.
      info - The method to add the exported data set.
      Returns:
      The path to the exported data set.
      Throws:
      StudyNotFoundException - Thrown when the specified study does not exist.
      ExportException - Thrown when there is an issue exporting the metadata.

    • importStudyCodeLists

      StudyUpdateResult importStudyCodeLists(String studyId, StudyComponentImportInfo importInfo, ExportFileCreateInfo validationInfo) throws StudyNotFoundException, StudyCodeListUpdateException, ImportException, ValidationReportException
      Updates the study code lists from the import file with options to replace all or add new. A validation report can be created that lists the errors, warnings, and notes that were found when processing the import file. The import file must be a SAS data set (.sas7bdat).
      Parameters:
      studyId - The identifier of the study.
      importInfo - The import information.
      validationInfo - The method to create a validation report, which contains the errors, warnings, and notes about the import file. Specifying null indicates that no report is be saved.
      Returns:
      The import results, which include study information and validation errors, warnings, and notes.
      Throws:
      StudyNotFoundException - Thrown when the specified study does not exist.
      StudyCodeListUpdateException - Thrown when the study code lists cannot be updated.
      ImportException - Thrown when there is an issue importing the file.
      ValidationReportException - Thrown when the validation report cannot be created.

    • importStudyTables

      StudyUpdateResult importStudyTables(String studyId, String standardId, StudyTablesImportInfo importInfo, ExportFileCreateInfo validationInfo) throws StudyNotFoundException, StandardNotFoundException, StudyTableUpdateException, ImportException, ValidationReportException
      Updates the study tables from the import file information with options to replace all or add new. Import requires a file for tables and a file for columns. A validation report can be created that lists errors, warnings, and notes found when processing the import file. The import files must be SAS data sets (.sas7bdat).
      Parameters:
      studyId - The identifier of the study.
      standardId - The identifier of the standard.
      importInfo - The import information.
      validationInfo - The method to create a validation report, which contains errors, warnings, and notes about the import file. Specifying null indicates that no report is saved.
      Returns:
      The import results, which include study information and validation errors, warnings, and notes.
      Throws:
      StudyNotFoundException - Thrown when the specified study does not exist.
      StandardNotFoundException - Thrown when the specified standard does not exist.
      StudyTableUpdateException - Thrown when the study tables cannot be updated.
      ImportException - Thrown when there is an issue importing the files.
      ValidationReportException - Thrown when the validation report cannot be created.

    • exportSupportingDocumentsToDataSet

      String exportSupportingDocumentsToDataSet(String studyId, String baseStandardName, String modelId, ExportFileCreateInfo info) throws StudyNotFoundException, ExportException
      Exports to a data set the study supporting documents for a specified base standard and model.
      Parameters:
      studyId - The identifier of the study.
      baseStandardName - The name of the base standard, such as SDTM and ADaM.
      modelId - The identifier of the model.
      info - The method to add the exported data set.
      Returns:
      The path to the exported data set.
      Throws:
      StudyNotFoundException - Thrown when the specified study does not exist.
      ExportException - Thrown when there is an issue exporting the metadata.

    • importStudySupportingDocuments

      StudyUpdateResult importStudySupportingDocuments(String studyId, String baseStandardName, String modelId, StudyComponentImportInfo importInfo, ExportFileCreateInfo validationInfo) throws StudyNotFoundException, StudySupportingDocumentUpdateException, ImportException, ValidationReportException
      Updates the study supporting documents from the import file with options to replace all or add new. A validation report can be created that lists errors, warnings, and notes found when processing the import file. The mport file must be a SAS data set (.sas7bdat).
      Parameters:
      studyId - The identifier of the study.
      baseStandardName - The name of the base standard, such as SDTM and ADaM.
      modelId - The identifier of the model.
      importInfo - The import information to update the study metadata.
      validationInfo - The method to create a validation report, which contains errors, warnings, and notes about the import file. Specifying null indicates that no report is saved.
      Returns:
      The import results, which include study information and validation errors, warnings, and notes.
      Throws:
      StudyNotFoundException - Thrown when the specified study does not exist.
      StudySupportingDocumentUpdateException - Thrown when the study supporting documents cannot be updated.
      ImportException - Thrown when there is an issue importing the file.
      ValidationReportException - Thrown when the validation report cannot be created.

    • exportValueLevelMetadataToDataSet

      String exportValueLevelMetadataToDataSet(String studyId, String baseStandardName, String modelId, ExportFileCreateInfo info) throws StudyNotFoundException, ExportException
      Exports to a data set the study's value level metadata for a specified standard and model.
      Parameters:
      studyId - The identifier of the study.
      baseStandardName - The name of the base standard, such as SDTM and ADaM.
      modelId - The identifier of the model.
      info - The method to add the exported data set.
      Returns:
      The path to the exported data set.
      Throws:
      StudyNotFoundException - Thrown when the specified study does not exist.
      ExportException - Thrown when there is an issue exporting the metadata.

    • importStudyValueLevelMetadata

      StudyUpdateResult importStudyValueLevelMetadata(String studyId, String baseStandardName, String modelId, StudyComponentImportInfo importInfo, ExportFileCreateInfo validationInfo) throws StudyNotFoundException, StudyValueLevelMetadataUpdateException, ImportException, ValidationReportException
      Updates the study value level metadata from the import file with options to replace all or add new. A validation report can be created that lists errors, warnings, and notes that were found when processing the import file. The import file must be a SAS data set (.sas7bdat).
      Parameters:
      studyId - The identifier of the study.
      baseStandardName - The name of the base standard, such as SDTM and ADaM.
      modelId - The identifier of the model.
      importInfo - The import information to update the study metadata.
      validationInfo - The method to create a validation report, which contains errors, warnings, and notes about the import file. Specifying null indicates that no report is saved.
      Returns:
      The import results, which include study information and validation errors, warnings, and notes.
      Throws:
      StudyNotFoundException - Thrown when the specified study does not exist.
      StudyValueLevelMetadataUpdateException - Thrown when the study value level metadata cannot be updated.
      ImportException - Thrown when there is an issue importing the file.
      ValidationReportException - Thrown when the validation report cannot be created.

    • exportStudyTablesToDataSets

      Set<String> exportStudyTablesToDataSets(String studyId, String baseStandardName, String modelId, BatchFileCreateInfo info) throws StudyNotFoundException, ExportException
      Exports to data sets the study's table and column metadata for a specified standard and model. The metadata is contained in two SAS data sets. The names include the prefix that is specified on the path variable in BatchFileCreateInfo and these suffixes:
      • _tables
      • _columns

      For example, if the path is /YOURORG/Files/st, st is used as a prefix, and the tables data set is created with name st_tables.sas7bdat.

      Parameters:
      studyId - The identifier of the study.
      baseStandardName - The name of the base standard, such as SDTM and ADaM.
      modelId - The identifier of the model.
      info - The method to add the exported data set.
      Returns:
      The paths to the exported data sets.
      Throws:
      StudyNotFoundException - Thrown when the specified study does not exist.
      ExportException - Thrown when there is an issue exporting the metadata.

    • exportTlfsToDataSets

      Set<String> exportTlfsToDataSets(String studyId, String baseStandardName, String modelId, BatchFileCreateInfo info, boolean includeAnalysisResultsAndDatasets) throws StudyNotFoundException, ExportException
      Exports to data sets the study's Tables, Listings, and Figures metadata for a specified standard and model. For tabulation standards, two SAS data sets are created. The names include the prefix specified on the path variable in BatchFileCreateInfo and these suffixes, which represent sections and TLFs:
      • _sect
      • _tlf

      For analysis standards, the same two data sets are created above. If you specify true to include analysis results and data sets, two additional data sets are created (four total):

      • _sect
      • _tlf
      • _rslt
      • _rdat

      Parameters:
      studyId - The identifier of the study.
      baseStandardName - The name of the base standard, such as SDTM and ADaM.
      modelId - The identifier of the model.
      info - The method to add the exported data set.
      includeAnalysisResultsAndDatasets - Indicates whether to include analysis results and data sets. This parameter applies only when the standard model is analysis.
      Returns:
      The path to the exported data set.
      Throws:
      StudyNotFoundException - Thrown when the specified study does not exist.
      ExportException - Thrown when there is an issue exporting the metadata.

    • importStudyTlfs

      StudyUpdateResult importStudyTlfs(String studyId, String baseStandardName, String modelId, TlfImportInfo importInfo, ExportFileCreateInfo validationInfo) throws StudyNotFoundException, TlfUpdateException, ImportException, ValidationReportException
      Updates the study Tables, Listings, and Figures (TLF) from the import files with options to replace all or add new. Import requires a file for sections and a file for TLFs although you can also specify files for results and result data sets. A validation report can be created that lists errors, warnings, and notes found when processing the import file. The import files must be SAS data sets (.sas7bdat).
      Parameters:
      studyId - The identifier of the study.
      baseStandardName - The name of the base standard, such as SDTM and ADaM.
      modelId - The identifier of the model.
      importInfo - The import information to update the study metadata.
      validationInfo - The method to create a validation report, which contains errors, warnings, and notes about the import file. Specifying null indicates that no report is saved.
      Returns:
      The import results, which include study information and validation errors, warnings, and notes.
      Throws:
      StudyNotFoundException - Thrown when the specified study does not exist.
      TlfUpdateException - Thrown when the study TLFs cannot be updated.
      ImportException - Thrown when there is an issue importing the file.
      ValidationReportException - Thrown when the validation report cannot be created.

    • exportZeroObservationDataSetsForStudyTables

      String exportZeroObservationDataSetsForStudyTables(String studyId, String baseStandardName, String modelId, BatchFileCreateInfo info) throws StudyNotFoundException, ExportException
      Exports a zero observation data set for every table in a study. For each table, a data set is created with the same name as the table in the container path provided in BatchFileCreateInfo.
      Parameters:
      studyId - The identifier of the study.
      baseStandardName - The name of the base standard such, as SDTM and ADaM.
      modelId - The identifier of the model.
      info - The method to add the exported data sets.
      Returns:
      The path to the parent location of the exported data sets.
      Throws:
      StudyNotFoundException - Thrown when the specified study does not exist.
      ExportException - Thrown when there is an issue exporting the metadata.

    • importStudyFromDefine

      StudyUpdateResult importStudyFromDefine(String studyId, String standardId, String definePath, String defineVersion, SourceLocation defineSourceLocation, UpdateAction codeListUpdateAction, ExportFileCreateInfo validationInfo) throws StudyNotFoundException, StandardNotFoundException, StudyUpdateException, ImportException, ValidationReportException
      Imports metadata from a Define-XML file and updates study components based on the contents of the file. Codelists for the study is updated based on the UpdateAction that is specified. All other study metadata is replaced.
      Parameters:
      studyId - The identifier of the study.
      standardId - The identifier of the standard.
      definePath - The path of the Define-XML file.
      defineVersion - The version of the Define-XML file. Specifying null gets the latest version of the file.
      defineSourceLocation - The source location of the Define-XML file.
      codeListUpdateAction - The method to the codelists.
      validationInfo - The method to create a validation report, which contains errors, warnings, and notes about the import file. Specifying null indicates that no report is saved.
      Returns:
      The import results, which include study information and validation errors, warnings, and notes.
      Throws:
      StudyNotFoundException - Thrown when the specified study does not exist.
      StandardNotFoundException - Thrown when the specified standard does not exist.
      StudyUpdateException - Thrown when the study cannot be updated.
      ImportException - Thrown when there is an issue importing the file.
      ValidationReportException - Thrown when the validation report cannot be created.