# CHANGES TO MTurkR 0.4 #

## SIGNIFICANT USER-VISIBLE CHANGES ##
* Functions that accept a `hit.type` argument can now generally accept a vector of HITTypeIds rather than just a single character string. See documentation.
* `GetBonuses` now allows requests to be opened in the default browser, like most other API functions.
* From version 0.3.7, global options (`MTurkR.log`,`MTurkR.test`,`MTurkR.browser`,and `MTurkR.print`) have been added to all functions. Defaults for these remain the same in all places.
* From version 0.3.65, `SearchHITs` returns a named list of QualificationRequirements. This is a consequence of some significant changes to now the names of user-defined QualificationTypes are added to this list (moving that functionality from `QualificationRequirementsToDataFrame` to `SearchHITs`.
* From version 0.3.6, a global option `options('MTurkR.sandbox'=FALSE)` has been added to allow easier reuse of code between testing in the sandbox and the live server. The default behavior remains to use the live server, but using an option, which is called by all functions, allows one to toggle the global option and then recycle code verbatim.
* Per API changes on April 8, 2013, several built-in QualificationTypes were removed. See `ListQualificationTypes` for the available types.
* Improved error, warning, and message handling by converting calls to `cat` to `warning` and `message`, where appropriate.
* Most API query functions now include a `validation.test` parameter that, when TRUE, runs pre-query checks on the MTurkR call and returns the full API query URL. The call is not executed. This can be used for pre- or post-request debugging.
* The 'MTurkRlog.tsv' file is now located according to a global option, specified by `options(MTurkR.logdir = getwd())`. The previous default behavior (to store the file in the working directory) is preserved but can now be globally modified for all requests. This might be useful for storing all requests (from all MTurk projects) in a single directory.

## BUG FIXES ##
* `ContactWorkers` now supplies additional information when attempting to contact ineligible workers (i.e., those who have not worked for the requester previously). These workers are indicated by a value of `HardFailure` in the `Valid` column of the response data.frame. (#29)
* All functions now explicitly convert factor arguments (e.g., for `worker`, `qual`, `hit`, etc.) to character in order to prevent some unintended side effects. (#26)
* New versions of libcurl (>7.28) deprecate boolean values for SSL_VERIFYPEER and SSL_VERIFYHOST options. `request` was returning errors due to this and has been updated. Everything is backwards compatible to earlier versions of libcurl. (#31, h/t James Ben Taylor)
* `GenerateHITLayoutParameter` now replaces any non-XML ampersands with `&amp;`, which had previously caused failures when creating HITs. (#30, h/t Eric Lin)
* In `GetAssignment`, made a small change to prevent a warning and coercion of a one-assignment vector to a list. (h/t Eric Lin)
* Two HITReviewPolicy names weres changed per a discussion on the AWS developer forum. Details here: https://forums.aws.amazon.com/thread.jspa?threadID=135285.
* In `HITStatus` and `HITsToDataFrame` the correct capitalization of "Of" (from lower to upper) has been corrected throughout.
* A series of related changes were made to `GetAssignment`, `AssignmentsToDataFrame` and `QuestionFormAnswersToDataFrame` to handle Answer data structures with differing QuestionIdentifiers. (h/t Robert Vesco and Solomon Messing)
* Eliminated several `response.group` options from `GetHITsForQualificationType` due to personal communication with AWS.
* Fixed bug in `GetReviewableHITs` that correctly queried the API but returned an incomplete dataframe. (h/t Eric Lin)
* Fixed bug in `CreateHIT`, saying `type` was not defined, that occurred when `hit.type` was non-NULL. (h/t Eric Lin)
* Fixed bug in `GetHIT`, which trickled down through `HITsToDataFrame` and `QualificationRequirementsToDataFrame` that caused error when retrieving HITs from the sandbox with user-defined qualifications. (h/t Eric Lin)
* Fixed bug in `GenerateHTMLQuestion` related to XML encoding. (h/t Alex Neustädter)
* In `request` and several convenience functions, corrected `shell.exec` to `browseURL` to be platform-independent.
* Added filters to `request` to handle a variety of problematic characters (that might emerge from FreeText responses in assignments). (h/t and contributions from Solomon Messing)
* removed references to `shell.exec` and replaced with `browseURL`.

## DOCUMENTATION ##
* Where appropriate, functions using `hit.type` parameters are now described (correctly) as allowing vectors of HITTypeIds rather than just a single HITTypeId. See documentation.
* Documentation for `ContactWorkers` now describes in greater detail what happens when attempting to contact ineligible workers. (#29)

# CHANGES TO MTurkR 0.3.5 #

## SIGNIFICANT USER-VISIBLE CHANGES ##
* `CreateHIT` now provides an option to validate the 'question' parameter for HTMLQuestion, ExternalQuestion, and QuestionForm HIT structures.
* `CreateQualificationType` now provides options to validate the 'test' and/or 'answerkey' parameters for QuestionForm and AnswerKey structures, respectively.
* `GenerateAnswerKey` was modified to accept slightly different inputs for the 'questions' parameter. A new function, `AnswerKeyTemplate`, produces a user-modifiable template (as a list) for that parameter based on a QuestionForm data structure for which an AnswerKey is desired.
* When internal functions (described in the documentation of `XMLToDataFrame`) that normally return named lists have nothing to translate to a dataframe, they now return named lists with NULL values rather than simply a single NULL.

## BUG FIXES ##
* Fixed bug in `GetAssignments` that prevented the return of assignments for an entire HITType or for multiple HITs. Specifically, previous version was retrieving assignments via the API but not returning them to the user. (h/t Robert Vesco)


# CHANGES TO MTurkR 0.3 #

## SIGNIFICANT USER-VISIBLE CHANGES ##
* To improve speed and reduce the number of API calls, `HITsToDataFrame`, which is called by `SearchHITs`, `GetHIT`, etc., now uses the convenience function `ListQualificationTypes` to return the name of QualificationRequirements when applicable.
* Expanded the functionality of `ContactWorkers` to allow a 'batch' mode, wherein workers are contacted with generic (i.e., not customized) email messages and subject lines in batches of 100.
* Text sent to console when `print=TRUE` modified slightly, so that iteration numbers are printed for each iteration (to monitor progress of mutli-item requests).
* ResponseGroups updated to current API specifications for `CreateHIT`, `GetAssignments`, `GetHIT`, `GetStatistic`, `GetWorkerStatistic`, and `SearchHITs`. These now include an optional "Request" ResponseGroup to simply return information about the API call without executing that call.
* `AssignmentsToDataFrame` now returns a "RequesterFeedback" variable, providing access to feedback supplied to workers when `GetAssignments` is called with the "AssignmentFeedback" ResponseGroup.
* Updates were made to `GenerateAnswerKey` (see documentation) and a new function `AnswerKeyToDataFrame` was released.
* `QuestionFormToDataFrame` created. See documentation for details.

## BUG FIXES ##
* MTurk API operation 'ChangeHITTypeofHIT' typo was fixed to 'ChangeHITTypeOfHIT'.
* A small change was made to `BlockWorkers` to allow a single reason to be used for multiple workers, as originally intended.
* Fixed bug in `GetAssignments` to allow retrieval of assignments by status, as originally intended.
* Fixed bug in `AssignmentsToDataFrame` to correctly store 'ApprovalTime' or 'RejectionTime' in 'ApprovalRejectionTime'
* Bug fixes to `CreateQualificationType` related to parsing of XML in 'test' and 'answerkey' parameters.
* Modified `credentials` to pass CRAN checks.

## DOCUMENTATION ##
* Documentation for `CreateQualificationType` notes web browser-dependent constraints on URL length that may produce unintended behavior when 'browser=TRUE' and a 'test' parameter is specified.
* Added documentation for `AnswerKeyToDataFrame`.
* Various copyedits.



# CHANGES TO MTurkR 0.2 #

## SIGNIFICANT USER-VISIBLE CHANGES ##
* A completely new GUI interface for managing MTurkR, which now suggests library(tcltk), has been added. The previous, text-based wizard remains available by calling `mturkr.wizard("simple")`.
* Support for ReviewPolicies has been added, both creating them using `GenerateReviewPolicy` and retrieving their results using `GetReviewResultsForHIT`.
* Support for AnswerKey data structures has been added, for use in `CreateQualificationType`.
* Added simple checks for 'sortproperty', 'sortdirection', 'pagesize', and 'pagenumber' parameters in relevant functions.
* Expanded support for QuestionForm data structures is currently under development and should be available in the next release.

## BUG FIXES ##
* A number of bug fixes have been corrected throughout the package. Most were minor and related to output, but some like the 'return.all' parameter in `GetAssignments`, were producing unintended behavior.
* Various mislabelled function parameters (used within functions) have been corrected (some were creating notes on R CMD check).
* `request` was modified to remove problematic whitespace characters when writing log entries (which made reading the log file into R problematic).

## DOCUMENTATION ##
* Fixed a number of minor errors in documentation.
* Expanded documentation for functions associated with AnswerKey and ReviewPolicy data structures.
* Expanded documentation for 'sortproperty' and 'sortdirection' parameters in relevant functions.
