Step 1 on how to place an order using the API.

Step 1 - Setup a TaskTemplate

To define the TaskTemplate, including your order specific parameters such as the briefing, target language, etc., the customer needs to create a specific structured XML-document for the API. This XML-document is called the ‘Task-template’.

Configure standard attributes

The following XML document shows the standard attributes for the text products. Standard attributes are common to all TaskTemplates, regardless of the product chosen.

  • XML
<task_template>
  <code>[unique_template_id_1234]</code>
  <name>[TEMPLATE NAME]</name>
  <titles>
    <de>[GERMAN TITLE]</de>
    <en>[ENGLISH TITLE]</en>
  </titles>
  <descriptions>
    <de>[GERMAN DESCRIPTION]</de>
    <en>[ENGLISH DESCRIPTION]</en>
  </descriptions>
</task_template>

Note: Values to be be filled in are marked in brackets placeholders “[]”.

These standard product parameters have the following meaning:

  • <code>: a unique identifier for the customer (string).
  • <name>: a unique Task-template name for the customer (string)
  • <titles>: The title in German (<de>) and English (<en>), will be shown to the clickworkers. It should be short, but descriptive.
  • <descriptions>: The working instruction of the requested texts. Here the customer needs to state as clear as possible what kind of text he expects to be written by the clickworkers.

Configue Product specific attributes

The child element contains the product specific attributes.

  • XML
<product>
  <link href="/api/marketplace/v2/products/TextCreate" rel="product"
type="application/xml"/>

  <attributes>
    <code>textcreate_language</code>
    <value>[WANTED LANGUAGE]</value>
  </attributes>

  <attributes>
    <code>textcreate_text_length</code>
    <value>[WANTED TEXT LENGTH]</value>
  </attributes>

  <attributes>
    <code>textcreate_proof_read</code>
    <value>[textcreate_proof_yes | textcreate_proof_no]</value>
  </attributes>
</product>

The <descriptions> tag above is essential for the quality of the created texts. As it is shown to the clickworkers as their working instruction it should be easy to understand and formatted well. We strongly advise to use encoded html-tags to structure the description in a meaningful manner. For this online tools like http://www.opinionatedgeek.com/DotNet/Tools/HTMLEncode/encode.aspx can be used.

An encoded description looks like this:

  • html
&lt;h1&gt;I am an encoded html-working instruction&lt;/h1&gt;
&lt;h2&gt;I am an encoded html-working instruction&lt;/h2&gt;
&lt;h3&gt;I am an encoded html-working instruction&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;Point 1&lt;/li&gt;
&lt;li&gt;Point 2&lt;/li&gt;
&lt;li&gt;Point 3&lt;/li&gt;
&lt;/ul&gt;

which is encoded from the following original html text:

  • XML
<h1>I am an encoded html-working instruction</h1>
<h2>I am an encoded html-working instruction</h2>
<h3>I am an encoded html-working instruction</h3>
<ul>
  <li>Point 1</li>
  <li>Point 2</li>
  <li>Point 3</li>
</ul>

Product Specific Attributes

The child element <product> contains the product specific attributes.

  • XML
<product>
  <link href="/api/marketplace/v2/products/TextCreate" rel="product" type="application/xml"/>
  
  <attributes>
    <code>textcreate_sample</code>
    <value>[EXAMPLE TEXT]</value>
  </attributes>

  <attributes>
    <code>textcreate_description</code>
    <value>[DESCRIPTION]</value>
  </attributes>
</product>

Choose your product by replacing

<link href=”[URL TO PRODUCT]” rel=”product” type=”application/xml” />

by

  • /api/marketplace/v2/products/TextCreate
  • /api/marketplace/v2/products/TextCreateWithKeywords
  • or the URL for your customer specific product provided by Solutions

See 2.2 for the differences between these two products.

In the example above the attributes for the “TextCreate” product are shown. Their meaning are:

  • textcreate_language (mandatory) Defines the language of the text to be authored. The languages supported and their needed language code are listed here: [languages ]
  • textcreate_text_length (mandatory) Defines the valid range of text length. All results fields are counted and summed up. The supported lengths are listed here: [text lengths]. The syntax must be: [lower limit]#[upper limit] - e.g. 10#
  • textcreate_proof_read (mandatory) Define whether quality assurance using review by second clickworker is requested. Valid options are: “textcreate_proof_yes” or “textcreate_proof_no”. Hint: For testing purposes in sandbox, you may want to switch quality assurance off, so you can bypass a number of jobs.
  • textcreate_sample (optional) Contains an example text for clickworkers. We strongly recommended to provide examples, as they will significantly improve the quality of authored content. clickworker will have a clearer understanding of the style and character of the requested text.
  • textcreate_description (mandatory) Contains an internal description for the task. This content will not be shown to clickworkers.

An example of a well-configured Task-template is shown as follows:

  • XML
<product>
  <link href="/api/marketplace/v2/products/TextCreate" rel="product"
type="application/xml"/>

  <attributes>
    <code>textcreate_language</code>
    <value>de</value>
  </attributes>

  <attributes>
    <code>textcreate_text_length</code>
    <value>10#55</value>
  </attributes>

  <attributes>
    <code>textcreate_proof_read</code>
    <value>textcreate_proof_yes</value>
  </attributes>

  <attributes>
    <code>textcreate_sample</code>
    <value>Hier sollte Ihr Beispieltext stehen.</value>
  </attributes>

  <attributes>
    <code>textcreate_description</code>
    <value>Lorem ipsum dolor sit amet, consectetur, adipisci velit, ... </value>
   </attributes>
</product>

Define Form Elements

Finally, the <form> element, defines the document structure for the tasks, based on input and output elements. It consists of several elements. Each of this element is either a read-only input or a writable output of each task.

Form Input

If a clickworker, for example, is asked to write a text about a hotel, and the information source is the URL of the hotel’s website, this URL must be given to the clickworker. Exactly for this kind of input data for each task a read-only element is defined. These configurations are used to render the input values as HTML. In the hotel-URL example it could be defined as follows:

  • XML
<elements>
  <is_output>false</is_output>
  <titles>
    <de> Hotel-URL</de>
    <en>Hotel URL</en>
  </titles>
  <is_mandatory>true</is_mandatory> 
  <type>url</type>
  <item_code>link_to_hotel</item_code>
  <sort_order>10</sort_order>
</elements>

The children are:

  • <is_output> The value ‘false’ in the above example defines this element as an input element for the task.
  • <titles> This element provides the title of the element in the different languages: de (german) and en (english). The value here is shown to the clickworker in front of the corresponding input data (it is the label of the element).
  • <is_mandatory> If “true”, defines that the clickworker must provide a value for this field.
  • <type> In the above-described hotel URL example the type is given as ‘url’. With this the input data will be rendered as a clickable html link. Depending on the semantics of the input data several types of elements are available. See 5 for details.
  • <item_code> The item code needs to be a unique identifier in the context of the Task-template. Herewith the association to the later uploaded input data is done.
  • <sort_order> The final configuration done for the element is the sort order. This defines the position of the input element in the form. Over all elements defined within the Task-template the sort order determines the vertical order from top to bottom shown to the clickworkers.

Although the XML document is quite comprehensive, it is advised to check how the form looks like from a clickworker’s perspective. In order to do so, submit a task and login as a clickworker in the sandbox enironment for preview.

Form Output

In addition to the input data, the desired output data structure carrying the results of the task must be defined. Similar to the input elements, output data structure is also defined by a set of . The main difference is that its child element will be set to ‘true’.

Each output element can be configured more detailed, so the complete output can be structured to fulfil the customer’s requirements. The most frequently used detail configuration for an output element is the definition of the minimal and maximal length of a text field.

According to the hotel URL example, you may want the text the author to provide the result as a separate header field and a paragraph section, rather than one chunk of text. In this common scenario you would need to define two output elements.

The configuration for a heading and a paragraph is:

  • XML
<elements>
  <is_output>true</is_output>
  <titles>
    <de>Überschrift</de>
    <en>Heading</en>
  </titles>
  <is_mandatory>true</is_mandatory>
  <type>text_field</type>
  <item_code>title_top</item_code>
  <sort_order>20</sort_order>
  <options>
    <code>min_length</code>
    <value> 5 </value>
  </options>
  <options>
    <code>max_length</code>
    <value>15</value>
  </options>
</elements>

<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>
  <options>
    <code>min_length</code>
    <value> 5 </value>
  </options>
  <options>
    <code>max_length</code>
    <value> 40 </value>
  </options>
</elements>

As shown the accumulated min_length of both elements is 10. The accumulated max_length of both elements is 55. This fits into the configured text length for the overall text length from 10 to 55.

Important Note : Make sure that the min/max lengths for the output fields add up to the valid min/max length of the total text. Otherwise this may result in situations where clickworkers cannot save their work due to conflicting contraints!

For a complete list of additional configuration options of output elements see chapter 5.

Putting it all together

Putting all parts of the Task-template together the complete ordering/configuration of the project looks like this:

  • XML
<task_template>

  <code>unqiue_template_id_1234</code>
  <name>Hotel-Beschreibungen</name>
  <titles>
    <de>Informative Beschreibungen von Hotels</de>
    <en>Informative descriptions of hotels</en>
  </titles>
  <descriptions>
    <de>Hier sollte Ihr Briefing für die clickworker stehen.</de>
    <en>Here you should describe the instructions for the clickworkers.</en>
  </descriptions>
  <product>
  <link href="/api/marketplace/v2/products/TextCreate" rel="product"
type="application/xml"/>

  <attributes>
  <code>textcreate_language</code>
  <value>de</value>
  </attributes>

  <attributes>
    <code>textcreate_text_length</code>
    <value>10#55</value>
  </attributes>

  <attributes>
    <code>textcreate_proof_read</code>
    <value>textcreate_proof_yes</value>
  </attributes>

  <attributes>
    <code>textcreate_sample</code>
    <value>Hier sollte ein Beispieltext stehen.</value>
  </attributes>

  <attributes>
    <code>textcreate_description</code>
    <value>Lorem ipsum dolor sit amet, consectetur, adipisci velit, ... </value>
  </attributes>
</product>

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

<elements>
  <is_output>true</is_output>
  <titles>
    <de>Überschrift</de>
    <en>Heading</en>
  </titles>
  <is_mandatory>true</is_mandatory>
  <type>text_field</type>
  <item_code>title_top</item_code>
  <sort_order>20</sort_order>
  <options>
    <code>min_length</code>
    <value>10</value>
  </options>
  <options>
    <code>max_length</code>
    <value>15</value>
  </options>
</elements>

<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>
  </form>
</task_template>

To finish the initial project configuration, send a http-POST request to https://.clickworker.com/api/marketplace/v2/customer/task_templates. As we strongly recommend to test the setup first on the sandbox environment the placeholder should be ‘sandbox’ (for production this would be ‘api’).

The Task-template itself would be saved as a XML-document and forming the request-body.

Tags: