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 Detail

      • getStudiesAssociatedWithStandard

        java.util.Set<Study> getStudiesAssociatedWithStandard​(java.lang.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

        java.util.Set<Study> getStudiesAssociatedWithDictionary​(java.lang.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

        java.util.Set<Study> getStudiesAssociatedWithExternalDictionary​(java.lang.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.
      • disassociateStandards

        void disassociateStandards​(java.lang.String studyId,
                                   java.util.Set<java.lang.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.
      • getStandardsAssociatedWithStudy

        java.util.Set<StandardDescriptor> getStandardsAssociatedWithStudy​(java.lang.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

        java.util.List<DictionaryDescriptor> getDictionariesAssociatedWithStudy​(java.lang.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

        java.util.Set<ExternalDictionary> getExternalDictionariesAssociatedWithStudy​(java.lang.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​(java.lang.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.
      • exportStudyDetailsToDataSet

        java.lang.String exportStudyDetailsToDataSet​(java.lang.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

        java.lang.String exportStudyStandardsToDataSet​(java.lang.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.
      • exportStudyExternalDictionariesToDataSet

        java.lang.String exportStudyExternalDictionariesToDataSet​(java.lang.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

        java.lang.String exportStudyDictionariesToDataSet​(java.lang.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

        java.lang.String exportStudyCodeListsToDataSet​(java.lang.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​(java.lang.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​(java.lang.String studyId,
                                            java.lang.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

        java.lang.String exportSupportingDocumentsToDataSet​(java.lang.String studyId,
                                                            java.lang.String baseStandardName,
                                                            java.lang.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​(java.lang.String studyId,
                                                         java.lang.String baseStandardName,
                                                         java.lang.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

        java.lang.String exportValueLevelMetadataToDataSet​(java.lang.String studyId,
                                                           java.lang.String baseStandardName,
                                                           java.lang.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​(java.lang.String studyId,
                                                        java.lang.String baseStandardName,
                                                        java.lang.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

        java.util.Set<java.lang.String> exportStudyTablesToDataSets​(java.lang.String studyId,
                                                                    java.lang.String baseStandardName,
                                                                    java.lang.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

        java.util.Set<java.lang.String> exportTlfsToDataSets​(java.lang.String studyId,
                                                             java.lang.String baseStandardName,
                                                             java.lang.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​(java.lang.String studyId,
                                          java.lang.String baseStandardName,
                                          java.lang.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

        java.lang.String exportZeroObservationDataSetsForStudyTables​(java.lang.String studyId,
                                                                     java.lang.String baseStandardName,
                                                                     java.lang.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​(java.lang.String studyId,
                                                java.lang.String standardId,
                                                java.lang.String definePath,
                                                java.lang.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.