Order Setup

Project setup - Step-by-step

As mentioned in the previous section we offer two different products through the API. The initial configuration of the product according to the customer’s needs is called the ‘Project setup’.

Herewith the customer specifies the following aspects of his project:

• which Product is ordered (TextCreate, TextCreateWithKeywords including client specific products)

  • language of the text
  • length of the text
  • quality assurance on/off
• input data
• output data

3.5 TextCreateWithKeywords

As shown in 3.1.2 one part of the Task-template is the product configuration. With ‘TextCreateWithKeyword’ we would choose a different product and the product configuration would need to be changed as follows:

<product>
<link href="/api/marketplace/v2/products/TextCreateWithKeywords" rel="product"
type="application/xml"/>
 <attributes>
   <code>textcreatewithkeywords_language</code>
   <value>[WANTED LANGUAGE]</value>
 </attributes>
 <attributes>
   <code>textcreatewithkeywords_text_length</code>
   <value>[WANTED TEXT LENGTH]</value>
 </attributes>
 <attributes>
   <code>textcreatewithkeywords_proof_read</code>
   <value>[textcreate_proof_yes | textcreate_proof_no]</value>
 </attributes>
 <attributes>
   <code>textcreatewithkeywords_sample</code>
   <value>[EXAMPLE TEXT]</value>
 </attributes>
 <attributes>
   <code>textcreatewithkeywords_description</code>
   <value>[DESCRIPTION]</value>
 </attributes>
 <attributes>
   <code> textcreatewithkeywords_team_whitelist</code>
   <value>[Team ID]</value>
 </attributes>
 <attributes>
   <code> textcreatewithkeywords_team_blacklist</code>
   <value>[Team ID]</value>
 </attributes>
</product>

Mainly the <code> elements differ from the ‘TextCreate’ product according to the product’s name. Also a slightly difference within the offered text lengths must be considered (see 2.2). Last but not least the <link> element must point to the product.

The main difference is viewable within the form definition of the Task-template. There must be a definition of the keywords the clickworker is supposed to include in the text he they creates. So additionally to the ‘normal’ input elements (3.1.3.1) the keyword elements must be defined as follows:

<elements>
 <is_output>false</is_output>
 <titles>
   <de>Keyword A</de>
   <en>Keyword A</en>
 </titles>
 <is_mandatory>true</is_mandatory>
 <type>keyword</type>
 <item_code>keyword_a</item_code>
 <sort_order>50</sort_order>
 <options>
   <code>min_occurrence_ref</code>
   <value>keyword_a_min</value>
 </options>
 <options>
   <code>max_occurrence_ref</code>
   <value>keyword_a_max</value>
 </options>
 <options>
   <code>reference_code</code>
   <value>all</value>
 </options>
</elements>

This element has the value ‘keyword’ for the <type> element configured. The type ‘keyword’ has the following options to be defined:

These options and their relevance become more apparent if we look to the corresponding Task-upload

3.5.1 Task submission using Product TextCreateWithKeywords

For the above described definition of a keyword element the related Task-upload (see also 3.2.2) needs to be extended by an additional input element:

<items>
  <code>keyword_a</code>
  <content>Bottrop</content>
</items>
<items>
  <code>keyword_a_min</code>
  <content>1</content>
</items>
<items>
  <code>keyword_a_max</code>
  <content>2</content>
</items>

The items with the defined <code> ‘keyword_a_min’ and ‘keyword_a_max’ define the minimal and maximal occurence count of the keyword ‘Bottrop’. hese item codes are defined within the Tasktemplate. Together with the defined value ‘all’ for the keyword option ‘reference_code’ this means that the term ‘Bottrop’ must be included 1 or 2 times within the result fields ‘title_top’ or ‘paragraph_bottom’ (as per our example in 3.1.3.2).

With this definition the clickworker has to submit the results including 1 or 2 times the term ‘Bottrop’.

If the keyword should only be included in a particular output field this would need to be defined within the Task-template. E.G. a definition of:

<options>
  <code>reference_code</code>
  <value>title_top</value>
</options>

would ensure that the keyword is only included to the output field ‘title_top’.

3.5.2 Summary

As mentioned before there are two main aspects which differ between the ‘TextCreate’ and the ‘TextCreateWithKeywords’ Product:

• The Task-template defines an input element of type ‘keyword’
• The Task-upload must include the keyword and defines it’s occurrence count

3.6 Survey

Additional to the both above explained text-based products we offer a Product “Survey”. This product offers the opportunity to survey our Clickworkers to any scientific or market oriented topic. The main dea here is that a customer prepares a survey on any external website reachable via a Url. The lickworkers will click on the given link and participate in the survey. Once the survey is finished a code is shown to the participants. This code is pre-configured on the clickworker.com latform and needs to be entered into a form to proof that he finished the survey. With this the lickworker is getting paid.

The use of the Product survey starts again with the definition of the task-template.

3.6.1 Prdouct Specific Attributes

As the standard attributes for the task-template are always the same (see 3.1.1) we start with the Product specific attributes:

<product>
 <link href="/api/marketplace/v2/products/Survey" rel="product"
type="application/xml"/>
 <attributes>
   <code>mp_df_survey_country</code>
   <value>[Countrycode]</value>
 </attributes>
 <attributes>
   <code>mp_df_survey_payment</code>
   <value>[CW payment in Cent]</value>
  </attributes>
 <attributes>
   <code>mp_df_survey_age_from</code>
   <value>[18-99]</value>
 </attributes>
 <attributes>
   <code>mp_df_survey_age_to</code>
   <value>[18-99]</value>
 </attributes>
 <attributes>
   <code>mp_df_survey_gender</code>
   <value>[f|m|a]</value>
 </attributes>
 <attributes>
   <code>mp_df_survey_expiration</code>
   <value>[expiration-date]</value>
 </attributes>
 <attributes>
   <code>mp_df_survey_code</code>
   <value>[confirmation-code]</value>
 </attributes>
 <attributes>
   <code>mp_df_survey_add_user_hash</code>
   <value>[yes|no]</value>
 </attributes>
 <attributes>
   <code>mp_df_same_url_for_all</code>
   <value>[yes|no]</value>
 </attributes>

 <attributes>
   <code>mp_df_individual_codes</code>
   <value>[yes|no]</value>
 </attributes>
 <attributes>
   <code>team_whitelist</code>
   <value>[Team ID]</value>
 </attributes>
 <attributes>
   <code>team_blacklist</code>
   <value>[Team ID]</value>
 </attributes>
</product>

• mp_df_survey_country (mandatory)

With this you can choose the country where our Clickworkers need to be located to participate in your survey. Valid country-codes are: at (Austria), be (Belgium), gb (Great Britain), es (Spain), pt (Portugal), pl (Poland), nl (Netherlands), it (Italy), in (India), fr (France), de (Germany), ca (Canada), us (USA), ch (Suisse). Mandatory if no whitelist provided.

• mp_df_survey_payment (mandatory)

Here you enter the Clickworker’s fee to participate in your survey. We will add 40% to the amount for your invoice. Please offer a reasonable fee to make sure enough of our Clickworker’s are motivated to participate in your survey. The number will be interpreted as Cent (1/100) from your configured customer currency.

• mp_df_survey_age_from (mandatory)

Here you can enter the minimum age of the Clickworker’s to participate (18-99). Mandatory if no whitelist provided.

• mp_df_survey_age_to (mandatory)

Here you can enter the maximum age of the Clickworker’s to participate (18-99). Mandatory if no whitelist provided.

-mp_df_survey_gender (optional)

Here you can enter the wanted gender of the Clickworkers to participate. Valid values are f (female) and m (male) or a (all).

• mp_df_survey_expiration (optional)

Here you enter until when your survey shall be online (if not yet finished). Enter in the format yyyy-mm-dd (e.G.: 2015-01-02)

• mp_df_survey_code (mandatory)

To ensure that our Clickworkers complete the survey, you have to show a code at the end of the survey. Our Clickworkers will enter this code on our platform to proof that they participated in the survey. Here you have to enter exactly the code you will show at the end of the survey. This code is the same for all participants (the use of individual codes is also possible – see below ‘mp_df_individual_codes’).

• mp_df_survey_add_user_hash (optional)

Here you configure if the we shall append an unique identifier of the Clickworker calling the URL of the survey. Allowed values are ‘yes’ or ‘no’ with the following result: yes: http://www.mysurvey.com/ -> http://www.mysurvey.com/?user=af37289db32b2c779273a982828fe8e79a08b782 no: http://www.mysurvey.com/ -> http://www.mysurvey.com/ Be aware that this identification is for statistical usage only.

• mp_df_same_url_for_all

If the URL to the externally hosted Survey is the same for all participants, configure ‘yes’. In this case you will be able to easily enter the needed number of participants and the URL in one task creation request only.

• mp_df_individual_codes

If you are able to provide an individual URL for each Participant it would also be possible to store an individual confirmation code for each URL. In this case a unique confirmation code would be shown at the end of the survey, which the Clickworker would need to enter within our Platform to get paid for his participation. This makes only sense if ‘mp_df_same_url_for_all’ (see previous bullet point) has been configured as ‘no’. If you choose ‘yes’ for the individual confirmation-codes an additional form-element named ‘code’ needs to be part of your task creation request. Within this element you enter the confirmation code for each URL separately. If a Clickworker picks up the Job with the particular URL our system expects the Clickworker to enter the code configured here within the same task creation request. Only if the Clickworker’s Code and the Code from the task creation request are the same the Clickworker is getting paid.

• team_whitelist (optional)

Users from whitelist (team) will be included to the survey. If no demography is provided, then only the users on the whitelist can participate.

• team_blacklist (optional)

Users from blacklist (team) will be excluded from the survey.

3.6.2 The Form

In general in case of external hosted surveys there re only one or two input field necessary to show the external Url (and maybe transfer the individual confirmation code or the number of requested participants) to our Clickworkers:

<form>
 <elements>
   <is_output>false</is_output>
   <titles>
     <de>URL</de>
     <en>URL</en>
   </titles>
   <is_mandatory>true</is_mandatory>
   <type>url</type>
   <item_code>link_to_survey</item_code>
   <sort_order>10</sort_order>
 </elements>

 <!-- next element only if ‘mp_df_same_url_for_all’ has been configured as ‘yes’ and
‘mp_df_individual_codes’ has been configured as ‘no’ in the product-configuration
above -->
 <elements>
   <is_output>false</is_output>
   <titles>
     <de>no_of_participants</de>
     <en>no_of_participants</en>
   </titles>
   <is_mandatory>true</is_mandatory>
   <type>hidden</type>
   <item_code>participants</item_code>
   <sort_order>20</sort_order>
 </elements>
<!-- next element only if ‘mp_df_same_url_for_all’ has been configured as ‘no’ and
‘mp_df_individual_codes’ has been configured as ‘yes’ in the product-configuration
above -->
 <elements>
   <is_output>false</is_output>
   <titles>
     <de>Code</de>
     <en>Code</en>
   </titles>
   <is_mandatory>false</is_mandatory>
   <type>hidden</type>
   <item_code>code</item_code>
   <sort_order>20</sort_order>
 </elements>
</form> 

3.6.3 Putting it all together

To prepare a survey with female Cickworkers from Germany in the age from 18-60, paying 100 Eurocent each we would create a task-template like this:

<task_template>
  <code>unqiue_template_id_1234</code>
  <name>Survey3000</name>
  <titles>
    <de>Eine Umfrage über Handies</de>
    <en>A survey about mobiles</en>
  </titles>
  <descriptions>
    <de>Bitte klicken Sie auf die URL und nehmen Sie an der Umfrage teil.</de>
    <en>Please click on the link and participate in the survey.</en>
  </descriptions>
  <product>
  <link href="/api/marketplace/v2/products/Survey" rel="product"
type="application/xml"/>

    <attributes>
      <code>mp_df_survey_country</code>
      <value>de</value>
    </attributes>
    <attributes>
      <code>mp_df_survey_payment</code>
      <value>100</value>
    </attributes>

    <attributes>
      <code>mp_df_survey_age_from</code>
      <value>18</value>
    </attributes>
    <attributes>
      <code>mp_df_survey_age_to</code>
      <value>60</value>
    </attributes>
    <attributes>
      <code>mp_df_survey_gender</code>
      <value>f</value>
    </attributes>

    <attributes>
      <code>mp_df_survey_expiration</code>
      <value>2015-03-30</value>
    </attributes>
    <attributes>
      <code>mp_df_survey_code</code>
      <value>1234</value>
    </attributes>
    <attributes>
      <code>mp_df_survey_add_user_hash</code>
      <value>no</value>
    </attributes>

    <attributes>
      <code>mp_df_same_url_for_all</code>
      <value>yes</value>
    </attributes>

    <attributes>
      <code>mp_df_individual_codes</code>
      <value>no</value>
    </attributes>
  </product>
<form>
  <elements>
    <is_output>false</is_output>
    <titles>
      <de>URL</de>
      <en>URL</en>
    </titles>
    <is_mandatory>true</is_mandatory>
    <type>url</type>
    <item_code>link_to_survey</item_code>
    <sort_order>10</sort_order>
  </elements>
  <elements>
    <is_output>false</is_output>
    <titles>
      <de>no_of_participants</de>
      <en>no_of_participants</en>
    </titles>
    <is_mandatory>true</is_mandatory>
    <type>hidden</type>
    <item_code>participants</item_code>
    <sort_order>20</sort_order>
 </elements>
 <!—Following element not needed as ‘mp_df_same_url_for_all’ has been configured as
‘yes’ and ‘mp_df_individual_codes’ has been configured as ‘no’ above.
 <elements>
   <is_output>false</is_output>
   <titles>
     <de>Code</de>
     <en>Code</en>
   </titles>
   <is_mandatory>false</is_mandatory>
   <type>hidden</type>
   <item_code>code</item_code>
   <sort_order>20</sort_order>
 </elements>
-->
 </form>
</task_template>

3.6.4 Upload a task for the survey

With the above constructed task-template we can immediately post a task with the following configuration:

<task>
  <customer_ref>Handy-Umfrage</customer_ref>
  <template>
    <link
href="/api/marketplace/v2/customer/task_templates/unqiue%255Ftemplate%255Fid%255F1234"
rel="task_template" type="application/xml" />
  </template>
  <input>
    <items>
      <code>link_to_survey</code>
      <content>http://www.mysurvey.de/survey3000</content>
    </items>
    <items>
      <code>participants</code>
      <content>1000</content>
    </items>
<!—Following element not needed as ‘mp_df_same_url_for_all’ has been configured as ‘yes’ and ‘mp_df_individual_codes’ has been configured as ‘no’ within the tasktemplate. But if it would be configured the other way around it would be needed and it would replace the former item ‘participants’
    <items>
      <code>code</code>
      <content>6789</content>
    </items>
-->
   </input>
 </task>

As a response the following XML document will be send by our API:

<task_response>
  <request_status>
    <id>7a++TncqQ/QUgUTGQXy6PiHu/Rs=</id>
    <valid>true</valid>
    <status_code>200</status_code>
    <status_text>OK</status_text>
  </request_status>
  <task>
    <link type="application/xml" href=
"http://localhost:3000/api/marketplace/v2/customer/tasks/174811" rel="self"/>
    <id>174811</id>
    <customer_ref>Handy-Umfrage</customer_ref>
    <template>
      <link type="application/xml" href=
"http://localhost:3000/api/marketplace/v2/customer/task_templates/unqiue_template_id_1
234" rel="self"/>
      <product>
        <link type="application/xml" href=
"http://localhost:3000/api/marketplace/v2/products/Survey" rel="self"/>
      </product>
    </template>
    <net_amount>1.4</net_amount>
    <tax_amount>0.27</tax_amount>
    <amount>1.67</amount>
    <currency>EUR</currency>
    <state>confirmed</state>
    <inputs>
      <code>link_to_survey</code>
      <content>http://www.mysurvey.de/survey3000</content>
    </inputs>
    <inputs>
      <code>participants</code>
      <content>1000</content>
    </inputs>
  </task>
</task_response>

As you can see we invoice 140% of the Clickworker’s fee (1.4 * 100 Cent = 1.40€).

The above given task will be rendered on the clickworker platform as follows:

If you want 1000 Clickworkers to participate in the survey you may need to post 1000 tasks through our API for technical reasons. We make sure that only distinct Clickworkers will participate. If you have choosen ‘mp_df_same_url_for_all’ as ‘yes’ within your task-template you would be able to request 1000 participants with the post of one task only

4 How-to for specific usage scenarios

Within this chapter the following scenarios will be described:

• How to get task-results if notifications cannot be used
• How to find tasks using the customer specific task reference

4.1 How to get task-results if notifications cannot be used

If you cannot use notification for processing the events CUSTOMER_INPUT_REQUIRED and/or the TASK_COMPLETED, you must take care tracking result sign off yourself. As explained in 3.4 any Task detail can be retrieved by an http-GET request to the corresponding URL (e.g.:

https://[environment].clickworker.com/api/marketplace/v2/customer/tasks/2405829?show_cloned_task=true).

For practical reasons this approach must be extended by a feature to get an overview of all tasks and their corresponding states. A http-GET request to the URL:

https://[environment].clickworker.com/api/marketplace/v2/customer/tasks would show all tasks from the customer as a list in the following format:

<tasks>
  <link href=
"https://[environment].clickworker.com/api/marketplace/v2/customer/tasks/[task_id]"
rel="task" type="application/xml"/>
  <customer_ref>[CUSTOMER_REF]</customer_ref>
  <template>
    <link href=
"https://[environment].clickworker.com/api/marketplace/v2/customer/task_templates/
[tt_code]" rel="task_template" type="application/xml"/>
    <product>
      <link href=
"https://[environment].clickworker.com/api/marketplace/v2/products/TextCreate"
rel="product" type="application/xml"/>
    </product>
  </template>
  <state>finished</state>
  <created_at>2013- 10 - 17T09:22:16+02:00</created_at>
</tasks>

The request-URL can be configured by the use of request-Parameter:

To request a list of tasks that are waiting for the customer’s approval, the URL would be:

https://[environment].clickworker.com/api/marketplace/v2/customer/tasks?state=feedback

To request a list of tasks created during a specific timeframe, the URL would be:

https://[environment].clickworker.com/api/marketplace/v2/customer/tasks?from=10.10.2013&to=14.10.2013

4.2 How to get tasks by customer reference

Within the examples of the Task-upload (see 3.2.1) is shown that customers can pass-through their own identifier if desired. With this identifier all tasks from a specific customer can be filtered using the following

URL:

https://[environment].clickworker.com/api/marketplace/v2/customer/tasks/search? customer_ref=[customer_ref].

As a result the same list of tasks is presented to the customer as described in the section before.

5 Form elements

As described in 3.1.3 the <form> element of the Task-template defines the element that carries the in and output for each text creation process.

For example there is an output element defined:

<elements>
  <is_output>true</is_output>
  <titles>
    <de>Textblock</de>
    <en>Paragraph</en>
  </titles>
  <is_mandatory>true</is_mandatory>
  <type>text_area</type>
  <item_code>paragraph_bottom</item_code>
  <sort_order>30</sort_order>
</elements>

As the customer wanted this element to carry text data the <type> here has been defined as ‘text_area’. There are several other ‘types’ available to carry specific types of data. This is true for input and for output elements.

The following table lists all available types of form elements and explains their specific use case:

This needs work. Not sure how to do this complicated a table in markdown. This is proper markdown but it won’t render

|<type>|use case|options|description| |text_field|In- or output of single line text.|is_mandatory|Field must be filled (valid for input elements during Task-creation or for output elements during result creation)?|

| | |min_length|Minimum input length in characters.|
| | |max_length|Maximum input length in characters.|

|text_area|In- or output of multi line text.|is_mandatory|Field must be filled?|
| | |min_length|Minimum input length in characters.|
| | |max_length|Maximum input length in characters.|
| | |is_richtext|Defines, whether this field supports HTML rich text. The default is “false”.|
|number|In- or output of numbers.|is_mandatory|Field must be filled?|
| | |min_value|The minimum value allowed.|
| | |max_value|The maximum value allowed.|
|date|In- or output of dates.|is_mandatory|Field must be filled?|
| | |min_date|Defines the earliest date that can be entered.|
| | |max_date|Defines the latest date that can be entered|
|keyword|Input of keywords which should be included in the text.|is_mandatory|Field must be filled?|
| | |min_occurrence_ref|This option defines the Task’s data item code to read from the minimal occurrence count of the keyword.|
| | |max_occurrence_ref|This option defines the Task’s data item code to read from the maximal occurrence count of the keyword.|
reference_code Enter the code of a data
item
here to check for
keywords only in this
item. Otherwise, leave
blank or use the
special value “all” to scan
for keywords in
all suitable fields.

email In- or output of eMail addresses.

is_mandatory Field must be filled?

url In- or output of clickable URLs. is_mandatory Field must be filled?

with_protocol Defines whether the
clickworker has to enter
the
protocol prefix (e.g.
http://)

drop_box

multi_select

check_box

radio_button

In- or output of a selection list
with multiple alternatives.

is_mandatory Field must be filled?

alternatives List of alternatives to pick
from. Every
alternative has one
attribute:

• The alternatives value that will be used when setting the Form Element’s value and label.

An example of ‘drop_box’ is given as:

<elements>
<type>drop_box</type>
<titles>
<en>Please choose</en>
<de>Bitte wählen Sie</de>
</titles>
<item_code>selected_language</item_code>
<options>
<code>alternatives</code>

<!-- ************first entry************ -->

<value>
<value>de</value>
</value>

<!-- ************second entry************ -->

<value>
<value>fr</value>
</value>

</options>
</elements>