Skip to content

Latest commit

 

History

History
881 lines (574 loc) · 27.8 KB

useCases.md

File metadata and controls

881 lines (574 loc) · 27.8 KB
Raw

Use Cases

In the context of Domain-Driven Design (DDD), a use case is a specific way to describe and capture a user's or system's interaction with the domain to achieve a particular goal.

This package exposes the functionality in the form of use cases, with the main goal that any package consumer can easily identify the desired functionality.

The different use cases currently available in the package are classified below, according to the subdomains they target:

Table of Contents

Collections

Collections Read Use Cases

Get a Collection

Returns a Collection instance, given the search parameters to identify it.

Example call:
import { getCollection } from '@iqss/dataverse-client-javascript'

/* ... */
// Case 1: Fetch Collection by its numerical ID
const collectionIdOrAlias = 12345

getCollection
  .execute(collectionId)
  .then((collection: Collection) => {
    /* ... */
  })
  .catch((error: Error) => {
    /* ... */
  })

/* ... */

// Case 2: Fetch Collection by its alias
const collectionIdOrAlias = 'classicLiterature'
getCollection
  .execute(collectionAlias)
  .then((collection: Collection) => {
    /* ... */
  })
  .catch((error: Error) => {
    /* ... */
  })

/* ... */

See use case definition.

The collectionIdOrAlias is a generic collection identifier, which can be either a string (for queries by CollectionAlias), or a number (for queries by CollectionId).

If no collection identifier is specified, the default collection identifier; root will be used. If you want to search for a different collection, you must add the collection identifier as a parameter in the use case call.

Datasets

Datasets Read Use Cases

Get a Dataset

Returns a Dataset instance, given the search parameters to identify it.

Example call:
import { getDataset } from '@iqss/dataverse-client-javascript'

/* ... */

const datasetId = 'doi:10.77777/FK2/AAAAAA'
const datasetVersionId = '1.0'

getDataset.execute(datasetId, datasetVersionId).then((dataset: Dataset) => {
  /* ... */
})

/* ... */

See use case definition.

The datasetId parameter can be a string, for persistent identifiers, or a number, for numeric identifiers.

The optional datasetVersionId parameter can correspond to a numeric version identifier, as in the previous example, or a DatasetNotNumberedVersion enum value. If not set, the default value is DatasetNotNumberedVersion.LATEST.

There is an optional third parameter called includeDeaccessioned, which indicates whether to consider deaccessioned versions or not in the dataset search. If not set, the default value is false.

Get Dataset By Private URL Token

Returns a Dataset instance, given an associated Private URL Token.

import { getPrivateUrlDataset } from '@iqss/dataverse-client-javascript'

/* ... */

const token = 'a56444bc-7697-4711-8964-e0577f055fd2'

getPrivateUrlDataset.execute(token).then((dataset: Dataset) => {
  /* ... */
})

/* ... */

See use case definition.

Get Dataset Citation Text

Returns the Dataset citation text.

Example call:
import { getDatasetCitation } from '@iqss/dataverse-client-javascript'

/* ... */

const datasetId = 2
const datasetVersionId = '1.0'

getDatasetCitation.execute(datasetId, datasetVersionId).then((citationText: string) => {
  /* ... */
})

/* ... */

See use case implementation.

The datasetId parameter can be a string, for persistent identifiers, or a number, for numeric identifiers.

There is an optional third parameter called includeDeaccessioned, which indicates whether to consider deaccessioned versions or not in the dataset search. If not set, the default value is false.

Get Dataset Citation Text By Private URL Token

Returns the Dataset citation text, given an associated Private URL Token.

Example call:
import { getPrivateUrlDatasetCitation } from '@iqss/dataverse-client-javascript'

/* ... */

const token = 'a56444bc-7697-4711-8964-e0577f055fd2'

getPrivateUrlDatasetCitation.execute(token).then((citationText: string) => {
  /* ... */
})

/* ... */

See use case implementation.

Get Dataset Locks

Returns a DatasetLock array of all locks present in a Dataset.

Example call:
import { getDatasetLocks } from '@iqss/dataverse-client-javascript'

/* ... */

const datasetId = 'doi:10.77777/FK2/AAAAAA'

getDatasetLocks.execute(datasetId).then((datasetLocks: DatasetLock[]) => {
  /* ... */
})

/* ... */

See use case implementation.

The datasetId parameter can be a string, for persistent identifiers, or a number, for numeric identifiers.

Get Dataset Summary Field Names

Returns the names of the dataset summary fields configured in the installation.

Example call:
import { getDatasetSummaryFieldNames } from '@iqss/dataverse-client-javascript'

/* ... */

getDatasetSummaryFieldNames.execute().then((names: string[]) => {
  /* ... */
})

/* ... */

See use case implementation.

Get User Permissions on a Dataset

Returns an instance of DatasetUserPermissions that includes the permissions that the calling user has on a particular Dataset.

Example call:
import { getDatasetUserPermissions } from '@iqss/dataverse-client-javascript'

/* ... */

const datasetId = 'doi:10.77777/FK2/AAAAAA'

getDatasetUserPermissions.execute(datasetId).then((permissions: DatasetUserPermissions) => {
  /* ... */
})

/* ... */

See use case implementation.

The datasetId parameter can be a string, for persistent identifiers, or a number, for numeric identifiers.

List All Datasets

Returns an instance of DatasetPreviewSubset that contains reduced information for each dataset that the calling user can access in the installation.

Example call:
import { getAllDatasetPreviews } from '@iqss/dataverse-client-javascript'

/* ... */

const limit = 10
const offset = 20
const collectionId = 'subcollection1'

getAllDatasetPreviews.execute(limit, offset, collectionId).then((subset: DatasetPreviewSubset) => {
  /* ... */
})

/* ... */

See use case implementation.

Note that limit and offset are optional parameters for pagination.

Note that collectionId is an optional parameter to filter datasets by collection. If not set, the default value is root.

The DatasetPreviewSubsetreturned instance contains a property called totalDatasetCount which is necessary for pagination.

Datasets Write Use Cases

Create a Dataset

Creates a new Dataset in a collection, given a NewDatasetDTO object and an optional collection identifier, which defaults to root.

This use case validates the submitted fields of each metadata block and can return errors of type ResourceValidationError, which include sufficient information to determine which field value is invalid and why.

Example call:
import { createDataset } from '@iqss/dataverse-client-javascript'

/* ... */

const newDatasetDTO: NewDatasetDTO = {
  metadataBlockValues: [
    {
      name: 'citation',
      fields: {
        title: 'New Dataset',
        author: [
          {
            authorName: 'John Doe',
            authorAffiliation: 'Dataverse'
          },
          {
            authorName: 'John Lee',
            authorAffiliation: 'Dataverse'
          }
        ],
        datasetContact: [
          {
            datasetContactEmail: '[email protected]',
            datasetContactName: 'John'
          }
        ],
        dsDescription: [
          {
            dsDescriptionValue: 'This is the description of our new dataset'
          }
        ],
        subject: 'Earth and Environmental Sciences'

        /* Rest of field values... */
      }
    }
  ]
}

createDataset.execute(newDatasetDTO).then((newDatasetIds: CreatedDatasetIdentifiers) => {
  /* ... */
})

/* ... */

See use case 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.

The use case returns a CreatedDatasetIdentifiers object, which includes the persistent and numeric identifiers of the created dataset.

Publish a Dataset

Publishes a Dataset, given its identifier and the type of version update to perform.

Example call:
import { publishDataset } from '@iqss/dataverse-client-javascript'

/* ... */

const datasetId = 'doi:10.77777/FK2/AAAAAA'
const versionUpdateType = VersionUpdateType.MINOR

publishDataset.execute(datasetId, versionUpdateType).then((publishedDataset: Dataset) => {
  /* ... */
})

/* ... */

See use case implementation.

The above example publishes the dataset with the specified identifier and performs a minor version update. If the response is successful, the use case does not return the dataset object, but the HTTP status code 200. Otherwise, it throws an error. If you want to perform a major version update, you must set the versionUpdateType parameter to VersionUpdateType.MAJOR.

The datasetId parameter can be a string, for persistent identifiers, or a number, for numeric identifiers.

The versionUpdateType parameter can be a VersionUpdateType enum value, which can be one of the following:

  • VersionUpdateType.MINOR
  • VersionUpdateType.MAJOR

Files

Files read use cases

Get a File

Returns a File instance, given the search parameters to identify it.

Example call:
import { getFile } from '@iqss/dataverse-client-javascript'

/* ... */

const fileId = 2
const datasetVersionId = '1.0'

getFile.execute(fileId, datasetVersionId).then((file: File) => {
  /* ... */
})

/* ... */

See use case definition.

The fileId parameter can be a string, for persistent identifiers, or a number, for numeric identifiers.

The optional datasetVersionId parameter can correspond to a numeric version identifier, as in the previous example, or a DatasetNotNumberedVersion enum value. If not set, the default value is DatasetNotNumberedVersion.LATEST.

Get a File and its Dataset

Returns a tuple of File and Dataset objects ([File, Dataset]), given the search parameters to identify the file.

The returned dataset object corresponds to the dataset version associated with the requested file.

Example call:
import { getFileAndDataset } from '@iqss/dataverse-client-javascript'

/* ... */

const fileId = 2
const datasetVersionId = '1.0'

getFileAndDataset.execute(fileId, datasetVersionId).then((fileAndDataset: [File, Dataset]) => {
  /* ... */
})

/* ... */

See use case definition.

The fileId parameter can be a string, for persistent identifiers, or a number, for numeric identifiers.

The optional datasetVersionId parameter can correspond to a numeric version identifier, as in the previous example, or a DatasetNotNumberedVersion enum value. If not set, the default value is DatasetNotNumberedVersion.LATEST.

Get File Citation Text

Returns the File citation text.

Example call:
import { getFileCitation } from '@iqss/dataverse-client-javascript'

/* ... */

const fileId = 3
const datasetVersionId = '1.0'

getFileCitation.execute(fileId, datasetVersionId).then((citationText: string) => {
  /* ... */
})

/* ... */

See use case implementation.

The fileId parameter can be a string, for persistent identifiers, or a number, for numeric identifiers.

There is an optional third parameter called includeDeaccessioned, which indicates whether to consider deaccessioned versions or not in the file search. If not set, the default value is false.

Get File Counts in a Dataset

Returns an instance of FileCounts, containing the requested Dataset total file count, as well as file counts for the following file properties:

  • Per content type
  • Per category name
  • Per tabular tag name
  • Per access status (Possible values: Public, Restricted, EmbargoedThenRestricted, EmbargoedThenPublic)
Example call:
import { getDatasetFileCounts } from '@iqss/dataverse-client-javascript'

/* ... */

const datasetId = 2
const datasetVersionId = '1.0'

getDatasetFileCounts.execute(datasetId, datasetVersionId).then((fileCounts: FileCounts) => {
  /* ... */
})

/* ... */

See use case implementation.

The datasetId parameter can be a string, for persistent identifiers, or a number, for numeric identifiers. The optional datasetVersionId parameter can correspond to a numeric version identifier, as in the previous example, or a DatasetNotNumberedVersion enum value. If not set, the default value is DatasetNotNumberedVersion.LATEST. There is an optional third parameter called includeDeaccessioned, which indicates whether to consider deaccessioned versions or not in the dataset search. If not set, the default value is false.

An optional fourth parameter fileSearchCriteria receives a FileSearchCriteria object to retrieve counts only for files that match the specified criteria.

Example call using optional parameters:
import { getDatasetFileCounts } from '@iqss/dataverse-client-javascript'

/* ... */

const datasetId: number = 2
const datasetVersionId: string = '1.0'
const includeDeaccessioned: boolean = true
const searchCriteria: FileSearchCriteria = {
  categoryName: 'physics'
}

getDatasetFileCounts
  .execute(datasetId, datasetVersionId, includeDeaccessioned, searchCriteria)
  .then((fileCounts: FileCounts) => {
    /* ... */
  })

/* ... */

Get File Data Tables

This use case is oriented toward tabular files and provides an array of FileDataTable objects for an existing tabular file.

Example call:
import { getFileDataTables } from '@iqss/dataverse-client-javascript'

/* ... */

const fileId = 2

getFileDataTables.execute(fileId).then((dataTables: FileDataTable[]) => {
  /* ... */
})

/* ... */

See use case implementation.

The fileId parameter can be a string, for persistent identifiers, or a number, for numeric identifiers.

Get File Download Count

Provides the download count for a particular File.

Example call:
import { getFileDownloadCount } from '@iqss/dataverse-client-javascript'

/* ... */

const fileId: number = 2

getFileDownloadCount.execute(fileId).then((count: number) => {
  /* ... */
})

/* ... */

See use case implementation.

The fileId parameter can be a string, for persistent identifiers, or a number, for numeric identifiers.

Get the size of Downloading all the files of a Dataset Version

Returns the combined size in bytes of all the files available for download from a particular Dataset.

Example call:
import { getDatasetFilesTotalDownloadSize } from '@iqss/dataverse-client-javascript'

/* ... */

const datasetId: number = 2
const datasetVersionId: string = '1.0'

getDatasetFilesTotalDownloadSize.execute(datasetId, datasetVersionId).then((size: number) => {
  /* ... */
})

/* ... */

See use case implementation.

The datasetId parameter can be a string, for persistent identifiers, or a number, for numeric identifiers. The optional datasetVersionId parameter can correspond to a numeric version identifier, as in the previous example, or a DatasetNotNumberedVersion enum value. If not set, the default value is DatasetNotNumberedVersion.LATEST. There is a third optional parameter called fileDownloadSizeMode which receives an enum type of FileDownloadSizeMode, and applies a filter criteria to the operation. This parameter supports the following values:

  • FileDownloadSizeMode.ALL (Default): Includes both archival and original sizes for tabular files
  • FileDownloadSizeMode.ARCHIVAL: Includes only the archival size for tabular files
  • FileDownloadSizeMode.ORIGINAL: Includes only the original size for tabular files

An optional fourth parameter called fileSearchCriteria receives a FileSearchCriteria object to only consider files that match the specified criteria.

An optional fifth parameter called includeDeaccessioned indicates whether to consider deaccessioned versions or not in the dataset search. If not set, the default value is false.

Example call using optional parameters:
import { getDatasetFilesTotalDownloadSize } from '@iqss/dataverse-client-javascript'

/* ... */

const datasetId: number = 2
const datasetVersionId: string = '1.0'
const mode: FileDownloadSizeMode = FileDownloadSizeMode.ARCHIVAL
const searchCriteria: FileDownloadSizeMode = {
  categoryName: 'physics'
}
const includeDeaccessioned: boolean = true

getDatasetFilesTotalDownloadSize
  .execute(datasetId, datasetVersionId, mode, searchCriteria, includeDeaccessioned)
  .then((size: number) => {
    /* ... */
  })

/* ... */

Get User Permissions on a File

This use case returns a FileUserPermissions object, which includes the permissions that the calling user has on a particular File.

The returned FileUserPermissions object contains the following permissions, as booleans:

  • Can download the file (canDownloadFile)
  • Can manage the file permissions (canManageFilePermissions)
  • Can edit the file owner dataset (canEditOwnerDataset)
Example call:
import { getFileUserPermissions } from '@iqss/dataverse-client-javascript'

/* ... */

const fileId: number = 2

getFileUserPermissions.execute(fileId).then((permissions: FileUserPermissions) => {
  /* ... */
})

/* ... */

See use case implementation.

The fileId parameter can be a string, for persistent identifiers, or a number, for numeric identifiers.

List Files in a Dataset

Returns an instance of FilesSubset, which contains the files from the requested Dataset and page (if pagination parameters are set).

Example call:
import { getDatasetFiles } from '@iqss/dataverse-client-javascript'

/* ... */

const datasetId = 2
const datasetVersionId = '1.0'

getDatasetFiles.execute(datasetId, datasetVersionId).then((subset: FilesSubset) => {
  /* ... */
})

/* ... */

See use case implementation.

The datasetId parameter can be a string, for persistent identifiers, or a number, for numeric identifiers. The optional datasetVersionId parameter can correspond to a numeric version identifier, as in the previous example, or a DatasetNotNumberedVersion enum value. If not set, the default value is DatasetNotNumberedVersion.LATEST. This use case supports the following optional parameters depending on the search goals:

  • includeDeaccessioned: (boolean) Indicates whether to consider deaccessioned versions or not in the dataset search. If not set, the default value is false.
  • limit: (number) Limit for pagination.
  • offset: (number) Offset for pagination.
  • fileSearchCriteria: (FileSearchCriteria) Supports filtering the files by different file properties.
  • fileOrderCriteria: (FileOrderCriteria) Supports ordering the results according to different criteria. If not set, the defalt value is FileOrderCriteria.NAME_AZ.
Example call using optional parameters:
import { getDatasetFiles } from '@iqss/dataverse-client-javascript'

/* ... */

const datasetId: number = 2
const datasetVersionId: string = '1.0'
const includeDeaccessioned: boolean = true
const limit: number = 10
const offset: number = 20
const searchCriteria: FileSearchCriteria = {
  searchText: 'file title'
}
const orderCriteria: FileOrderCriteria = FileOrderCriteria.NEWEST

getDatasetFiles
  .execute(
    datasetId,
    datasetVersionId,
    includeDeaccessioned,
    limit,
    offset,
    searchCriteria,
    orderCriteria
  )
  .then((subset: FilesSubset) => {
    /* ... */
  })

/* ... */

Metadata Blocks

Metadata Blocks read use cases

Get Metadata Block By Name

Returns a MetadataBlock instance, given its name.

Example call:
import { getMetadataBlockByName } from '@iqss/dataverse-client-javascript'

/* ... */

const name = 'citation'

getMetadataBlockByName.execute(name).then((metadataBlock: MetadataBlock) => {
  /* ... */
})

/* ... */

See use case implementation.

Get Collection Metadata Blocks

Returns a MetadataBlock array containing the metadata blocks from the requested collection.

Example call:
import { getCollectionMetadataBlocks } from '@iqss/dataverse-client-javascript'

/* ... */

const collectionIdOrAlias = 'citation'

getCollectionMetadataBlocks.execute(collectionAlias).then((metadataBlocks: MetadataBlock[]) => {
  /* ... */
})

/* ... */

See use case implementation.

The collectionIdOrAlias is a generic collection identifier, which can be either a string (for queries by CollectionAlias), or a number (for queries by CollectionId).

There is a second optional parameter called onlyDisplayedOnCreate which indicates whether or not to return only the metadata blocks that are displayed on dataset creation. The default value is false.

Users

Users read use cases

Get Current Authenticated User

Returns the current AuthenticatedUser corresponding to the authentication mechanism provided through ApiConfig.

Example call:
import { getCurrentAuthenticatedUser } from '@iqss/dataverse-client-javascript'

/* ... */

getCurrentAuthenticatedUser.execute().then((user: AuthenticatedUser) => {
  /* ... */
})

/* ... */

See use case implementation.

Info

Get Dataverse Backend Version

Returns a DataverseVersion object, which contains version information for the Dataverse backend installation.

Example call:
import { getDataverseVersion } from '@iqss/dataverse-client-javascript'

/* ... */

getDataverseVersion.execute().then((version: DataverseVersion) => {
  /* ... */
})

/* ... */

See use case implementation.

Get Maximum Embargo Duration In Months

Returns a number indicating the configured maximum embargo duration in months. For information on the possible values that can be returned, please refer to the MaxEmbargoDurationInMonths property in the Dataverse documentation: MaxEmbargoDurationInMonths.

Example call:
import { getMaxEmbargoDurationInMonths } from '@iqss/dataverse-client-javascript'

/* ... */

getMaxEmbargoDurationInMonths.execute().then((months: number) => {
  /* ... */
})

/* ... */

See use case implementation.

Get ZIP Download Limit

Returns a number indicating the configured ZIP download limit in bytes.

Example call:
import { getZipDownloadLimit } from '@iqss/dataverse-client-javascript'

/* ... */

getZipDownloadLimit.execute().then((downloadLimit: number) => {
  /* ... */
})

/* ... */

See use case implementation.