Legacy Retainer README

This page is about the legacy retainer tool, a version of which is included in LegionTools. This page is included here for purposes of completeness, but is not guaranteed to be accurate.

Overview

The retainer tool can retain a pool of crowd-workers, and makes it easy to send many workers to a given task at a moment's notice. One instance of the tool can be used to handle multiple tasks.

Functionality

Adding workers to the pool.

1. The task-developer should send crowd workers to retainer/index.php?workerId=<workerId>&task=<task>.
2. Upon going to the index page, an entry for that worker will be added in the workers table using retainer/php/setLive.php.
3. The worker is then immediately forwarded to the waiting page, retainer/wait.php?workerId=<workerId>&task=<task>.
4. While on the waiting page, retainer/scripts/triggerCheck.js will be called, which in turn calls retainer/php/triggerCheck.php once per second. On triggerCheck's first call, if an open entry for the worker's task does not already exist, an entry for the task will be created and added to the triggerCheck table. An "open" entry for a task means that the task has an entry on the table, but the url column for that task is blank.
5. Subsequent workers who join the pool with that task will all use that same entry in triggerCheck.
6. While on the waiting page, retainer/scripts/setOnline.js will be also be called, which in turn calls retainer/php/ajax_whosonline.php once per second. See later in this readme for a description of this function.
7. Upon subsequent calls, when triggerCheck sees that a url has been provided for the worker's task, the worker will see an alert notifying them that they are about to be directed to the task page. The worker is then forwarded to http://<taskurl>?workerId=<workerId>, and their endTime in the workers table will be updated to the current time. If enough workers have already been fired when a worker clicks through their alert, the worker will see another alert notifying them that enough workers were already fired. The worker then remains on the waiting page and is ready for the next firing.
8. If a worker closes the waiting page before they are assigned a task, their endTime will not be updated.
9. The same worker is not allowed to be concurrently waiting for multiple tasks. If a worker goes to the index page and is already in the pool for a different task, a popup alert will occur and the worker will not be directed to the waiting page.

Triggering Workers (Firing)

1. Task developers can find the trigger at retainer/trigger.php?task=<task>.
2. The number of workers currently in the pool for that task is shown on the page. This is done via retainer/scripts.setOnline.js, which each second calls retainer/php/ajax_whosonline.php. Since setOnline is called from the trigger page, it will simply get the number of workers in the pool for the given task. Please note, there is a couple-second lag in this number updating. See later in the readme for a more detailed description of this function.
3. When the fire button is submitted, retainer/php/setFire.php and retainer/php/updateReleased.php are called.
4. setFire will then update the most recent entry in the triggerFlag database that has the corresponding task. fireTime for this entry will be updated to the current time, and link will be updated with the url entered in the trigger. updateReleased updates the released table with a new entry.
5. All workers in the pool that have the corresponding task will have been monitoring the task via retainer/scripts/triggerCheck.js. Once triggerCheck sees that a url has been provided for the task, it will check retainer/php/checkReleased.php. It will then either forward those workers to http://<taskurl>?workerId=<workerId> with <taskurl> being the url entered by the task-developer in the trigger, or it will keep the worker on the waiting page if enough workers were already fired. triggerCheck will also call retainer/scripts/updateEndTime.js, which in turn calls retainer/php/updateEndTime.php, which updates the worker's endTime to the current time.

Paying workers

In order to receive the amount of time a worker waited, run php/getTimeWaited.php?workerId="workerId". This will echo the amount of time a worker is waited in seconds, and it gets this value using the most recent entry for this workerID. This should only be done after the trigger is fired, since workers will not have an endTime assigned to them prior to being triggered.

To pay workers who are no longer needed, fire them to submitOnly.php. This page will contains a LegionJS submit button, and will pay workers the base HIT amount and the money they earned from waiting. To change rate that workers earn money from waiting, edit the the vars file at scripts/vars.js.

Whois online tool

This tool can be found at retainer/php/ajax_whosonline.php. When first called from a worker, it will create a new entry for that worker with its associated task. Each subsequent call will update the worker's time to the current time. If a worker's time is more than three or more seconds prior to the current time, it is no longer considered online. When the tool is not called from a worker, it will echo the current amount of workers online for a given task.

Waiting page instructions

The waiting page will display the contents of instructions.php. Modify instructions.php to contain your desired instructions.

mySQL

• Be sure to input your database credentials in getDB.php, located in the root LegionTools directory.

Required - the following four mySQL tables in a database called "retainer" must be present on the server.

• "triggerFlag"

describe triggerFlag;
+----------+-----------+------+-----+-------------------+-----------------------------+
| Field    | Type      | Null | Key | Default           | Extra                       |
+----------+-----------+------+-----+-------------------+-----------------------------+
| id       | int(11)   | NO   | PRI | NULL              | auto_increment              |
| task     | text      | YES  |     | NULL              |                             |
| link     | text      | YES  |     | NULL              |                             |
| fireTime | timestamp | NO   |     | CURRENT_TIMESTAMP | on update CURRENT_TIMESTAMP |
+----------+-----------+------+-----+-------------------+-----------------------------+

• "workers"

describe workers;
+-----------+-----------+------+-----+---------------------+----------------+
| Field     | Type      | Null | Key | Default             | Extra          |
+-----------+-----------+------+-----+---------------------+----------------+
| id        | int(11)   | NO   | PRI | NULL                | auto_increment |
| wid       | text      | YES  |     | NULL                |                |
| idx       | text      | YES  |     | NULL                |                |
| startTime | timestamp | NO   |     | CURRENT_TIMESTAMP   |                |
| endTime   | timestamp | NO   |     | 0000-00-00 00:00:00 |                |
+-----------+-----------+------+-----+---------------------+----------------+

• "whois_online"

describe whois_online;
+-------+------+------+-----+---------+-------+
| Field | Type | Null | Key | Default | Extra |
+-------+------+------+-----+---------+-------+
| id    | text | YES  |     | NULL    |       |
| task  | text | YES  |     | NULL    |       |
| time  | time | YES  |     | NULL    |       |
+-------+------+------+-----+---------+-------+

• "released"

describe released;
+-------+---------+------+-----+---------+----------------+
| Field | Type    | Null | Key | Default | Extra          |
+-------+---------+------+-----+---------+----------------+
| ID    | int(11) | NO   | PRI | NULL    | auto_increment |
| url   | text    | YES  |     | NULL    |                |
| max   | int(11) | YES  |     | NULL    |                |
| sent  | int(11) | YES  |     | NULL    |                |
+-------+---------+------+-----+---------+----------------+

mySQL table column descriptions:

workers:

• id - the nth worker to be added to the table (eg. the 3rd worker to be added to the table has an id of 3).
• wid - the worker id.
• idx - the nth time that the same worker (same wid) has been added to the table, starting at 0.
• startTime - timestamp of when the worker connected
• endTime - timestamp of when the worker proceeds to the task.

triggerFlag:

• id - the nth session to be added to the table
• task - the task assigned to the worker
• link - the url that workers for that task should be sent to. This field will start out empty, and when no link is present, a task is considered open.
• fireTime - This is updated to the current time when the task is fired.

whois_online:

• id - the workerId
• task - the task assigned to the worker
• time - the most recent time the worker was seen online (in the pool).

Example Workflow

1. Three workers go to retainer/index.php?workerId=<workerId>&task=task1.
2. The task-developer goes to retainer/trigger.php?task=task1. The page will show that there are 3 workers online.
3. The task-developer types in mytasksite.com as the task URL, and fired two workers towards it.
4. All three workers receive alert popups.
5. The first two workers to click through the alert are sent to mytasksite.com?workerId=<workerId>.
6. The trigger page now shows 1 online worker, because the third has remained in the pool.
7. Another worker goes to retainer/index.php?workerId=<workerId>, the trigger page now shows 2 online worker2.
8. The task developer enter the number 1, clicks fire again, and one worker is sent to mytasksite.com?workerId=<workerId>.
9. The task developer then decides that they are finished with the task. However, there is still one worker left waiting in the pool. To pay that worker, the task developer fires it to submitOnly.php.
10. If the task developer wishes to get the amount of time a worker waited, they may call retainer/php/getTimeWaited.php?workerId=<workerId> for each of the four workers.