Merge pull request #355 from IQSS/feat/317-get-dataset-templates

Get Dataset Templates use case

Author: ofahimIQSS

docs/useCases.md

@@ -38,6 +38,7 @@ The different use cases currently available in the package are classified below,
     - [Get Dataset Versions Summaries](#get-dataset-versions-summaries)
     - [Get Dataset Linked Collections](#get-dataset-linked-collections)
     - [Get Dataset Available Categories](#get-dataset-available-categories)
+    - [Get Dataset Templates](#get-dataset-templates)
   - [Datasets write use cases](#datasets-write-use-cases)
     - [Create a Dataset](#create-a-dataset)
     - [Update a Dataset](#update-a-dataset)
@@ -1113,6 +1114,24 @@ _See [use case](../src/datasets/domain/useCases/GetDatasetAvailableCategories.ts
 
 The `datasetId` parameter is a number for numeric identifiers or string for persistent identifiers.
 
+#### Get Dataset Templates
+
+Returns a [DatasetTemplate](../src/datasets/domain/models/DatasetTemplate.ts) array containing the dataset templates of the requested collection, given the collection identifier or alias.
+
+##### Example call:
+
+```typescript
+import { getDatasetTemplates } from '@iqss/dataverse-client-javascript'
+
+const collectionIdOrAlias = 12345
+
+getDatasetTemplates.execute(collectionIdOrAlias).then((datasetTemplates: DatasetTemplate[]) => {
+  /* ... */
+})
+```
+
+_See [use case](../src/datasets/domain/useCases/GetDatasetTemplates.ts)_ definition.
+
 ## Files
 
 ### Files read use cases

src/datasets/domain/models/Dataset.ts

@@ -1,4 +1,5 @@
 import { DvObjectOwnerNode } from '../../../core/domain/models/DvObjectOwnerNode'
+import { License } from '../../../licenses'
 
 export interface Dataset {
   id: number
@@ -32,11 +33,7 @@ export enum DatasetVersionState {
   DEACCESSIONED = 'DEACCESSIONED'
 }
 
-export interface DatasetLicense {
-  name: string
-  uri: string
-  iconUri?: string
-}
+export type DatasetLicense = Pick<License, 'name' | 'uri' | 'iconUri'>
 
 export interface CustomTerms {
   termsOfUse: string

src/datasets/domain/models/DatasetTemplate.ts

@@ -0,0 +1,23 @@
+import { DatasetMetadataBlock, TermsOfUse } from './Dataset'
+import { License } from '../../../licenses/domain/models/License'
+
+export interface DatasetTemplate {
+  id: number
+  name: string
+  collectionAlias: string
+  isDefault: boolean
+  usageCount: number
+  createTime: string
+  createDate: string
+  // 👇 From Edit Template Metadata
+  datasetMetadataBlocks: DatasetMetadataBlock[]
+  instructions: DatasetTemplateInstruction[]
+  // 👇 From Edit Template Terms
+  termsOfUse: TermsOfUse
+  license?: License // This license property is going to be present if not custom terms are added in the UI
+}
+
+export interface DatasetTemplateInstruction {
+  instructionField: string
+  instructionText: string
+}

src/datasets/domain/repositories/IDatasetsRepository.ts

@@ -12,6 +12,7 @@ import { DatasetVersionSummaryInfo } from '../models/DatasetVersionSummaryInfo'
 import { DatasetLinkedCollection } from '../models/DatasetLinkedCollection'
 import { CitationFormat } from '../models/CitationFormat'
 import { FormattedCitation } from '../models/FormattedCitation'
+import { DatasetTemplate } from '../models/DatasetTemplate'
 
 export interface IDatasetsRepository {
   getDataset(
@@ -74,4 +75,5 @@ export interface IDatasetsRepository {
     format: CitationFormat,
     includeDeaccessioned?: boolean
   ): Promise<FormattedCitation>
+  getDatasetTemplates(collectionIdOrAlias: number | string): Promise<DatasetTemplate[]>
 }

src/datasets/domain/useCases/GetDatasetTemplates.ts

@@ -0,0 +1,25 @@
+import { ROOT_COLLECTION_ID } from '../../../collections/domain/models/Collection'
+import { UseCase } from '../../../core/domain/useCases/UseCase'
+import { DatasetTemplate } from '../models/DatasetTemplate'
+import { IDatasetsRepository } from '../repositories/IDatasetsRepository'
+
+export class GetDatasetTemplates implements UseCase<DatasetTemplate[]> {
+  private datasetsRepository: IDatasetsRepository
+
+  constructor(datasetsRepository: IDatasetsRepository) {
+    this.datasetsRepository = datasetsRepository
+  }
+
+  /**
+   * Returns a DatasetTemplate array containing the dataset templates of the requested collection, given the collection identifier or alias.
+   *
+   * @param {number | string} [collectionIdOrAlias = ':root'] - A generic collection identifier, which can be either a string (for queries by CollectionAlias), or a number (for queries by CollectionId)
+   * If this parameter is not set, the default value is: ':root'
+   * @returns {Promise<DatasetTemplate[]>}
+   */
+  async execute(
+    collectionIdOrAlias: number | string = ROOT_COLLECTION_ID
+  ): Promise<DatasetTemplate[]> {
+    return await this.datasetsRepository.getDatasetTemplates(collectionIdOrAlias)
+  }
+}

src/datasets/index.ts

@@ -25,6 +25,7 @@ import { UnlinkDataset } from './domain/useCases/UnlinkDataset'
 import { GetDatasetLinkedCollections } from './domain/useCases/GetDatasetLinkedCollections'
 import { GetDatasetAvailableCategories } from './domain/useCases/GetDatasetAvailableCategories'
 import { GetDatasetCitationInOtherFormats } from './domain/useCases/GetDatasetCitationInOtherFormats'
+import { GetDatasetTemplates } from './domain/useCases/GetDatasetTemplates'
 
 const datasetsRepository = new DatasetsRepository()
 
@@ -64,6 +65,7 @@ const unlinkDataset = new UnlinkDataset(datasetsRepository)
 const getDatasetLinkedCollections = new GetDatasetLinkedCollections(datasetsRepository)
 const getDatasetAvailableCategories = new GetDatasetAvailableCategories(datasetsRepository)
 const getDatasetCitationInOtherFormats = new GetDatasetCitationInOtherFormats(datasetsRepository)
+const getDatasetTemplates = new GetDatasetTemplates(datasetsRepository)
 
 export {
   getDataset,
@@ -86,7 +88,8 @@ export {
   unlinkDataset,
   getDatasetLinkedCollections,
   getDatasetAvailableCategories,
-  getDatasetCitationInOtherFormats
+  getDatasetCitationInOtherFormats,
+  getDatasetTemplates
 }
 export { DatasetNotNumberedVersion } from './domain/models/DatasetNotNumberedVersion'
 export { DatasetUserPermissions } from './domain/models/DatasetUserPermissions'

src/datasets/infra/repositories/DatasetsRepository.ts

@@ -1,3 +1,4 @@
+import { AxiosResponse } from 'axios'
 import { ApiRepository } from '../../../core/infra/repositories/ApiRepository'
 import { IDatasetsRepository } from '../../domain/repositories/IDatasetsRepository'
 import { Dataset, VersionUpdateType } from '../../domain/models/Dataset'
@@ -24,6 +25,9 @@ import { DatasetLinkedCollection } from '../../domain/models/DatasetLinkedCollec
 import { CitationFormat } from '../../domain/models/CitationFormat'
 import { transformDatasetLinkedCollectionsResponseToDatasetLinkedCollection } from './transformers/datasetLinkedCollectionsTransformers'
 import { FormattedCitation } from '../../domain/models/FormattedCitation'
+import { DatasetTemplate } from '../../domain/models/DatasetTemplate'
+import { DatasetTemplatePayload } from './transformers/DatasetTemplatePayload'
+import { transformDatasetTemplatePayloadToDatasetTemplate } from './transformers/datasetTemplateTransformers'
 
 export interface GetAllDatasetPreviewsQueryParams {
   per_page?: number
@@ -357,4 +361,16 @@ export class DatasetsRepository extends ApiRepository implements IDatasetsReposi
         throw error
       })
   }
+
+  public async getDatasetTemplates(
+    collectionIdOrAlias: number | string
+  ): Promise<DatasetTemplate[]> {
+    return this.doGet(`/dataverses/${collectionIdOrAlias}/templates`, true)
+      .then((response: AxiosResponse<{ data: DatasetTemplatePayload[] }>) =>
+        transformDatasetTemplatePayloadToDatasetTemplate(response.data.data)
+      )
+      .catch((error) => {
+        throw error
+      })
+  }
 }

src/datasets/infra/repositories/transformers/DatasetPayload.ts

@@ -13,7 +13,7 @@ export interface DatasetPayload {
   lastUpdateTime: string
   releaseTime: string
   metadataBlocks: MetadataBlocksPayload
-  license?: LicensePayload
+  license?: DatasetLicensePayload
   alternativePersistentId?: string
   publicationDate?: string
   citationDate?: string
@@ -38,7 +38,7 @@ export interface DatasetPayload {
   deaccessionNote?: string
 }
 
-export interface LicensePayload {
+export interface DatasetLicensePayload {
   name: string
   uri: string
   iconUri?: string

src/datasets/infra/repositories/transformers/DatasetTemplatePayload.ts

@@ -0,0 +1,52 @@
+import { LicensePayload } from '../../../../licenses/domain/repositories/transformers/LicensePayload'
+import { MetadataFieldPayload } from './DatasetPayload'
+
+export interface DatasetTemplatePayload {
+  id: number
+  name: string
+  dataverseAlias: string
+  isDefault: boolean
+  usageCount: number
+  createTime: string
+  createDate: string
+  // 👇 From Edit Template Metadata
+  datasetFields: DatasetFieldsPayload
+  instructions: Instruction[]
+  // 👇 From Edit Template Terms
+  termsOfUseAndAccess: {
+    id: number
+    fileAccessRequest: boolean
+    // This license property is going to be present if not custom terms are added in the UI
+    license?: LicensePayload
+    // Below fields are going to be present if are added in "Restricted Files + Terms of Access"
+    termsOfAccess?: string // This is terms of access for restricted files in the JSF UI
+    dataAccessPlace?: string
+    originalArchive?: string
+    availabilityStatus?: string
+    sizeOfCollection?: string
+    studyCompletion?: string
+    contactForAccess?: string
+    // Below fields are going to be present if custom terms are added in the UI, they will be mapped and grouped under customTerms
+    termsOfUse?: string
+    confidentialityDeclaration?: string
+    specialPermissions?: string
+    restrictions?: string
+    citationRequirements?: string
+    depositorRequirements?: string
+    conditions?: string
+    disclaimer?: string
+  }
+}
+
+type DatasetFieldsPayload = Record<string, DatasetFieldInfoPayload>
+
+interface DatasetFieldInfoPayload {
+  displayName: string
+  name: string
+  fields: MetadataFieldPayload[]
+}
+
+interface Instruction {
+  instructionField: string
+  instructionText: string
+}

src/datasets/infra/repositories/transformers/datasetTemplateTransformers.ts

@@ -0,0 +1,57 @@
+import { transformPayloadLicenseToLicense } from '../../../../licenses/domain/repositories/transformers/licenseTransformers'
+import { DatasetTemplate } from '../../../domain/models/DatasetTemplate'
+import { DatasetTemplatePayload } from './DatasetTemplatePayload'
+import { transformPayloadToDatasetMetadataBlocks } from './datasetTransformers'
+
+export const transformDatasetTemplatePayloadToDatasetTemplate = (
+  collectionDatasetTemplatePayload: DatasetTemplatePayload[]
+): DatasetTemplate[] => {
+  return collectionDatasetTemplatePayload.map((payload) => {
+    const datasetTemplate: DatasetTemplate = {
+      id: payload.id,
+      name: payload.name,
+      collectionAlias: payload.dataverseAlias,
+      isDefault: payload.isDefault,
+      usageCount: payload.usageCount,
+      createTime: payload.createTime,
+      createDate: payload.createDate,
+      datasetMetadataBlocks: transformPayloadToDatasetMetadataBlocks(payload.datasetFields, false),
+      instructions: payload.instructions.map((instruction) => ({
+        instructionField: instruction.instructionField,
+        instructionText: instruction.instructionText
+      })),
+      termsOfUse: {
+        termsOfAccess: {
+          fileAccessRequest: payload.termsOfUseAndAccess.fileAccessRequest,
+          termsOfAccessForRestrictedFiles: payload.termsOfUseAndAccess.termsOfAccess,
+          dataAccessPlace: payload.termsOfUseAndAccess.dataAccessPlace,
+          originalArchive: payload.termsOfUseAndAccess.originalArchive,
+          availabilityStatus: payload.termsOfUseAndAccess.availabilityStatus,
+          contactForAccess: payload.termsOfUseAndAccess.contactForAccess,
+          sizeOfCollection: payload.termsOfUseAndAccess.sizeOfCollection,
+          studyCompletion: payload.termsOfUseAndAccess.studyCompletion
+        }
+      }
+    }
+
+    if (payload.termsOfUseAndAccess.license) {
+      datasetTemplate.license = transformPayloadLicenseToLicense(
+        payload.termsOfUseAndAccess.license
+      )
+    } else {
+      datasetTemplate.termsOfUse.customTerms = {
+        termsOfUse: payload.termsOfUseAndAccess.termsOfUse as string,
+        confidentialityDeclaration: payload.termsOfUseAndAccess
+          .confidentialityDeclaration as string,
+        specialPermissions: payload.termsOfUseAndAccess.specialPermissions as string,
+        restrictions: payload.termsOfUseAndAccess.restrictions as string,
+        citationRequirements: payload.termsOfUseAndAccess.citationRequirements as string,
+        depositorRequirements: payload.termsOfUseAndAccess.depositorRequirements as string,
+        conditions: payload.termsOfUseAndAccess.conditions as string,
+        disclaimer: payload.termsOfUseAndAccess.disclaimer as string
+      }
+    }
+
+    return datasetTemplate
+  })
+}