Skip to content

Latest commit

 

History

History
2769 lines (1806 loc) · 85.3 KB

useCases.md

File metadata and controls

2769 lines (1806 loc) · 85.3 KB

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.

Get Collection Facets

Returns a CollectionFacet array containing the facets of the requested collection, given the collection identifier or alias.

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

const collectionIdOrAlias = 12345

getCollectionFacets
  .execute(collectionId)
  .then((facets: CollectionFacet[]) => {
    /* ... */
  })
  .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.

Get User Permissions on a Collection

Returns an instance of CollectionUserPermissions that includes the permissions that the calling user has on a particular Collection.

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

/* ... */

const collectionIdOrAlias = 12345

getCollectionUserPermissions
  .execute(collectionIdOrAlias)
  .then((permissions: CollectionUserPermissions) => {
    /* ... */
  })

/* ... */

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).

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.

List All Collection Items

Returns an instance of CollectionItemSubset that contains reduced information for each collection item that the calling user can access in the installation.

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

/* ... */

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

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

/* ... */

See use case implementation.

Note that collectionId is an optional parameter to filter the items by a specific collection. If not set, the use case will return items starting from the root collection.

The CollectionItemSubsetreturned instance contains a property called totalItemCount which is necessary for pagination.

This use case supports the following optional parameters depending on the search goals:

  • limit: (number) Limit for pagination.
  • offset: (number) Offset for pagination.
  • collectionSearchCriteria: (CollectionSearchCriteria) Supports filtering the collection items by different properties.
  • searchServiceName: The search service name on which to execute the search (Optional).
  • showTypeCounts: If true, the response will include the count per object type (Optional).

List My Data Collection Items

Returns an instance of CollectionItemSubset that contains reduced information for each collection item for which the calling user has a role.

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

/* ... */

const roleIds = [1, 2]
const collectionItemTypes = [CollectionItemType.DATASET, CollectionItemType.FILE]
const publishingStatuses = [
  PublicationStatus.Published,
  PublicationStatus.Draft,
  PublicationStatus.Unpublished
]
const limit = 10
const selectedPage = 1
const searchText = 'search text'
const otherUserName = 'otherUserName'

getMyDataCollectionItems
  .execute(
    roleIds,
    collectionItemTypes,
    publishingStatuses,
    limit,
    selectedPage,
    searchText,
    otherUserName
  )
  .then((subset: CollectionItemSubset) => {
    /* ... */
  })

/* ... */

See use case implementation. This use case requires the following parameters:

  • roleIds is an array of user role identifiers to filter the results. At least one roleId must be specified.
  • collectionItemTypes is an array of collection item types to filter the results. At least one collectionItemType must be specified.
  • publishingStatuses is an array of publishing statuses to filter the results. At least one publishingStatus must be specified.

This use case supports the following optional parameters depending on the search goals:

  • limit: (number) Limit of items per page for pagination. (default is 10)
  • selectedPage: (number) the page of results to be returned. (default is 1)
  • searchText is an optional string to filter the results by.
  • otherUserName is an optional string to return the collection items of another user. If not set, the calling user will be used. Only superusers can use this parameter.

The CollectionItemSubsetreturned instance contains a property called totalItemCount which is necessary for pagination.

Get Collection Featured Items

Returns a FeaturedItem array containing the featured items of the requested collection, given the collection identifier or alias.

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

const collectionIdOrAlias = 12345

getCollectionFeaturedItems
  .execute(collectionId)
  .then((featuredItems: FeaturedItem[]) => {
    /* ... */
  })
  .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.

Get Collections for Linking

Returns an array of CollectionSummary (id, alias, displayName) representing the Dataverse collections to which a given Dataverse collection or Dataset may be linked.

This use case supports an optional searchTerm to filter by collection name.

Example calls:
import { getCollectionsForLinking } from '@iqss/dataverse-client-javascript'

/* ... */

// Case 1: For a given Dataverse collection (by numeric id or alias)
const collectionIdOrAlias: number | string = 'collectionAlias' // or 123
const searchTerm = 'searchOn'

getCollectionsForLinking
  .execute('collection', collectionIdOrAlias, searchTerm)
  .then((collections) => {
    // collections: CollectionSummary[]
    /* ... */
  })
  .catch((error: Error) => {
    /* ... */
  })

/* ... */

// Case 2: For a given Dataset (by persistent identifier)
const persistentId = 'doi:10.5072/FK2/J8SJZB'

getCollectionsForLinking
  .execute('dataset', persistentId, searchTerm)
  .then((collections) => {
    // collections: CollectionSummary[]
    /* ... */
  })
  .catch((error: Error) => {
    /* ... */
  })

// Case 3: [alreadyLinked] Optional flag. When true, returns collections currently linked (candidates to unlink). Defaults to false.
const alreadyLinked = true

getCollectionsForLinking
  .execute('dataset', persistentId, searchTerm, alreadyLinked)
  .then((collections) => {
    // collections: CollectionSummary[]
    /* ... */
  })
  .catch((error: Error) => {
    /* ... */
  })

See use case implementation.

Notes:

  • When the first argument is 'collection', the second argument can be a numeric collection id or a collection alias.
  • When the first argument is 'dataset', the second argument must be the dataset persistent identifier string (e.g., doi:...).

Collections Write Use Cases

Create a Collection

Creates a new Collection, given a CollectionDTO object and an optional parent collection identifier, which defaults to :root.

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

/* ... */

const collectionDTO: CollectionDTO = {
  alias: alias,
  name: 'Test Collection',
  contacts: ['dataverse@test.com'],
  type: CollectionType.DEPARTMENT
}

createCollection.execute(collectionDTO).then((createdCollectionId: number) => {
  /* ... */
})

/* ... */

See use case implementation.

The above example creates the new collection in the root collection since no collection identifier is specified. If you want to create the collection in a different collection, you must add the collection identifier as a second parameter in the use case call.

The use case returns a number, which is the identifier of the created collection.

Update a Collection

Updates an existing collection, given a collection identifier and a CollectionDTO including the updated collection data.

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

/* ... */

const collectionIdOrAlias = 12345
const collectionDTO: CollectionDTO = {
  alias: alias,
  name: 'Updated Collection Name',
  contacts: ['dataverse@test.com'],
  type: CollectionType.DEPARTMENT
}

updateCollection.execute(collectionIdOrAlias, collectionDTO)

/* ... */

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).

Publish a Collection

Publishes a Collection, given the collection identifier.

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

/* ... */

const collectionIdOrAlias = 12345

publishCollection.execute(collectionIdOrAlias)

/* ... */

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

See use case definition.

Delete a Collection

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

/* ... */

const collectionIdOrAlias = 12345

deleteCollection.execute(collectionIdOrAlias)

/* ... */

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

See use case definition.

Update Collection Featured Items

Updates all featured items, given a collection identifier and a FeaturedItemsDTO.

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

/* ... */

const collectionIdOrAlias = 12345

updateCollectionFeaturedItems.execute(collectionIdOrAlias).then((featuredItems: FeaturedItem[]) => {
  /* ... */
})

/* ... */

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

See use case definition.

Delete Collection Featured Items

Deletes all featured items from a collection, given a collection identifier.

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

/* ... */

const collectionIdOrAlias = 12345

deleteCollectionFeaturedItems.execute(collectionIdOrAlias)

/* ... */

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

See use case definition.

Delete A Collection Featured Item

Deletes a single featured item, given a featured item id.

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

/* ... */

const featuredItemId = 12345

deleteCollectionFeaturedItem.execute(featuredItemId)

/* ... */

See use case definition.

Templates

Templates Read Use Cases

Get a Template

Returns a Template by its template id.

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

const templateId = 12345

getTemplate.execute(templateId).then((template: Template) => {
  /* ... */
})

See use case definition.

Get Templates By Collection Id

Returns a Template array containing the templates of the requested collection, given the collection identifier or alias.

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

const collectionIdOrAlias = 12345

getTemplatesByCollectionId.execute(collectionIdOrAlias).then((template: Template[]) => {
  /* ... */
})

See use case definition.

Templates Write Use Cases

Create a Template

Creates a template for a given Dataverse collection id or alias.

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

const collectionAlias = ':root'
const template: CreateTemplateDTO = {
  name: 'Dataverse template',
  isDefault: true,
  fields: [
    {
      typeName: 'author',
      typeClass: 'compound',
      multiple: true,
      value: [
        {
          authorName: { typeName: 'authorName', value: 'Belicheck, Bill' },
          authorAffiliation: { typeName: 'authorIdentifierScheme', value: 'ORCID' }
        }
      ]
    }
  ],
  instructions: [{ instructionField: 'author', instructionText: 'The author data' }]
}

await createTemplate.execute(template, collectionAlias)

See use case implementation.

Delete a Template

Deletes a template by its template id.

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

const templateId = 12345

await deleteTemplate.execute(templateId)

See use case definition.

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.

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.

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.

There is an optional second 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.

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 In Other Formats

Retrieves the citation for a dataset in a specified bibliographic format.

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

/* ... */

const datasetId = 2
const datasetVersionId = '1.0'

getDatasetCitationInOtherFormats
  .execute(datasetId, datasetVersionId, format)
  .then((citationText: FormattedCitation) => {
    /* ... */
  })

/* ... */

See use case implementation.

Supported formats include 'EndNote' (XML), 'RIS' (plain text), 'BibTeX' (plain text), 'CSLJson' (JSON), and 'Internal' (HTML). The response contains the raw citation content in the requested format, the format type, and the content type (MIME type).

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.

Get Differences between Two Dataset Versions

Returns an instance of DatasetVersionDiff that contains the differences between two Dataset Versions.

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

/* ... */

const datasetId = 'doi:10.77777/FK2/AAAAAA'
const oldVersion = '1.0'
const newVersion = '2.0'

getDatasetVersionDiff
  .execute(datasetId, oldVersion, newVersion)
  .then((versionDiff: DatasetVersionDiff) => {
    /* ... */
  })

/* ... */

See use case implementation.

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

The oldVersion and newVersion parameters specify the versions of the dataset to compare.

There is an optional third parameter called includeDeaccessioned, by default, deaccessioned dataset versions are not included in the search when applying the :latest or :latest-published identifiers. If not set, the default value is false.

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.

Get Dataset Versions Summaries

Returns the total count of versions and an array of DatasetVersionSummaryInfo that contains information about what changed in every specific version.

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

/* ... */

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

getDatasetVersionsSummaries
  .execute(datasetId)
  .then((datasetVersionsSummaries: DatasetVersionSummarySubset) => {
    /* ... */
  })

/* ... */

See use case implementation.

  • The datasetId parameter can be a string, for persistent identifiers, or a number, for numeric identifiers.
  • limit: (number) Limit for pagination.
  • offset: (number) Offset for pagination.

Get Dataset Linked Collections

Returns an array of DatasetLinkedCollection that contains the collections linked to a dataset.

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

/* ... */

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

getDatasetLinkedCollections
  .execute(datasetId)
  .then((datasetLinkedCollections: DatasetLinkedCollection[]) => {
    /* ... */
  })

/* ... */

See use case implementation.

Get Dataset Available Dataset Types

Returns a list of available dataset types that can be used at dataset creation. By default, only the type "dataset" is returned.

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

/* ... */

getDatasetAvailableDatasetTypes.execute().then((datasetTypes: DatasetType[]) => {
  /* ... */
})

See use case implementation.

Get Dataset Available Dataset Type

Returns an available dataset types that can be used at dataset creation.

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

/* ... */

getDatasetAvailableDatasetType.execute().then((datasetType: DatasetType) => {
  /* ... */
})

See use case implementation.

Datasets Write Use Cases

Create a Dataset

Creates a new Dataset in a collection, given a DatasetDTO object, an optional collection identifier, which defaults to :root, and an optional dataset type.

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 datasetDTO: DatasetDTO = {
  metadataBlockValues: [
    {
      name: 'citation',
      fields: {
        title: 'New Dataset',
        author: [
          {
            authorName: 'John Doe',
            authorAffiliation: 'Dataverse'
          },
          {
            authorName: 'John Lee',
            authorAffiliation: 'Dataverse'
          }
        ],
        datasetContact: [
          {
            datasetContactEmail: 'johndoe@dataverse.com',
            datasetContactName: 'John'
          }
        ],
        dsDescription: [
          {
            dsDescriptionValue: 'This is the description of our new dataset'
          }
        ],
        subject: 'Earth and Environmental Sciences'

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

createDataset.execute(datasetDTO).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. If you want the dataset type to be anything other than dataset, first check available dataset types and then add the name of the dataset type as the third parameter.

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

Update a Dataset

Updates an existing Dataset, given a DatasetDTO with the updated information.

If a draft of the dataset already exists, the metadata of that draft is overwritten; otherwise, a new draft is created with the updated metadata.

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 { updateDataset } from '@iqss/dataverse-client-javascript'

/* ... */

const datasetId = 1
const datasetDTO: DatasetDTO = {
  metadataBlockValues: [
    {
      name: 'citation',
      fields: {
        title: 'Updated Dataset',
        author: [
          {
            authorName: 'John Doe',
            authorAffiliation: 'Dataverse'
          },
          {
            authorName: 'John Lee',
            authorAffiliation: 'Dataverse'
          }
        ],
        datasetContact: [
          {
            datasetContactEmail: 'johndoe@dataverse.com',
            datasetContactName: 'John'
          }
        ],
        dsDescription: [
          {
            dsDescriptionValue: 'This is the description of our new dataset'
          }
        ],
        subject: 'Earth and Environmental Sciences'

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

updateDataset.execute(datasetId, datasetDTO)

/* ... */

See use case implementation.

Update a Dataset License

Updates the license of a dataset by applying it to the draft version. If no draft exists, a new one is automatically created by the API. Supports predefined licenses (by name) or custom terms of use and access.

Example calls:
import {
  updateDatasetLicense,
  DatasetLicenseUpdateRequest
} from '@iqss/dataverse-client-javascript'

/* ... */

const datasetId = 1

const predefinedPayload: DatasetLicenseUpdateRequest = { name: 'CC BY 4.0' }
await updateDatasetLicense.execute(datasetId, predefinedPayload)

const customPayload: DatasetLicenseUpdateRequest = {
  customTerms: {
    termsOfUse: 'Your terms of use',
    confidentialityDeclaration: 'Your confidentiality declaration',
    specialPermissions: 'Your special permissions',
    restrictions: 'Your restrictions',
    citationRequirements: 'Your citation requirements',
    depositorRequirements: 'Your depositor requirements',
    conditions: 'Your conditions',
    disclaimer: 'Your disclaimer'
  }
}

updateDatasetLicense.execute(datasetId, customPayload)

See use case implementation.

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

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)

/* ... */

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.
Superusers can pass VersionUpdateType.UPDATE_CURRENT to update metadata without changing the version number. This will overwrite the latest published version and therefore will only work for a dataset that has been published at least once. *Note that this will only work also if there were no file changes in the update.
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
  • VersionUpdateType.UPDATE_CURRENT

Update Terms of Access

Updates the Terms of Access for restricted files on a dataset.

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

/* ... */

const datasetId = 3

await updateTermsOfAccess.execute(datasetId, {
  fileAccessRequest: true,
  termsOfAccessForRestrictedFiles: 'Your terms of access for restricted files',
  dataAccessPlace: 'Your data access place',
  originalArchive: 'Your original archive',
  availabilityStatus: 'Your availability status',
  contactForAccess: 'Your contact for access',
  sizeOfCollection: 'Your size of collection',
  studyCompletion: 'Your study completion'
})

See use case implementation.

Notes:

  • If the dataset is already published, this action creates a DRAFT version containing the new terms.
  • Unspecified fields are treated as omissions: sending only fileAccessRequest will update that field and leave all other terms absent (undefined). In practice, the new values you send fully replace the previous set of terms — so if you omit a field, you are effectively clearing it unless you include its original value in the new input.

Deaccession a Dataset

Deaccession a Dataset, given its identifier, version, and deaccessionDatasetDTO to perform.

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

/* ... */

const datasetId = 1
const version = ':latestPublished'
const deaccessionDatasetDTO = {
  deaccessionReason: 'Description of the deaccession reason.',
  deaccessionForwardURL: 'https://demo.dataverse.org'
}

deaccessionDataset.execute(datasetId, version, deaccessionDatasetDTO)

/* ... */

See use case implementation. The datasetId parameter can be a string for persistent identifiers, or a number for numeric identifiers. The version parameter should be a string or a DatasetNotNumberedVersion enum value.

You cannot deaccession a dataset more than once. If you call this endpoint twice for the same dataset version, you will get a not found error on the second call, since the dataset you are looking for will no longer be published since it is already deaccessioned.

Delete a Draft Dataset

Delete a Draft Dataset, given its identifier.

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

/* ... */

const datasetId = 1

deleteDatasetDraft.execute(datasetId)

/* ... */

See use case implementation.

The datasetId parameter is a number for numeric identifiers or string for persistent identifiers.

If you try to delete a dataset without draft version, you will get a not found error.

Link a Dataset

Creates a link between a Dataset and a Collection.

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

/* ... */

const datasetId = 1
const collectionAlias = 'collection-alias'

linkDataset.execute(datasetId, collectionAlias)

/* ... */

See use case implementation.

Unlink a Dataset

Removes a link between a Dataset and a Collection.

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

/* ... */

const datasetId = 1
const collectionAlias = 'collection-alias'

unlinkDataset.execute(datasetId, collectionAlias)

/* ... */

See use case implementation.

Get Download Count of a Dataset

Total number of downloads requested for a dataset, given a dataset numeric identifier,

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

/* ... */

const datasetId = 1
const includeMDC = true

getDatasetDownloadCount
  .execute(datasetId, includeMDC)
  .then((datasetDownloadCount: DatasetDownloadCount) => {
    /* ... */
  })

/* ... */

See use case implementation.

The datasetId parameter is a number for numeric identifiers or string for persistent identifiers. The includeMDC parameter is optional.

  • Setting includeMDC to True will ignore the MDCStartDate setting and return a total count.
  • If MDC isn't enabled, the download count will return a total count, without MDCStartDate.
  • If MDC is enabled but the includeMDC is false, the count will be limited to the time before MDCStartDate

Get Dataset Available Categories

Returns a list of available file categories that may be applied to the files of a given dataset.

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

/* ... */

const datasetId = 1

getDatasetAvailableCategories.execute(datasetId).then((categories: String[]) => {
  /* ... */
})

See use case implementation.

The datasetId parameter is a number for numeric identifiers or string for persistent identifiers.

<<<<<<< HEAD

Get Dataset Templates

Returns a DatasetTemplate array containing the dataset templates of the requested collection, given the collection identifier or alias.

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

const collectionIdOrAlias = 12345

getDatasetTemplates.execute(collectionIdOrAlias).then((datasetTemplates: DatasetTemplate[]) => {
  /* ... */
})

See use case definition.

Get Dataset Storage Driver

Returns a StorageDriver instance with storage driver configuration for a dataset, including properties like name, type, label, and upload/download capabilities.

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

/* ... */

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

getDatasetStorageDriver.execute(datasetId).then((storageDriver: StorageDriver) => {
  /* ... */
})

/* ... */

See use case implementation.

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

develop

Add a Dataset Type

Adds a dataset types that can be used at dataset creation.

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

/* ... */

addDatasetType.execute(datasetType).then((datasetType: DatasetType) => {
  /* ... */
})

See use case implementation.

Link Dataset Type with Metadata Blocks

Link a dataset type with metadata blocks.

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

/* ... */

linkDatasetTypeWithMetadataBlocks.execute(datasetTypeId, ['geospatial']).then(() => {
  /* ... */
})

See use case implementation.

Set Available Licenses For Dataset Type

Set available licenses for dataset type.

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

/* ... */

setAvailableLicensesForDatasetType.execute(datasetTypeId, ['CC BY 4.0']).then(() => {
  /* ... */
})

See use case implementation.

Delete a Dataset Type

Delete a dataset type.

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

/* ... */

deleteDatasetType.execute(datasetTypeId).then(() => {
  /* ... */
})

See use case implementation.

Files

Files read use cases

Get a File

Returns a FileModel 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: FileModel) => {
  /* ... */
})

/* ... */

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.

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 a File and its Dataset

Returns a tuple of FileModel and Dataset objects ([FileModel, 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: [FileModel, 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.

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 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) => {
    /* ... */
  })

/* ... */

Files write use cases

File Uploading Use Cases

These use cases are designed to facilitate the uploading of files to a remote S3 storage and subsequently adding them to a dataset. This process involves two main steps / use cases:

  1. Uploading a file to remote S3 storage and obtaining a storage identifier.
  2. Adding one or more uploaded files to the dataset using the obtained storage identifiers.

This use case flow is entirely based on the Direct Upload API as described in the Dataverse documentation: https://guides.dataverse.org/en/latest/developers/s3-direct-upload-api.html

Upload File

This use case uploads a file to a remote S3 storage and returns the storage identifier associated with the file.

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

/* ... */

const datasetId: number | string = 123
const file = new File(['content'], 'example.txt', { type: 'text/plain' })
const progressCallback = (progress) => console.log(`Upload progress: ${progress}%`)
const abortController = new AbortController()

uploadFile.execute(datasetId, file, progressCallback, abortController).then((storageId) => {
  console.log(`File uploaded successfully with storage ID: ${storageId}`)
})

/* ... */

See use case implementation.

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

The file parameter is a subclass of Blob (Binary Large Object) that represents a file.

The progress parameter represents a callback function that allows the caller to monitor the progress of the file uploading operation.

The abortController is a built-in mechanism in modern web browsers that allows the cancellation of asynchronous operations. It works in conjunction with an associated AbortSignal, which will be passed to the file uploading API calls to monitor whether the operation should be aborted, if the caller decides to cancel the operation midway.

Add Uploaded Files to the Dataset

This use case involves adding files that have been previously uploaded to remote storage to the dataset.

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

/* ... */

const datasetId: number | string = 123
const uploadedFileDTOs: UploadedFileDTO[] = [
  {
    fileName: 'the-file-name',
    storageId: 'localstack1://mybucket:19121faf7e7-2c40322ff54e',
    checksumType: 'md5',
    checksumValue: 'ede3d3b685b4e137ba4cb2521329a75e',
    mimeType: 'text/plain'
  }
]

addUploadedFilesToDataset.execute(datasetId, uploadedFileDTOs).then(() => {
  console.log('Files added to the dataset successfully.')
})

/* ... */

See use case implementation.

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

The uploadedFileDTOs parameter is an array of UploadedFileDTO and includes properties related to the uploaded files. Some of these properties should be calculated from the uploaded File Blob objects and the resulting storage identifiers from the Upload File use case.

Error handling:

These use cases involve multiple steps, each associated with different API calls, which introduce various points of potential failure. Therefore, different error types have been implemented according to their nature, all of which extend DirectUploadClientError.

The following errors might arise from the UploadFile use case:

  • UrlGenerationError: This error indicates that the destination URLs for file upload could not be generated successfully.

  • FilePartUploadError: This error indicates that the retry limit has been exceeded for uploading one of the parts of a multipart file. If this error is received, it is because the abort endpoint has been successfully called.

  • MultipartAbortError: This error indicates that it was not possible to call the abort endpoint after an error occurred during the upload of one of the parts of a multipart file.

  • MultipartCompletionError: This error indicates that the multipart upload could not be completed due to an error encountered when calling the completion endpoint.

  • FileUploadError: This error indicates that there has been an error while uploading a single-part file.

  • FileUploadCancelError: This error is received when the caller cancels the operation through the abort controller.

The following error might arise from the AddUploadedFileToDataset use case:

  • AddUploadedFileToDatasetError: This error indicates that there was an error while adding the uploaded file to the dataset.

Update File Metadata

Updates Metadata of a File.

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

/* ... */

const fileId: number | string = 123
const updateFileMetadataDTO = {
  label: 'myfile.txt',
  directoryLabel: 'mydir',
  description: 'My description bbb.',
  categories: ['Data'],
  restrict: false
}

await updateFileMetadata.execute(fileId, updateFileMetadataDTO).then(() => {
  console.log(`File updated successfully`)
})

See use case implementation.

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

Update File Categories

Updates Categories of a File.

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

/* ... */

const fileId: number | string = 123
const categories = ['category 1', 'category 1']
const replace = true

await updateFileCategories.execute(fileId, categories, replace).then(() => {
  console.log(`File updated successfully`)
})

See use case implementation.

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

Update File Tabular Tags

Updates Tabular Tags of a File.

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

/* ... */

const fileId: number | string = 123
const tabularTags = ['Surveys']

await updateFileTabularTags.execute(fileId, tabularTags, replace).then(() => {
  console.log(`File updated successfully`)
})

See use case implementation.

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

Delete a File

Deletes a File.

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

/* ... */

const fileId = 12345

deleteFile.execute(fileId)

/* ... */

See use case implementation.

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

Note that the behavior of deleting files depends on if the dataset has ever been published or not.

  • If the dataset has never been published, the file will be deleted forever.
  • If the dataset has published, the file is deleted from the draft (and future published versions).
  • If the dataset has published, the deleted file can still be downloaded because it was part of a published version.

Replace a File

Replaces a File. Currently working for already uploaded S3 bucket files.

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

/* ... */

const fileId = 12345
const uploadedFileDTO: UploadedFileDTO = {
  fileName: 'the-file-name',
  storageId: 'localstack1://mybucket:19121faf7e7-2c40322ff54e',
  checksumType: 'md5',
  checksumValue: 'ede3d3b685b4e137ba4cb2521329a75e',
  mimeType: 'text/plain'
}

replaceFile.execute(fileId, uploadedFileDTO).then((newFileId: number) => {
  /* ... */
})

/* ... */

See use case implementation.

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

The uploadedFileDTO parameter is a UploadedFileDTO and includes properties related to the uploaded files. Some of these properties should be calculated from the uploaded File Blob objects and the resulting storage identifiers from the Upload File use case.

The use case returns a number, which is the identifier of the new file.

Restrict or Unrestrict a File

Restrict or unrestrict an existing file, given a RestrictFileDTO

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

/* ... */

const fileId = 12345
const restrictFileDTO = {
  restrict: true,
  enableAccessRequest: false,
  termsOfAccess: 'terms of access'
}

restrictFile.execute(fileId, restrictFileDTO)

/* ... */

See use case implementation.

The fileId parameter can be a string, for persistent identifiers, or a number, for numeric identifiers. If restrict is false then enableAccessRequest and termsOfAccess are ignored If restrict is true and enableAccessRequest is false then termsOfAccess is required. The enableAccessRequest and termsOfAccess are applied to the Draft version of the Dataset and affect all of the restricted files in said Draft version.

Is File Deleted

Check if the file has been deleted, return a boolean.

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

/* ... */

const fileId = 12345

await isFileDeleted.execute(fileId).then((isDeleted: boolean) => {
  /* ... */
})

/* ... */

See use case implementation.

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

Get File Version Summaries

Get the file versions summaries, return a total count of versions and a list of summaries for each version

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

/* ... */

const fileId = 1

getFileVersionSummaries.execute(fileId).then((fileVersionSummaries: fileVersionSummarySubset) => {
  /* ... */
})

/* ... */

See use case implementation.

  • limit: (number) Limit for pagination.
  • offset: (number) Offset for pagination.

Metadata Blocks

Metadata Blocks read use cases

Get All Facetable Metadata Fields

Returns a MetadataFieldInfo array containing all facetable metadata fields defined in the installation.

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

/* ... */

getAllFacetableMetadataFields.execute().then((metadataFieldInfos: MetadataFieldInfo[]) => {
  /* ... */
})

/* ... */

See use case implementation.

Get All Metadata Blocks

Returns a MetadataBlock array containing the metadata blocks defined in the installation.

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

/* ... */

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

/* ... */

See use case implementation.

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.

There is a third optional parameter called datasetType which will include additional fields from metadata blocks linked to the provided type, if any. Before using this parameter, you will probably want to list available dataset types for your installation.

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.

Get Current API Token

Returns the current ApiTokenInfo corresponding to the current authenticated user.

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

/* ... */

getCurrentApiToken.execute().then((apiTokenInfo: ApiTokenInfo) => {
  /* ... */
})

/* ... */

See use case implementation.

Users write use cases

Delete Current API Token

Deletes the API token of the current authenticated user.

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

/* ... */

deleteCurrentApiToken.execute()

/* ... */

See use case implementation.

Recreate Current API Token

Reacreates the API token of the current authenticated user and returns the new ApiTokenInfo.

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

/* ... */

recreateCurrentApiToken.execute().then((apiTokenInfo: ApiTokenInfo) => {
  /* ... */
})

/* ... */

See use case implementation.

Register User

Register a new user, given a UserDTO

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

/* ... */

const userDTO: UserDTO = {
  username: 'johndoe',
  firstName: 'John',
  lastName: 'Doe',
  emailAddress: 'johndoe@email.com',
  position: '',
  affiliation: '',
  termsAccepted: true
}

registerUser.execute(userDTO)

/* ... */

See use case implementation.

Roles

Get User Selectable Roles

Returns a Role array that the calling user can use as filters when searching within their data.

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

/* ... */

getUserSelectableRoles.execute().then((roles: Role[]) => {
  /* ... */
})

/* ... */

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.

Get Application Terms of Use

Returns the Application Terms of Use. If you have enabled Internationalization you can pass a two-character language code (e.g. “en”) as the lang parameter.

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

/* ... */

getApplicationTermsOfUse.execute().then((termsOfUse: string) => {
  /* ... */
})

/* ... */

See use case implementation.

Get Available Dataset Metadata Export Formats

Returns a DatasetMetadataExportFormats object containing the available dataset metadata export formats.

Example call:
import {
  getAvailableDatasetMetadataExportFormats,
  DatasetMetadataExportFormats
} from '@iqss/dataverse-client-javascript'

/* ... */

getAvailableDatasetMetadataExportFormats
  .execute()
  .then((datasetMetadataExportFormats: DatasetMetadataExportFormats) => {
    /* ... */
  })

/* ... */

See use case implementation.

Licenses

Get Available Standard License Terms

Returns a list of available standard licenses that can be selected for a dataset.

Example call:
import { getAvailableStandardLicenses, License } from '@iqss/dataverse-client-javascript'

/* ... */

getAvailableStandardLicenses.execute().then((licenses: License[]) => {
  /* ... */
})

See use case implementation.

Contact

Send Feedback to Object Contacts

Returns a Contact object, which contains contact return information, showing fromEmail, subject, body.

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

/* ... */

const contactDTO: ContactDTO = {
  targedId: 1
  subject: 'Data Question',
  body: 'Please help me understand your data. Thank you!',
  fromEmail: 'test@gmail.com'
}

submitContactInfo.execute(contactDTO)

/* ... */

See use case implementation.

The above example would submit feedback to all contacts of a object where the object targetId = 1.

In ContactDTO, it takes the following information:

  • targetId: the numeric identifier of the collection, dataset, or datafile. Persistent ids and collection aliases are not supported. (Optional)
  • identifier: the alias of a collection or the persistence id of a dataset or datafile. (Optional)
  • subject: the email subject line.
  • body: the email body to send.
  • fromEmail: the email to list in the reply-to field.

Notifications

Get All Notifications by User

Returns a Notification array containing all notifications for the current authenticated user.

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

/* ... */

getAllNotificationsByUser.execute().then((notifications: Notification[]) => {
  /* ... */
})

/* ... */

See use case implementation.

Delete Notification

Deletes a specific notification for the current authenticated user by its ID.

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

/* ... */

const notificationId = 123

deleteNotification.execute(notificationId: number).then(() => {
  /* ... */
})

/* ... */

See use case implementation.

Get Unread Count

Returns the number of unread notifications for the current authenticated user.

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

/* ... */

getUnreadNotificationsCount.execute().then((count: number) => {
  console.log(`You have ${count} unread notifications`)
})

/* ... */

See use case implementation.

Mark As Read

Marks a specific notification as read for the current authenticated user. This operation is idempotent - marking an already-read notification as read will not cause an error.

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

/* ... */

const notificationId = 123

markNotificationAsRead.execute(notificationId).then(() => {
  console.log('Notification marked as read')
})

/* ... */

See use case implementation.

Search

Get Search Services

Returns all Search Services available in the installation.

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

/* ... */

getSearchServices.execute().then((searchServices: SearchService[]) => {
  /* ... */
})

/* ... */

See use case implementation.

External Tools

External Tools Read Use Cases

Get External Tools

Returns an array of ExternalTool objects, which represent the external tools available in the installation.

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

/* ... */

getExternalTools.execute().then((externalTools: ExternalTool[]) => {
  /* ... */
})

/* ... */

See use case implementation.

Get Dataset External Tool Resolved

Returns an instance of DatasetExternalToolResolved, which contains the resolved URL for accessing an external tool that operates at the dataset level.

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

/* ... */
const toolId = 1
const datasetId = 2
const getExternalToolDTO: GetExternalToolDTO = {
  preview: true,
  locale: 'en'
}

getDatasetExternalToolResolved
  .execute(toolId, datasetId, getExternalToolDTO)
  .then((datasetExternalToolResolved: DatasetExternalToolResolved) => {
    /* ... */
  })
/* ... */

See use case implementation.

Get File External Tool Resolved

Returns an instance of FileExternalToolResolved, which contains the resolved URL for accessing an external tool that operates at the file level.

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

/* ... */
const toolId = 1
const fileId = 2
const getExternalToolDTO: GetExternalToolDTO = {
  preview: true,
  locale: 'en'
}

getFileExternalToolResolved
  .execute(toolId, fileId, getExternalToolDTO)
  .then((fileExternalToolResolved: FileExternalToolResolved) => {
    /* ... */
  })
/* ... */

See use case implementation.