LegionTools

LegionTools provides an easy way to recruit and route workers from Amazon Mechanical Turk to synchronous real-time tasks.

LegionTools provides three key features for requesters:

Automatically optimized HIT posting - LegionTools makes it easy to automatically post HITs to AMT. To ensure your HITs are seen by workers, LegionTools automatically posts, expires, and re-posts your HITs periodically to keep them showing on the first page of MTurk. Additionally, you can easily change HIT title, price, and other values on the fly (changes are reflected in all subsequently posted HITs).
Worker staging - LegionTools allows you to stage workers in a retainer pool prior to forwarding them to a task. This lets you easily ensure that a specific number of workers all begin your task at the same time. LegionTools lets you select the number of workers you need, then send them all to a single URL with the push of a button.
Completed-HIT management - LegionTools allows you to easily approve, reject, and dispose the HITs that workers have completed.

Getting Started

Installation

Clone LegionTools to a public web server with PHP 5.3 or higher.
Install PHP’s SOAP extension. If you’re running PHP on Mac OS X or Windows, the extension is likely already installed.
- For CentOS/RedHat: yum install php-soap
- For Debian/Ubuntu: apt-get install php-soap
  Warning: on Ubuntu, php-soap does not always install properly. You may have to also do the following:
  apt-get --purge remove php5*
  sudo apt-get install php5 php5-sqlite php5-mysql
  sudo apt-get install php-pear php-apc php5-curl
  sudo apt-get autoremove
Modify LegionTools/config.php to contain the public URL of your LegionTools installation.
Enter your Amazon Mechanical Turk keys when you see the login screen.
→ OR: add your keys to LegionTools/amtKeys.php, and add ?login=false to the URL to skip this process.
Ensure that LegionTools/db and its contents has permissions 777.
To allow workers to submit HITs, you can import LegionTools/mturk.js to your task page, and add a form element with id="mturk_form".
→ OR: add your own MTurk task-submit code.

Usage

Navigate to LegionTools/index.php in your browser (tested on Chrome) to pull up the control UI.

Recruiting workers

Add a new task by typing a unique session name, title, description, keywords, and clicking Add new task. Remember your session name, you can use it to restore your session later on.
Set the target number of workers to keep around. Set the price range and click "Update price".
Click Change waiting page instructions to edit the text that workers will be shown while worker waiting for you to send them to your task.
Click Start recruiting to beging recruiting. You must click Stop recruiting to end the recruiting process. Note that stopping recruitment will take some time, depending on your target number of workers.
To pull up a previous task, select its session name. If you closed the UI page and left the recruiting tool running, you may stop that recruiting process by loading the associated session and clicking Stop recruiting.
To modify a task's title, description, or keywords, change the content and click Update. Changes automatically affect all new HITs posted by the recruiting tool.
To send workers to a URL, click the Fire button. Your chosen URL must be HTTPS.
When you are ready to review completed HITs, click Load in the Overview section to load all reviewable HITs associated with a given task session.

Citations

Please cite the following work if your research used LegionTools: