Initial survey options functions (draft)

[jmobrien]

Examples of two new functions, update_survey_metadata() and fetch_survey_metadata() that illustrate extending functionality simply by setting up 1 or more types of calls to a new endpoint.

In this case we have the survey-definitions/metadata endpoint, which allows us to get a survey's options (w/o having to download the whole survey contents). With a "PUT" (verb added to the querying function) it also allows us to (de)activate a survey both immediately and at designated times, as well as to set survey names & survey descriptions.

[jmobrien]

Update on this - This is pretty much done, now covering everything in the Update Metadata endpoint. Also stuck in the additional documentation for fetch_survey() to close #265.

It still needs tests, which I HAVE done, but haven't pushed here. The problem is that they don't work--and it's Qualtrics's fault.

Turns out this endpoint isn't actually checking for the requested ISO 8601 formatting for the start & expiration date parameters. Even their own example code on their documentation page doesn't work. (they're looking for a space instead of a "T", and reject the "Z" or time zone info like the fetch_survey() endpoint can).

I reached out to them about this, so hopefully they get it fixed up soonish and this can proceed.

[jmobrien]

Hearing that a fix to the endpoint is in progress now, though no details beyond that.

[jmobrien]

The support ticket lists a resolution timeline in the 6mo-1yr range. Seems high for this but I don't know all the details.

Anyway, if taking that timeline at face value, I think I'm just going to move ahead with this? Basically just add a workaround module that adjusts dates/times to match current implementation. I'll mark it so that we know what to strip out when the endpoint gets fixed.

Any issues I'm not seeing with that approach?

[juliasilge]

I think if you include a fair amount of clear comments (or lay out the situation in an issue that we can come back to and understand, or both), that sounds like the right approach. 👍

[jmobrien]

It's nothing too esoteric. The current implementation varies from the ISO standard in 2 ways:

1. There's no "T" separating days & time
2. There's no time zone marker at the end (either a Z for UTC or an hour/minute adjustment)

That means we can't just use the package tools for date formatting, and also that the endpoint apparently requires UTC time (implicitly, though we should check). For a workaround I think we could do the following.

1. Use the package tools for generating the ISO string standard (which incorporate time zone adjustments, etc.)
2. Back-convert to normal POSIX
3. Adjust time to UTC (lubridate::with_tz())
4. Convert to string, dropping the UTC suffix

Step 1 is already in place because that's how it should work. We add 2-4 then remove them later. I'll include those comments in the code as well so it's clear.

[juliasilge]

I just moved this repo's default branch from master to main; you can use usethis::git_default_branch_rediscover() to update your local setup.

[jmobrien]

Okay, so it looks like the issue with date times may have been that they had set up the endpoint to use the mySQL DATETIME instead of the ISO 8601 otherwise used throughout. And they fixed (air quotes) it by just adding a label noting the difference:

https://api.qualtrics.com/ae7f40bbcb91a-update-metadata

Not ideal of course, but there are probably some internal considerations I'm not seeing. To their credit, they did also add explicit alternative regex for validation: ^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$.

I've not yet found any R functions/packages that explicitly handle mySQL DATETIME representation. But since this is seemingly permanent I'll just extend the functions for date-time argument checking to have a mySQL option.

[jmobrien]

Okay, with the new API docs (and also incorporating som nice updates to lubridate), I got this this "working" in theory. But maybe someone can look at it for me? Something doesn't seem right.

I'm able to activate/deactivate surveys, as well as set activation/expiration dates. After issuing a request, both show up in the metadata. But the set times don't seem to do anything--e.g., an inactive survey doesn't seem to activate at its specified start time. Am I missing something about how this should work on Qualtrics's end?

[juliasilge]

I just gave a go at using this, and active = TRUE / FALSE works for me to change a survey's status but I can't seem to get the date-based approach to work. Sounds like that is the same thing that you experienced @jmobrien?