changeiq-cli v0.3.0

> changeiq

A command line tool for an automatic change of the q. c. state of multiple interviews in a specific survey.

Nfield domain, username and password arguments are required, as well as the survey id and the path to tsv file with two columns: INTNR and New State.

Install with npm:

npm install changeiq-cli --global

Usage:

changeiq -d <domain> -u <username> -p <password> -f <path> -s <survey id> [-a <list>] [-r <list>] [-U <list>] [-C <list>] [-c] [-m [count]] [-t <ms>]

Options:

-h, --help                        output usage information
-V, --version                     output the version number
-d, --nfield-domain <domain>      nfield domain
-u, --nfield-username <username>  nfield username
-p, --nfield-password <password>  nfield password
-f, --path-to-file <path>         path to tsv file with two colums: INTNR and new state code
-s, --survey-id <survey id>       nfield Survey ID
-m, --max-requests [count]        serializes requests to API to groups of [count], defaults to 10 if argument provided with no value
-t, --timeout <ms>                sets a timeout between API request 'blocks' made with --max-requests
-c, --change-unmapped             change state for unmapped codes to 'not checked'
-C, --not-checked <list>          comma-separated list of custom mappings for the 'not checked' state
-a, --approved <list>             comma-separated list of custom mappings for the 'approved' state
-U, --unverified <list>           comma-separated list of custom mappings for the 'unverified' state
-r, --rejected <list>             comma-separated list of custom mappings for the 'rejected' state

Example:

First we need to create a valid file with an interviews list to pass to the CLI. Let's name it interviews.txt and fill it with some data:

65	3
86	3
98	1
123	1

The first column is the INTNR; the second is the new state code (default codes are used for this example); columns are tab separated; empty or NaN cells are ignored by the CLI.

Then we run the changeiq command replacing -d, -u,, -p, -f, -s values with valid data:

changeiq -d DMN -u Username -p p455w0rD -f interviews.txt -s real-survey-id

If all goes well, something like this will appear in your terminal:

  starting to process 4 interviews...

  1 of 4 changed status of interview 00000123 to approved
  2 of 4 changed status of interview 00000098 to approved
  3 of 4 changed status of interview 00000086 to rejected
  4 of 4 changed status of interview 00000065 to rejected

  finished in 0.9s

Changing state code mapping:

By default changeiq looks for this standart Nfield codes (or their labels) in the provided tsv file to send 'state change' request to Nfield API. This codes are as follows:

So if provided file looks something like this:

1	SUCCESS
6	FAIL
7	true
8	false
9	-1
10	10

You will get just a bunch of errors, trying to pass it to the changeiq as is:

  1 of 6 ERR skipping interview 00000001: state code SUCCESS is mapped to undefined
  2 of 6 ERR skipping interview 00000006: state code FAIL is mapped to undefined
  3 of 6 ERR skipping interview 00000007: state code true is mapped to undefined
  4 of 6 ERR skipping interview 00000008: state code false is mapped to undefined
  5 of 6 ERR skipping interview 00000009: state code -1 is mapped to undefined
  6 of 6 ERR skipping interview 00000010: state code 10 is mapped to undefined

This could be changed with the following arguments:

-C, --not-checked <list>          comma-separated list of custom mappings for the 'not checked' state
-a, --approved <list>             comma-separated list of custom mappings for the 'approved' state
-U, --unverified <list>           comma-separated list of custom mappings for the 'unverified' state
-r, --rejected <list>             comma-separated list of custom mappings for the 'rejected' state

They accept a list of comma-separated values (or just one value) that is parsed to an array of unique case-sensitive values that will be used to map state codes to the 'state change' request. So for this bizzare example of a file that is provided above, you could run changeiq like this:

changeiq -d DMN -u Username -p p455w0rD -f interviews.txt -s real-survey-id -a SUCCESS,true,10 -r FAIL,false -U -1

and change states of all this interviews with no errors

  1 of 6 changed state of interview 00000008 to rejected
  2 of 6 changed state of interview 00000001 to approved
  3 of 6 changed state of interview 00000010 to approved
  4 of 6 changed state of interview 00000006 to rejected
  5 of 6 changed state of interview 00000009 to unverified
  6 of 6 changed state of interview 00000007 to approved

Changing unmapped codes:

By defaults all interviews from the provided tsv file with codes that does not correspond to default state codes or custom codes (if they are passed to the arguments) will be skipped by the CLI and log an error message:

  starting to process 11 interviews...

  1 of 11 ERR skipping interview 00000004: state code 4 is mapped to undefined
  2 of 11 ERR skipping interview 00000005: state code 5 is mapped to undefined
  

But because Nfield API allows to pass any value to the NewState parameter of the 'state change' request and interprets it as 'not checked' state, you can allow this behaviour with --change-unmapped flag. With this flag all interviews with unmapped state codes will be changed to 'not checked' state. In the logs you will see something like this:

  11 of 11 WARN state code 123 is mapped to undefined
  11 of 11 changed state of interview 00000065 to not checked
  

Limiting maximum request rate:

By default changeiq collects all 'state update' requests to an array and calls them with Promise.all, waiting for all of them to finish async at once, but sometimes it is not possible: for example when you need to handle a lot of data and your proxy limit request rate to some count in time. You can serialize all requests with --max-requests [--timeout <ms>] like this:

changeiq -d DMN -u Username -p p455w0rD -f interviews.txt -s real-survey-id -m 1000 -t 60000

This will limit request rate of the CLI to 1000 requests in one minute (60000ms).

For example, here I run CLI, limiting requests to 1 in 30 seconds:

changeiq -d DMN -u Username -p p455w0rD -f interviews.txt -s real-survey-id -m 1 -t 30000

and get an expected result of 152 seconds, taking in the account that first serialized request fires immidiately and ~2 secs goes to network delays

  starting to process 6 interviews...

  1 of 6 changed state of interview 00000001 to rejected
  2 of 6 changed state of interview 00000006 to rejected
  3 of 6 changed state of interview 00000007 to approved
  4 of 6 changed state of interview 00000008 to rejected
  5 of 6 changed state of interview 00000009 to rejected
  6 of 6 changed state of interview 00000010 to approved

  finished in 152.86s