@b-jones-rfd/qualtrics-api-tasks 0.3.0 → 0.3.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +6 -0
- package/README.md +171 -133
- package/package.json +1 -1
package/CHANGELOG.md
CHANGED
package/README.md
CHANGED
|
@@ -1,6 +1,9 @@
|
|
|
1
|
+
|
|
2
|
+
[](https://www.npmjs.com/package/@b-jones-rfd/qualtrics-api-tasks)
|
|
3
|
+
|
|
1
4
|
[](https://github.com/prettier/prettier)
|
|
2
5
|
|
|
3
|
-
#
|
|
6
|
+
# Qualtrics API Tasks
|
|
4
7
|
|
|
5
8
|
Helpers to perform common tasks using the [Qualtrics API](https://api.qualtrics.com/). This is an exercise to avoid code reuse in my own projects. Use at your own risk.
|
|
6
9
|
|
|
@@ -17,7 +20,7 @@ $ npm -v && node -v
|
|
|
17
20
|
v20.11.1
|
|
18
21
|
```
|
|
19
22
|
|
|
20
|
-
[PNPM]
|
|
23
|
+
[PNPM](https://pnpm.io/) is a awesome alternative to NPM and is recommended.
|
|
21
24
|
|
|
22
25
|
## Table of contents
|
|
23
26
|
|
|
@@ -30,6 +33,13 @@ v20.11.1
|
|
|
30
33
|
- [API](#api)
|
|
31
34
|
- [createConnection](#createSiteConnection)
|
|
32
35
|
- [Actions](#actions)
|
|
36
|
+
- [Authentication](#authentication)
|
|
37
|
+
- [Contacts](#contacts)
|
|
38
|
+
- [Distributions](#distributions)
|
|
39
|
+
- [Responses](#responses)
|
|
40
|
+
- [Mailing Lists](#mailing-lists)
|
|
41
|
+
- [Messages](#messages)
|
|
42
|
+
- [Utilities](#utilities)
|
|
33
43
|
- [Responses](#responses)
|
|
34
44
|
- [Contributing](#contributing)
|
|
35
45
|
- [Versioning](#versioning)
|
|
@@ -79,12 +89,12 @@ const connectionOptions = {
|
|
|
79
89
|
timeout: 20 * 1000, // optional timeout in milliseconds, default is 30 seconds
|
|
80
90
|
}
|
|
81
91
|
|
|
82
|
-
const connection:
|
|
92
|
+
const connection: Connection = createConnection(connectionOptions)
|
|
83
93
|
|
|
84
94
|
async function getBearerToken(clientId: string, clientSecret: string) {
|
|
85
|
-
const
|
|
86
|
-
if (
|
|
87
|
-
else throw new Error(
|
|
95
|
+
const result = await connection.getBearerToken({ clientId, clientSecret })
|
|
96
|
+
if (result.success) return result.data
|
|
97
|
+
else throw new Error(result.error)
|
|
88
98
|
}
|
|
89
99
|
```
|
|
90
100
|
|
|
@@ -95,20 +105,34 @@ Additionally, for single use or reduced import size, action factory methods can
|
|
|
95
105
|
```ts
|
|
96
106
|
import { testConnection } from '@b-jones-rfd/qualtrics-api-tasks'
|
|
97
107
|
|
|
98
|
-
async function testMyQualtricsConnection(
|
|
99
|
-
const action = testConnection(
|
|
100
|
-
const
|
|
101
|
-
if (
|
|
102
|
-
else throw new Error(
|
|
108
|
+
async function testMyQualtricsConnection() {
|
|
109
|
+
const action = testConnection(connectionOptions)
|
|
110
|
+
const result = await action()
|
|
111
|
+
if (result.success) return result.data
|
|
112
|
+
else throw new Error(result.error)
|
|
103
113
|
}
|
|
104
114
|
```
|
|
105
115
|
|
|
106
116
|
## API
|
|
107
117
|
|
|
108
|
-
###
|
|
118
|
+
### createConnection
|
|
119
|
+
|
|
120
|
+
Create a Qualtrics API Connection instance.
|
|
121
|
+
|
|
122
|
+
```ts
|
|
123
|
+
type ConnectionFactory = (options: ConnectionOptions) => Connection
|
|
124
|
+
```
|
|
109
125
|
|
|
110
126
|
#### ConnectionOptions
|
|
111
127
|
|
|
128
|
+
```ts
|
|
129
|
+
type ConnectionOptions = {
|
|
130
|
+
datacenterId: string
|
|
131
|
+
apiToken?: string
|
|
132
|
+
timeout?: number
|
|
133
|
+
}
|
|
134
|
+
```
|
|
135
|
+
|
|
112
136
|
`datacenterId`
|
|
113
137
|
|
|
114
138
|
| Type | Description | Example | Required |
|
|
@@ -139,7 +163,79 @@ export type Action<TConfig, TResponse> = (
|
|
|
139
163
|
|
|
140
164
|
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.
|
|
141
165
|
|
|
142
|
-
####
|
|
166
|
+
#### Authentication
|
|
167
|
+
|
|
168
|
+
##### getBearerToken(options)
|
|
169
|
+
|
|
170
|
+
Implements [OAuth Authentication (Client Credentials)](https://api.qualtrics.com/9398592961ced-o-auth-authentication-client-credentials) and returns the access token as the result data.
|
|
171
|
+
|
|
172
|
+
`options`
|
|
173
|
+
|
|
174
|
+
| Property | Type | Description | Required |
|
|
175
|
+
| ------------ | ------ | --------------------------------- | -------- |
|
|
176
|
+
| clientId | string | Quatrics Client ID | Y |
|
|
177
|
+
| clientSecret | string | Qualtrics Client Password | Y |
|
|
178
|
+
| scope | string | Qualtrics Client requested scopes | Y |
|
|
179
|
+
|
|
180
|
+
#### Contacts
|
|
181
|
+
|
|
182
|
+
##### getContactsImportStatus(options)
|
|
183
|
+
|
|
184
|
+
Implements [Get Contacts Import Status](https://api.qualtrics.com/c5d22705b1d45-get-transaction-contacts-import-status)
|
|
185
|
+
|
|
186
|
+
`options`
|
|
187
|
+
|
|
188
|
+
| Property | Type | Description | Required |
|
|
189
|
+
| ------------- | ------ | --------------------- | -------- |
|
|
190
|
+
| directoryId | string | Quatrics Directory ID | Y |
|
|
191
|
+
| importId | string | Contacts Import ID | Y |
|
|
192
|
+
| mailingListId | string | Mailing List ID | Y |
|
|
193
|
+
| bearerToken | string | Valid Bearer Token | N |
|
|
194
|
+
|
|
195
|
+
##### getContactsImportSummary(options)
|
|
196
|
+
|
|
197
|
+
Implements [Get Contacts Import Summary](https://api.qualtrics.com/6f0480b307053-get-transaction-contacts-import-summary)
|
|
198
|
+
|
|
199
|
+
`options`
|
|
200
|
+
|
|
201
|
+
| Property | Type | Description | Required |
|
|
202
|
+
| ------------- | ------ | --------------------- | -------- |
|
|
203
|
+
| directoryId | string | Quatrics Directory ID | Y |
|
|
204
|
+
| importId | string | Contacts Import ID | Y |
|
|
205
|
+
| mailingListId | string | Mailing List ID | Y |
|
|
206
|
+
| bearerToken | string | Valid Bearer Token | N |
|
|
207
|
+
|
|
208
|
+
##### importContacts(options)
|
|
209
|
+
|
|
210
|
+
Implements [Contact Import](https://api.qualtrics.com/1ac99fba8ca5b-contact-imports) multistep process
|
|
211
|
+
|
|
212
|
+
`options`
|
|
213
|
+
|
|
214
|
+
| Property | Type | Description | Required |
|
|
215
|
+
| --------------- | --------- | --------------------- | -------- |
|
|
216
|
+
| directoryId | string | Quatrics Directory ID | Y |
|
|
217
|
+
| mailingListId | string | Mailing List ID | Y |
|
|
218
|
+
| contacts | Contact[] | Contacts array | Y |
|
|
219
|
+
| transactionMeta | object | Transaction meta data | N |
|
|
220
|
+
| bearerToken | string | Valid Bearer Token | N |
|
|
221
|
+
|
|
222
|
+
##### startContactsImport(options)
|
|
223
|
+
|
|
224
|
+
Implements [Create Transaction Contacts Import](https://api.qualtrics.com/bab13356ac724-create-transaction-contacts-import)
|
|
225
|
+
|
|
226
|
+
`options`
|
|
227
|
+
|
|
228
|
+
| Property | Type | Description | Required |
|
|
229
|
+
| --------------- | --------- | --------------------- | -------- |
|
|
230
|
+
| directoryId | string | Quatrics Directory ID | Y |
|
|
231
|
+
| mailingListId | string | Mailing List ID | Y |
|
|
232
|
+
| contacts | Contact[] | Contacts array | Y |
|
|
233
|
+
| transactionMeta | object | Transaction meta data | N |
|
|
234
|
+
| bearerToken | string | Valid Bearer Token | N |
|
|
235
|
+
|
|
236
|
+
#### Distributions
|
|
237
|
+
|
|
238
|
+
##### createDistribution(options)
|
|
143
239
|
|
|
144
240
|
Implements [Create Distribution](https://api.qualtrics.com/573e3f0a94888-create-distribution).
|
|
145
241
|
|
|
@@ -164,40 +260,58 @@ Implements [Create Distribution](https://api.qualtrics.com/573e3f0a94888-create-
|
|
|
164
260
|
| sendDate | Date | Date time to send | Y | |
|
|
165
261
|
| bearerToken | string | Valid Bearer Token | N | |
|
|
166
262
|
|
|
167
|
-
|
|
263
|
+
##### createReminder(options)
|
|
168
264
|
|
|
169
|
-
Implements [Create
|
|
265
|
+
Implements [Create Reminder Distribution](https://api.qualtrics.com/764630bb0633a-create-reminder-distribution).
|
|
170
266
|
|
|
171
267
|
`options`
|
|
172
268
|
|
|
173
|
-
| Property
|
|
174
|
-
|
|
|
175
|
-
|
|
|
176
|
-
|
|
|
177
|
-
|
|
|
178
|
-
|
|
|
179
|
-
|
|
|
269
|
+
| Property | Type | Description | Required |
|
|
270
|
+
| -------------- | ---------------------- | ------------------------ | -------- |
|
|
271
|
+
| distributionId | string | Previous Distribution ID | Y |
|
|
272
|
+
| libraryId | string | Quatrics Library ID | Y |
|
|
273
|
+
| fromEmail | string | Originating email | Y |
|
|
274
|
+
| messageId | string | Qualtrics Message ID | Y |
|
|
275
|
+
| replyToEmail | string | Email reply-to address | N |
|
|
276
|
+
| fromName | string | Email from name | Y |
|
|
277
|
+
| subject | string | Email subject | Y |
|
|
278
|
+
| embeddedData | Record<string, string> | Up to 10 subkeys | N |
|
|
279
|
+
| sendDate | Date | Date time to send | Y |
|
|
280
|
+
| bearerToken | string | Valid Bearer Token | N |
|
|
281
|
+
|
|
282
|
+
##### getDistribution(options)
|
|
283
|
+
|
|
284
|
+
Implements [Get Distribution](https://api.qualtrics.com/f5b1d8775d803-get-distribution)
|
|
180
285
|
|
|
181
|
-
|
|
286
|
+
`options`
|
|
182
287
|
|
|
183
|
-
|
|
288
|
+
| Property | Type | Description | Required |
|
|
289
|
+
| -------------- | ------ | ------------------ | -------- |
|
|
290
|
+
| distributionId | string | Distribution ID | Y |
|
|
291
|
+
| surveyId | string | Survey ID | Y |
|
|
292
|
+
| bearerToken | string | Valid Bearer Token | N |
|
|
293
|
+
|
|
294
|
+
##### listDistributions(options)
|
|
295
|
+
|
|
296
|
+
Implements [List Distributions](https://api.qualtrics.com/234bb6b16cf6d-list-distributions)
|
|
184
297
|
|
|
185
298
|
`options`
|
|
186
299
|
|
|
187
|
-
| Property
|
|
188
|
-
|
|
|
189
|
-
|
|
|
190
|
-
|
|
|
191
|
-
|
|
|
192
|
-
|
|
|
193
|
-
|
|
|
194
|
-
|
|
|
195
|
-
|
|
|
196
|
-
|
|
|
197
|
-
|
|
|
198
|
-
|
|
199
|
-
|
|
200
|
-
|
|
300
|
+
| Property | Type | Description | Required | Default |
|
|
301
|
+
| ----------------------- | ------- | ------------------------------- | -------- | ------- |
|
|
302
|
+
| surveyId | string | Quatrics Survey ID | Y | |
|
|
303
|
+
| distributionRequestType | string | Distribution Request Type | Y | |
|
|
304
|
+
| mailingListId | string | Mailing List ID | Y | |
|
|
305
|
+
| sendStartDate | Date | Export start date and time | Y | |
|
|
306
|
+
| sendEndDate | Date | Export end date and time | Y | |
|
|
307
|
+
| skipToken | string | Pagination offset | N | |
|
|
308
|
+
| useNewPaginationScheme | boolean | Use updated pagination | N | false |
|
|
309
|
+
| pageSize | number | Distribution elements to return | N | 100 |
|
|
310
|
+
| bearerToken | string | Valid Bearer Token | N | |
|
|
311
|
+
|
|
312
|
+
#### Responses
|
|
313
|
+
|
|
314
|
+
##### exportResponses(options)
|
|
201
315
|
|
|
202
316
|
Implements [Survey Response File Export](https://api.qualtrics.com/u9e5lh4172v0v-survey-response-export-guide) multistep process.
|
|
203
317
|
|
|
@@ -230,57 +344,7 @@ Implements [Survey Response File Export](https://api.qualtrics.com/u9e5lh4172v0v
|
|
|
230
344
|
| sortByLastModifiedDate | boolean | Sort responses by modified date | N | false |
|
|
231
345
|
| bearerToken | string | Valid Bearer Token | N | |
|
|
232
346
|
|
|
233
|
-
|
|
234
|
-
|
|
235
|
-
Implements [OAuth Authentication (Client Credentials)](https://api.qualtrics.com/9398592961ced-o-auth-authentication-client-credentials)
|
|
236
|
-
|
|
237
|
-
`options`
|
|
238
|
-
|
|
239
|
-
| Property | Type | Description | Required |
|
|
240
|
-
| ------------ | ------ | --------------------------------- | -------- |
|
|
241
|
-
| clientId | string | Quatrics Client ID | Y |
|
|
242
|
-
| clientSecret | string | Qualtrics Client Password | Y |
|
|
243
|
-
| scope | string | Qualtrics Client requested scopes | Y |
|
|
244
|
-
|
|
245
|
-
#### getContactsImportStatus(options)
|
|
246
|
-
|
|
247
|
-
Implements [Get Contacts Import Status](https://api.qualtrics.com/c5d22705b1d45-get-transaction-contacts-import-status)
|
|
248
|
-
|
|
249
|
-
`options`
|
|
250
|
-
|
|
251
|
-
| Property | Type | Description | Required |
|
|
252
|
-
| ------------- | ------ | --------------------- | -------- |
|
|
253
|
-
| directoryId | string | Quatrics Directory ID | Y |
|
|
254
|
-
| importId | string | Contacts Import ID | Y |
|
|
255
|
-
| mailingListId | string | Mailing List ID | Y |
|
|
256
|
-
| bearerToken | string | Valid Bearer Token | N |
|
|
257
|
-
|
|
258
|
-
#### getContactsImportSummary(options)
|
|
259
|
-
|
|
260
|
-
Implements [Get Contacts Import Summary](https://api.qualtrics.com/6f0480b307053-get-transaction-contacts-import-summary)
|
|
261
|
-
|
|
262
|
-
`options`
|
|
263
|
-
|
|
264
|
-
| Property | Type | Description | Required |
|
|
265
|
-
| ------------- | ------ | --------------------- | -------- |
|
|
266
|
-
| directoryId | string | Quatrics Directory ID | Y |
|
|
267
|
-
| importId | string | Contacts Import ID | Y |
|
|
268
|
-
| mailingListId | string | Mailing List ID | Y |
|
|
269
|
-
| bearerToken | string | Valid Bearer Token | N |
|
|
270
|
-
|
|
271
|
-
#### getDistribution(options)
|
|
272
|
-
|
|
273
|
-
Implements [Get Distribution](https://api.qualtrics.com/f5b1d8775d803-get-distribution)
|
|
274
|
-
|
|
275
|
-
`options`
|
|
276
|
-
|
|
277
|
-
| Property | Type | Description | Required |
|
|
278
|
-
| -------------- | ------ | ------------------ | -------- |
|
|
279
|
-
| distributionId | string | Distribution ID | Y |
|
|
280
|
-
| surveyId | string | Survey ID | Y |
|
|
281
|
-
| bearerToken | string | Valid Bearer Token | N |
|
|
282
|
-
|
|
283
|
-
#### getResponseExportFile(options)
|
|
347
|
+
##### getResponseExportFile(options)
|
|
284
348
|
|
|
285
349
|
Implements [Get Response Export File](https://api.qualtrics.com/41296b6f2e828-get-response-export-file)
|
|
286
350
|
|
|
@@ -292,7 +356,7 @@ Implements [Get Response Export File](https://api.qualtrics.com/41296b6f2e828-ge
|
|
|
292
356
|
| fileId | string | File ID | Y |
|
|
293
357
|
| bearerToken | string | Valid Bearer Token | N |
|
|
294
358
|
|
|
295
|
-
|
|
359
|
+
##### getResponseExportProgress(options)
|
|
296
360
|
|
|
297
361
|
Implements [Get Response Export Progress](https://api.qualtrics.com/37e6a66f74ab4-get-response-export-progress)
|
|
298
362
|
|
|
@@ -304,39 +368,25 @@ Implements [Get Response Export Progress](https://api.qualtrics.com/37e6a66f74ab
|
|
|
304
368
|
| exportProgressId | string | Progress ID | Y |
|
|
305
369
|
| bearerToken | string | Valid Bearer Token | N |
|
|
306
370
|
|
|
307
|
-
####
|
|
308
|
-
|
|
309
|
-
Implements [Contact Import](https://api.qualtrics.com/1ac99fba8ca5b-contact-imports) multistep process
|
|
371
|
+
#### Mailing Lists
|
|
310
372
|
|
|
311
|
-
|
|
312
|
-
|
|
313
|
-
| Property | Type | Description | Required |
|
|
314
|
-
| --------------- | --------- | --------------------- | -------- |
|
|
315
|
-
| directoryId | string | Quatrics Directory ID | Y |
|
|
316
|
-
| mailingListId | string | Mailing List ID | Y |
|
|
317
|
-
| contacts | Contact[] | Contacts array | Y |
|
|
318
|
-
| transactionMeta | object | Transaction meta data | N |
|
|
319
|
-
| bearerToken | string | Valid Bearer Token | N |
|
|
373
|
+
##### createMailingList(options)
|
|
320
374
|
|
|
321
|
-
|
|
322
|
-
|
|
323
|
-
Implements [List Distributions](https://api.qualtrics.com/234bb6b16cf6d-list-distributions)
|
|
375
|
+
Implements [Create Mailing List](https://api.qualtrics.com/3f633e4cea6cd-create-mailing-list)
|
|
324
376
|
|
|
325
377
|
`options`
|
|
326
378
|
|
|
327
|
-
| Property
|
|
328
|
-
|
|
|
329
|
-
|
|
|
330
|
-
|
|
|
331
|
-
|
|
|
332
|
-
|
|
|
333
|
-
|
|
|
334
|
-
| skipToken | string | Pagination offset | N | |
|
|
335
|
-
| useNewPaginationScheme | boolean | Use updated pagination | N | false |
|
|
336
|
-
| pageSize | number | Distribution elements to return | N | 100 |
|
|
337
|
-
| bearerToken | string | Valid Bearer Token | N | |
|
|
379
|
+
| Property | Type | Description | Required | Default |
|
|
380
|
+
| ---------------------- | ------- | -------------------------------- | -------- | ------- |
|
|
381
|
+
| directoryId | string | Quatrics Directory ID | Y | |
|
|
382
|
+
| name | string | Mailing List Name | Y | |
|
|
383
|
+
| ownerId | string | Owner ID | Y | |
|
|
384
|
+
| prioritizeListMetadata | boolean | Import metadata as list metadata | N | false |
|
|
385
|
+
| bearerToken | string | Valid Bearer Token | N | |
|
|
338
386
|
|
|
339
|
-
####
|
|
387
|
+
#### Messages
|
|
388
|
+
|
|
389
|
+
##### listLibraryMessages(options)
|
|
340
390
|
|
|
341
391
|
Implements [List Library Messages](https://api.qualtrics.com/1d60a66b340fa-list-library-messages)
|
|
342
392
|
|
|
@@ -349,21 +399,7 @@ Implements [List Library Messages](https://api.qualtrics.com/1d60a66b340fa-list-
|
|
|
349
399
|
| offset | number | Pagination offset | N |
|
|
350
400
|
| bearerToken | string | Valid Bearer Token | N |
|
|
351
401
|
|
|
352
|
-
|
|
353
|
-
|
|
354
|
-
Implements [Create Transaction Contacts Import](https://api.qualtrics.com/bab13356ac724-create-transaction-contacts-import)
|
|
355
|
-
|
|
356
|
-
`options`
|
|
357
|
-
|
|
358
|
-
| Property | Type | Description | Required |
|
|
359
|
-
| --------------- | --------- | --------------------- | -------- |
|
|
360
|
-
| directoryId | string | Quatrics Directory ID | Y |
|
|
361
|
-
| mailingListId | string | Mailing List ID | Y |
|
|
362
|
-
| contacts | Contact[] | Contacts array | Y |
|
|
363
|
-
| transactionMeta | object | Transaction meta data | N |
|
|
364
|
-
| bearerToken | string | Valid Bearer Token | N |
|
|
365
|
-
|
|
366
|
-
#### startResponseExports(options)
|
|
402
|
+
##### startResponseExports(options)
|
|
367
403
|
|
|
368
404
|
Implements [Start Response Exports](https://api.qualtrics.com/6b00592b9c013-start-response-export)
|
|
369
405
|
|
|
@@ -396,7 +432,9 @@ Implements [Start Response Exports](https://api.qualtrics.com/6b00592b9c013-star
|
|
|
396
432
|
| sortByLastModifiedDate | boolean | Sort responses by modified date | N | false |
|
|
397
433
|
| bearerToken | string | Valid Bearer Token | N | |
|
|
398
434
|
|
|
399
|
-
####
|
|
435
|
+
#### Utilities
|
|
436
|
+
|
|
437
|
+
##### testConnection(bearerToken)
|
|
400
438
|
|
|
401
439
|
| Parameter | Type | Description | Required |
|
|
402
440
|
| ----------- | ------ | ------------------ | -------- |
|