Qualtrics API Tasks

Helpers to perform common tasks using the Qualtrics API. This is an exercise to avoid code reuse in my own projects. Use at your own risk.

Prerequisites

This project requires NodeJS (version >= 18) and NPM. Node and NPM are really easy to install. To make sure you have them available on your machine, try running the following command.

$ npm -v && node -v
10.2.4
v20.11.1

PNPM is a awesome alternative to NPM and is recommended.

Table of contents

• Qualtrics API Tasks
  • Prerequisites
  • Table of contents
  • Getting Started
  • Installation
  • Usage
  • API
    • createConnection
    • Actions
      • Authentication
      • Contacts
      • Distributions
      • Responses
      • Mailing Lists
      • Messages
      • Utilities
    • Responses
  • Contributing
  • Versioning
  • Authors
  • License

Getting Started

These instructions will get you a copy of the project up and running on your local machine for development and testing purposes. See deployment for notes on how to deploy the project on a live system.

Installation

BEFORE YOU INSTALL: please read the prerequisites

To install and set up the library, run:

$ npm i @b-jones-rfd/qualtrics-api-tasks

Or if you prefer using Yarn:

$ yarn add @b-jones-rfd/qualtrics-api-tasks

Or for PNPM:

$ pnpm add @b-jones-rfd/qualtrics-api-tasks

Usage

Instance Methods

Actions can be performed against the Qualtrics API using instance methods on a Qualtrics Connection instance.

If authenticating using OAuth 2.0 use the getBearerToken action with a Client ID and secret to obtain a bearer token. If authenticating with an API Token pass the token as a connection option using the apiToken property.

import { createConnection } from '@b-jones-rfd/qualtrics-api-tasks'

const connectionOptions = {
  datacenterId: 'az1',
  apiToken: 'my API Token', // optional
  timeout: 20 * 1000, // optional timeout in milliseconds, default is 30 seconds
}

const connection: Connection = createConnection(connectionOptions)

async function getBearerToken(clientId: string, clientSecret: string) {
  const result = await connection.getBearerToken({ clientId, clientSecret })
  if (result.success) return result.data
  else throw new Error(result.error)
}

Factory Action Methods

Additionally, for single use or reduced import size, action factory methods can be imported directly. Call the factory method with a SiteConnectionOptions object to return an asynchronous action function that can be called directly.

import { testConnection } from '@b-jones-rfd/qualtrics-api-tasks'

async function testMyQualtricsConnection() {
  const action = testConnection(connectionOptions)
  const result = await action()
  if (result.success) return result.data
  else throw new Error(result.error)
}

API

createConnection

Create a Qualtrics API Connection instance.

type ConnectionFactory = (options: ConnectionOptions) => Connection

ConnectionOptions

type ConnectionOptions = {
  datacenterId: string
  apiToken?: string
  timeout?: number
}

datacenterId

| Type | Description | Example | Required | | ------ | ------------------------ | ------- | -------- | | string | Qualtrics Data Center Id | 'ca1' | Y |

apiToken

| Type | Description | Required | | ------ | ------------------- | -------- | | string | Qualtrics API Token | N |

timeout

| Type | Default value | Description | Example | Required | | ------ | ------------- | ------------------------- | ------- | -------- | | number | 30000 | Qualtrics request timeout | 1000 | N |

Actions

Connection instance action methods.

export type Action<TConfig, TResponse> = (
  options: TConfig
) => Promise<Result<TResponse>>

If using the actions directly call the factory method with a ConnectionOptions object to return an action that can be used to execute a Qualtrics action.

Authentication

getBearerToken(options)

Implements OAuth Authentication (Client Credentials) and returns the access token as the result data.

options

| Property | Type | Description | Required | | ------------ | ------ | --------------------------------- | -------- | | clientId | string | Quatrics Client ID | Y | | clientSecret | string | Qualtrics Client Password | Y | | scope | string | Qualtrics Client requested scopes | Y |

Contacts

getContactsImportStatus(options)

Implements Get Contacts Import Status

options

| Property | Type | Description | Required | | ------------- | ------ | --------------------- | -------- | | directoryId | string | Quatrics Directory ID | Y | | importId | string | Contacts Import ID | Y | | mailingListId | string | Mailing List ID | Y | | bearerToken | string | Valid Bearer Token | N |

getContactsImportSummary(options)

Implements Get Contacts Import Summary

options

| Property | Type | Description | Required | | ------------- | ------ | --------------------- | -------- | | directoryId | string | Quatrics Directory ID | Y | | importId | string | Contacts Import ID | Y | | mailingListId | string | Mailing List ID | Y | | bearerToken | string | Valid Bearer Token | N |

importContacts(options)

Implements Contact Import multistep process. This runs the following actions:

1. Start Contacts Import
2. Polls Get Contacts Import Status
3. Get Contacts Import Summary

options

| Property | Type | Description | Required | | --------------- | --------- | --------------------- | -------- | | directoryId | string | Quatrics Directory ID | Y | | mailingListId | string | Mailing List ID | Y | | contacts | Contact[] | Contacts array | Y | | transactionMeta | object | Transaction meta data | N | | bearerToken | string | Valid Bearer Token | N |

startContactsImport(options)

Implements Create Transaction Contacts Import

options

| Property | Type | Description | Required | | --------------- | --------- | --------------------- | -------- | | directoryId | string | Quatrics Directory ID | Y | | mailingListId | string | Mailing List ID | Y | | contacts | Contact[] | Contacts array | Y | | transactionMeta | object | Transaction meta data | N | | bearerToken | string | Valid Bearer Token | N |

Distributions

createDistribution(options)

Implements Create Distribution.

options

| Property | Type | Description | Required | Default | | ------------------ | ---------------------- | ---------------------------------- | -------- | ------- | | libraryId | string | Quatrics Library ID | Y | | | messageId | string | Qualtrics Message ID | Y | | | messageText | string | Message text to send | N | | | mailingListId | string | Mailing List ID | Y | | | contactId | string | Contact lookup ID for individual | N | | | transactionBatchId | string | Transaction Batch ID | N | | | fromEmail | string | Originating email | Y | | | replyToEmail | string | Email reply-to address | N | | | fromName | string | Email from name | Y | | | subject | string | Email subject | Y | | | surveyId | string | Qualtrics Survey ID | Y | | | expirationDate | Date | Distribution expiration date time | Y | | | type | enum | Individual, Multiple, or Anonymous | Y | | | embeddedData | Record<string, string> | Up to 10 subkeys | N | | | sendDate | Date | Date time to send | Y | | | bearerToken | string | Valid Bearer Token | N | |

createReminder(options)

Implements Create Reminder Distribution.

options

| Property | Type | Description | Required | | -------------- | ---------------------- | ------------------------ | -------- | | distributionId | string | Previous Distribution ID | Y | | libraryId | string | Quatrics Library ID | Y | | fromEmail | string | Originating email | Y | | messageId | string | Qualtrics Message ID | Y | | replyToEmail | string | Email reply-to address | N | | fromName | string | Email from name | Y | | subject | string | Email subject | Y | | embeddedData | Record<string, string> | Up to 10 subkeys | N | | sendDate | Date | Date time to send | Y | | bearerToken | string | Valid Bearer Token | N |

distributeSurveys(options)

Multistep process to execute a survey distribution. Runs the following actions:

1. Create Mailing List
2. Import Contacts
3. Create Distribution
4. Create Reminder

options

| Property | Type | Description | Required | Default | | ----------------------- | ---------------------- | ---------------------------------- | -------- | ------- | | directoryId | string | Quatrics Directory ID | Y | | | mailingListName | string | Mailing List Name | Y | | | ownerId | string | Owner ID | Y | | | prioritizeListMetadata | boolean | Import metadata as list metadata | N | false | | contacts | Contact[] | Contacts array | Y | | | transactionMeta | object | Transaction meta data | N | | | libraryId | string | Quatrics Library ID | Y | | | distributionMessageId | string | Distribution Message ID | Y | | | distributionMessageText | string | Message text to send | N | | | reminderMessageId | string | Reminder Message ID | Y | | | reminderMessageText | string | Reminder message text to send | N | | | transactionBatchId | string | Transaction Batch ID | N | | | fromEmail | string | Originating email | Y | | | replyToEmail | string | Email reply-to address | N | | | fromName | string | Email from name | Y | | | distributionSubject | string | Distribution email subject | Y | | | reminderSubject | string | Reminder email subject | Y | | | surveyId | string | Qualtrics Survey ID | Y | | | expirationDate | Date | Distribution expiration date time | Y | | | type | enum | Individual, Multiple, or Anonymous | Y | | | embeddedData | Record<string, string> | Up to 10 subkeys | N | | | distributionSendDate | Date | Date time to send distribution | Y | | | reminderSendDate | Date | Date time to send reminder | Y | | | bearerToken | string | Valid Bearer Token | N | |

getDistribution(options)

Implements Get Distribution

options

| Property | Type | Description | Required | | -------------- | ------ | ------------------ | -------- | | distributionId | string | Distribution ID | Y | | surveyId | string | Survey ID | Y | | bearerToken | string | Valid Bearer Token | N |

listDistributions(options)

Implements List Distributions

options

| Property | Type | Description | Required | Default | | ----------------------- | ------- | ------------------------------- | -------- | ------- | | surveyId | string | Quatrics Survey ID | Y | | | sendStartDate | Date | Export start date and time | Y | | | sendEndDate | Date | Export end date and time | Y | | | mailingListId | string | Mailing List ID | N | | | distributionRequestType | string | Distribution Request Type | N | | | skipToken | string | Pagination offset | N | | | useNewPaginationScheme | boolean | Use updated pagination | N | false | | pageSize | number | Distribution elements to return | N | 100 | | bearerToken | string | Valid Bearer Token | N | |

Responses

exportResponses(options)

Implements Survey Response File Export multistep process. Runs the following actions:

1. Start Response Export
2. Polls Get Response Export Progress
3. Get Response Export File

options

| Property | Type | Description | Required | Default | | ------------------------------- | -------- | ------------------------------------------- | -------- | ------- | | surveyId | string | Quatrics Survey ID | Y | | | startDate | Date | Export start date and time | Y | | | endDate | Date | Export end date and time | Y | | | format | Enum | File format | N | 'csv' | | breakoutSets | boolean | Split multi-value fields into columns | N | true | | compress | boolean | Compress final export | N | true | | exportResponsesInProgress | boolean | Only export not complete | N | false | | filterId | string | Return responses matching id | N | | | formatDecimalAsComma | boolean | Use comma as decimal separator | N | false | | includeDisplayOrder | boolean | Include display order in export | N | false | | limit | number | Max responses to export | N | | | multiselectSeenUnansweredRecode | number | Recode seen, but unanswered for multiselect | N | | | newlineReplacement | string | Replace newline character with this | N | | | seenUnansweredRecode | number | Recode seen, but unanswered with this | N | | | timeZone | string | Timezone used to determine response date | N | 'UTC" | | useLabels | boolean | Export text of answer choice | N | false | | embeddedDataIds | string[] | Only export these embedded data fields | N | | | questionIds | string[] | Only export these question IDs | N | | | surveyMetadataIds | string[] | Only export these metadata fields | N | | | continuationToken | string | Previous export continuation token | N | | | allowContinuation | boolean | Request continuation token | N | false | | includeLabelColumns | boolean | Export two columns, recode and labels | N | false | | sortByLastModifiedDate | boolean | Sort responses by modified date | N | false | | bearerToken | string | Valid Bearer Token | N | |

getResponseExportFile(options)

Implements Get Response Export File

options

| Property | Type | Description | Required | | ----------- | ------ | ------------------ | -------- | | surveyId | string | Quatrics Survey ID | Y | | fileId | string | File ID | Y | | bearerToken | string | Valid Bearer Token | N |

getResponseExportProgress(options)

Implements Get Response Export Progress

options

| Property | Type | Description | Required | | ---------------- | ------ | ------------------ | -------- | | surveyId | string | Quatrics Survey ID | Y | | exportProgressId | string | Progress ID | Y | | bearerToken | string | Valid Bearer Token | N |

Mailing Lists

createMailingList(options)

Implements Create Mailing List

options

| Property | Type | Description | Required | Default | | ---------------------- | ------- | -------------------------------- | -------- | ------- | | directoryId | string | Quatrics Directory ID | Y | | | name | string | Mailing List Name | Y | | | ownerId | string | Owner ID | Y | | | prioritizeListMetadata | boolean | Import metadata as list metadata | N | false | | bearerToken | string | Valid Bearer Token | N | |

Messages

listLibraryMessages(options)

Implements List Library Messages

options

| Property | Type | Description | Required | | ----------- | ------ | ------------------- | -------- | | libraryId | string | Quatrics Library ID | Y | | category | string | Message category | N | | offset | number | Pagination offset | N | | bearerToken | string | Valid Bearer Token | N |

startResponseExports(options)

Implements Start Response Exports

options

| Property | Type | Description | Required | Default | | ------------------------------- | -------- | ------------------------------------------- | -------- | ------- | | surveyId | string | Quatrics Survey ID | Y | | | startDate | Date | Export start date and time | Y | | | endDate | Date | Export end date and time | Y | | | format | Enum | File format | N | 'csv' | | breakoutSets | boolean | Split multi-value fields into columns | N | true | | compress | boolean | Compress final export | N | true | | exportResponsesInProgress | boolean | Only export not complete | N | false | | filterId | string | Return responses matching id | N | | | formatDecimalAsComma | boolean | Use comma as decimal separator | N | false | | includeDisplayOrder | boolean | Include display order in export | N | false | | limit | number | Max responses to export | N | | | multiselectSeenUnansweredRecode | number | Recode seen, but unanswered for multiselect | N | | | newlineReplacement | string | Replace newline character with this | N | | | seenUnansweredRecode | number | Recode seen, but unanswered with this | N | | | timeZone | string | Timezone used to determine response date | N | 'UTC" | | useLabels | boolean | Export text of answer choice | N | false | | embeddedDataIds | string[] | Only export these embedded data fields | N | | | questionIds | string[] | Only export these question IDs | N | | | surveyMetadataIds | string[] | Only export these metadata fields | N | | | continuationToken | string | Previous export continuation token | N | | | allowContinuation | boolean | Request continuation token | N | false | | includeLabelColumns | boolean | Export two columns, recode and labels | N | false | | sortByLastModifiedDate | boolean | Sort responses by modified date | N | false | | bearerToken | string | Valid Bearer Token | N | |

Utilities

testConnection(bearerToken)

| Parameter | Type | Description | Required | | ----------- | ------ | ------------------ | -------- | | bearerToken | string | Valid Bearer Token | N |

Responses

Responses are provided based on the Result type. Success can be determined by checking the success property.

export type Result<TResponse> = Success<TResponse> | Failure

Success

Response is returned in the data property.

type Success<TResponse> = { success: true; data: TResponse }

Failure

Errors are returned in the error property.

type Failure = { success: false; error: string }

Contributing

This is a pet project to save me time at work. It is still under development and you should use at your own risk.

Versioning

We use SemVer for versioning. For the versions available, see the tags on this repository.

Authors

• B Jones RFD - Package Noob - B-Jones-RFD

License

MIT License