Update Template ID to Get and Create Dataset Use Case

CHANGELOG.md

@@ -8,6 +8,7 @@ This changelog follows the principles of [Keep a Changelog](https://keepachangel
 
 ### Added
 
+- Datasets: Added optional `templateId` support to `createDataset` requests and `getDataset` responses.
 - Guestbooks: Added `editGuestbook` use case.
 - Guestbooks: Added `getGuestbookResponsesByGuestbookId` use case and repository support for retrieving paginated guestbook responses with total count as structured JSON.
 - Guestbooks: Added `downloadGuestbookResponsesByCollectionId` and `downloadGuestbookResponsesOfAGuestbook` use cases and repository support for exporting guestbook responses as raw CSV content.

docs/useCases.md

@@ -997,6 +997,8 @@ There is an optional third parameter called `includeDeaccessioned`, which indica
 
 There is an optional fourth parameter called `keepRawFields`, which indicates whether or not to keep the metadata fields as they are and avoid the transformation to Markdown. The default value is `false`.
 
+When the dataset is associated with a template, the returned `Dataset` includes the optional `templateId` field containing that template's numeric identifier.
+
 #### Get Dataset By Private URL Token
 
 Returns a [Dataset](../src/datasets/domain/models/Dataset.ts) instance, given an associated Private URL Token.
@@ -1449,7 +1451,7 @@ createDataset.execute(datasetDTO).then((newDatasetIds: CreatedDatasetIdentifiers
 
 _See [use case](../src/datasets/domain/useCases/CreateDataset.ts) implementation_.
 
-The above example creates the new dataset in the root collection since no collection identifier is specified. If you want to create the dataset in a different collection, you must add the collection identifier as a second parameter in the use case call. If you want the dataset type to be anything other than dataset, first [check available dataset types](#get-dataset-available-dataset-types) and then add the name of the dataset type as the third parameter.
+The above example creates the new dataset in the root collection since no collection identifier is specified. If you want to create the dataset in a different collection, you must add the collection identifier as a second parameter in the use case call. If you want the dataset type to be anything other than dataset, first [check available dataset types](#get-dataset-available-dataset-types) and then add the name of the dataset type as the third parameter. To create from an applicable metadata template, set its numeric identifier as `datasetDTO.templateId`; the SDK sends it as the top-level `templateId` field in the request body.
 
 The use case returns a [CreatedDatasetIdentifiers](../src/datasets/domain/models/CreatedDatasetIdentifiers.ts) object, which includes the persistent and numeric identifiers of the created dataset.
 

src/datasets/domain/dtos/DatasetDTO.ts

@@ -2,6 +2,7 @@ import { DatasetLicense } from '../models/Dataset'
 
 export interface DatasetDTO {
   license?: DatasetLicense
+  templateId?: number
   metadataBlockValues: DatasetMetadataBlockValuesDTO[]
 }
 

src/datasets/domain/models/Dataset.ts

@@ -13,6 +13,7 @@ export interface Dataset {
   publicationDate?: string
   citationDate?: string
   guestbookId?: number
+  templateId?: number
   metadataBlocks: DatasetMetadataBlocks
   isPartOf: DvObjectOwnerNode
   datasetType?: string

src/datasets/domain/useCases/CreateDataset.ts

@@ -18,7 +18,7 @@ export class CreateDataset extends DatasetWriteUseCase<CreatedDatasetIdentifiers
   /**
    * Creates a new Dataset in a collection, given a DatasetDTO object and an optional collection identifier, which defaults to :root.
    *
-   * @param {DatasetDTO} [newDataset] - DatasetDTO object including the new dataset metadata field values for each metadata block.
+   * @param {DatasetDTO} [newDataset] - DatasetDTO object including the new dataset metadata field values for each metadata block and, optionally, the template ID to apply.
    * @param {string} [collectionId] - Specifies the collection identifier where the new dataset should be created (optional, defaults to :root).
    * @param {string} [datasetType] - Specifies the dataset type (optional, when omitted, defaults to "dataset").
    * @returns {Promise<CreatedDatasetIdentifiers>}

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

@@ -18,6 +18,7 @@ export interface DatasetPayload {
   publicationDate?: string
   citationDate?: string
   guestbookId?: number
+  templateId?: number
   fileAccessRequest: boolean
   termsOfAccess?: string
   dataAccessPlace?: string

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

@@ -32,6 +32,7 @@ const turndownService = new TurndownService()
 
 export interface NewDatasetRequestPayload {
   datasetType?: string
+  templateId?: number
   datasetVersion: {
     license?: DatasetLicense
     metadataBlocks: Record<string, MetadataBlockRequestPayload>
@@ -102,6 +103,7 @@ export const transformDatasetModelToNewDatasetRequestPayload = (
 ): NewDatasetRequestPayload => {
   return {
     datasetType,
+    ...(dataset.templateId !== undefined && { templateId: dataset.templateId }),
     datasetVersion: {
       ...(dataset.license && { license: dataset.license }),
       metadataBlocks: transformMetadataBlockModelsToRequestPayload(
@@ -299,6 +301,9 @@ export const transformVersionPayloadToDataset = (
   if ('guestbookId' in versionPayload) {
     datasetModel.guestbookId = versionPayload.guestbookId
   }
+  if ('templateId' in versionPayload) {
+    datasetModel.templateId = versionPayload.templateId
+  }
   if ('datasetType' in versionPayload) {
     datasetModel.datasetType = versionPayload.datasetType
   }

test/functional/datasets/GetDataset.test.ts

@@ -93,6 +93,14 @@ describe('execute', () => {
     expect(dataset.termsOfUse.termsOfAccess.termsOfAccessForRestrictedFiles).toBe('Terms of access')
     expect(dataset.termsOfUse.customTerms?.termsOfUse).toBe('Terms of use')
   })
+  test('should return the template id when present', () => {
+    const versionPayload = createDatasetVersionPayload()
+    versionPayload.templateId = 3
+
+    const dataset = transformVersionPayloadToDataset(versionPayload, false)
+
+    expect(dataset.templateId).toBe(3)
+  })
   test('should return metadata fields in markdown format when keepRawFields is false', async () => {
     const createdDatasetIdentifiers = await createDataset.execute(testNewDataset)
 

test/unit/datasets/datasetTransformers.test.ts

@@ -57,4 +57,13 @@ describe('transformNewDatasetModelToRequestPayload', () => {
 
     expect(actual).toEqual(expectedNewDatasetRequestPayload)
   })
+
+  it('should include the template id at the top level of a new dataset request payload', () => {
+    const testDataset = { ...createDatasetDTO(), templateId: 3 }
+    const testMetadataBlocks = [createDatasetMetadataBlockModel()]
+
+    const actual = transformDatasetModelToNewDatasetRequestPayload(testDataset, testMetadataBlocks)
+
+    expect(actual).toEqual({ ...createNewDatasetRequestPayload(), templateId: 3 })
+  })
 })