Contesta Interface Descriptions

Here you can find a description of how to import and export data for your judging software to be compatible with Contesta.

The Contesta process

Contesta is open for every judging platform. It defines standard interfaces in csv, so you are able to import data entered by the participants in your Contest to your judging system. The actual image files are delivered in a defined file structure and can be downloaded by the organizer with the Contesta downloader.

After the judging is done, the results can be re-imported to Contesta for the results processing functionality (such as result gallery pages or result emails).

The following chapters show the csv interfaces for participant data and images with example files. The organizer can download these files for his/her contest from Contesta at the admin export area.

After the registration period has ended and the participants have paid their contest fees, their images and entered information can be downloaded by the admin from the Contesta Export page.

The export format is defined below. It is a more or less Comma Separated Value (CSV) format that is instantly compatible with Microsoft Office Excel ©.

Export File-Format

Value enclosure sign "
End of line sign \r\n
Delimiter between values \t
Byte order mark Yes (0xFF 0xFE)
Encoding UTF-16LE

Export Datatypes

Data Type Description Informative Regex
String Character string with all possible UTF-16LE signs. .*
Integer Full numeric value without decimal places (positive and negative). [0]|[-]?[1-9][0-9]*
Unsigned Full numeric value without decimal places (only positive). [0]|[1-9][0-9]*
Boolean A true (1) or false (0) value. 0|1
Date A date value in the format DD.MM.yy in the time zone GMT+1. [0-9]{0,2}\.[0-9]{0,2}\.[0-9]{0,2}
Email An email address. .+@.+
Decimal A decimal number rounded to two digits. [0-9]+\.[0-9]{2,2}

Export Fields

The following fields can be used in the export files. Additionally, the administrator can add optional fields that the participant has to enter when registering. These fields are exported as additional fields at the end of an export.

Field ID

Field name

Data Type

Formatting

Description

Example

User.id

User id

Unsigned

 

Unique ID of the participant

  • 9
  • 234

User.email

User email

String

 

Validated E-mail address of the participant

  • example@qwerty.co.uk
  • my_mail@mail.com

User.role

User role

String

 

The role of the user

  • admin
  • user
  • groupadmin

User.group_id

Group id

Unsigned

 

The id of the group the user is part in or admin of.

  • 21
  • 33
  • 47

User.activated

Activated

Boolean

 

1 if the user has been activated (by email or manually by admin), otherwise 0.

  • 1
  • 0

User.fixed

Fixed

Boolean

 

1 if the user has fixed (finalized) his contribution, otherwise 0.

  • 1
  • 0

User.language

Language

String

 

The ISO 639-3 code of the user language.

  • deu
  • eng
  • zho

User.Detail.forename

Forename

String

 

Forename of the participant

  • John Don
  • Dominik
  • Sergio

User.Detail.lastname

Lastname

String

 

Last name of the participant

  • White
  • Van der Sinnen
  • Andradé

User.Detail.addressline1

Address line 1

String

 

Address (Line 1) of the participant

  • Freigthlane 12
  • 3rd Avenue
  • Hartgasse 18/82

User.Detail.addressline2

Address line 2

String

 

Address (Line 2) of the participant

  • Top 12
  • Post box 234
  • 17

User.Detail.phone

Phone

String

 

Telephone number of the participant

  • 0049723123746
  • +1912372 312
  • +43 8173 1623849

User.Detail.town

town

String

 

Address (Town)

  • London
  • Leeds
  • Abu-Dhabi

User.Detail.zip

zip

String

 

Address (Postal Code) of the participant

  • NW1927
  • 23845
  • 2345

User.Detail.country

country

String

CC

Address (country) of the participant in 3166-1 alpha-2

  • UK
  • DE
  • AT

User.Detail.birth_date

birth_date

String

dd.mm.YY

Date of birth of the participant

22.08.93

User.Detail.state

state

String

Address (state) of the participant

  • Washingtown
  • Bayern
  • Wien

User.Detail.organization_type_abbreviation

Organization type

String

The organization type the user is in

  • AMA
  • PRO
  • SCHUL

User.Detail.organization_name

Organization Name

String

The name of the organization

  • IBM
  • Oxford University
  • First Photography Club Luxembourg

User.Detail.entry_class

Entry Class

String

Entry class the user is in

  • Amateur
  • Pro
  • Teens
  • Senior
  • Underage

Upload.id

Upload-ID

Unsigned

 

Unique ID of the image

  • 1
  • 82875

Upload.title

Image Title

string

 

Title of the image

Big Rose

Upload.size

Image Size

Integer

 

Size of the image in byte

  • 9697068

Upload.user_id

User that uploaded the image

Unsigned

 

Unique id of the user that uploaded the image.

  • 1213
  • 56
  • 1

Upload.category_id

Category id

Integer

 

The ID of the category the image takes part in.

  • 2
  • 12

Upload.print_received

Print Received

Boolean

 

1 if the admin marked the print image as received, otherwise 0.

  • 1
  • 0

Upload.filehash

File Hash

String

 

32 chars long md5 hash of the file used to verify the integrity of the file.

  • 3d513f3e41bb05a55- c034913cbfd747a
  • 7ae04ab5256c96e09- d270d6bec58ee41

Upload.width

Width

Unsigned

 

Width of the image in pixel.

  • 1331
  • 786654

Upload.height

Height

Unsigned

 

Height of the image in pixel.

  • 1331
  • 786654

Upload.width_small

Width Small

Unsigned

 

Width of the thumbnail of the image in pixel.

  • 12
  • 27

Upload.height_small

Height Small

Unsigned

 

Height of the thumbnail of the image in pixel.

  • 55
  • 62

Upload.type

Type

String

 

MIME type of the uploaded image.

  • image/jpeg
  • image/png

Upload.tag_type

Tag Type

String

 

Type of the tag given to the image by the admin.

  • problematic_authorship
  • duplicate
  • not_allowed_content
  • edited
  • wrong_category
  • on_notice
  • other

Upload.tag_text

Tag Text

String

 

Text of the tag given to the image by the admin.

  • This image seems to be in the wrong category!
  • Is this image a duplicate of the image 231?

Category.id

Category Id

Unsigned

 

Identification of the category

  • 2
  • 12

Category.name

Category Name

String

 

Name of the category in the default language.

  • Black & White
  • Nature

Category.description

Category Description

String

 

Description of the category in the default language.

  • This is a text with a description of the category.
  • Lorem ipsum

Category.abbreviation

Category Abbreviation

String

 

Abbreviation of the category.

  • BW
  • NA

Category.print

Category print

Boolean

 

1 if the category is a print category, otherwise 0.

  • 1
  • 0

Payment.id

Payment Id

Unsigned

 

Identification of the payment

  • 2
  • 12

Payment.status

Payment Status

String

 

The status of the payment transaction.

  • canceled
  • paid
  • initiated

Group.group_name

Group name

String

 

The name of the group the user is a member of

  • FIAP Fotofriends
  • FC Uppertown

Payment.total_amount_gross

Payment Total Amount Gross

Decimal

 

Total amount (gross) that is being paid with this transaction.

  • 33.22
  • 12.00
  • 0.00

Payment.total_amount_net

Payment Total Amount Net

Decimal

 

Total amount (gross) that is being paid with this transaction.

  • 33.22
  • 12.00
  • 0.00

Payment.system

Payment System

String

 

Total payment system used for this transaction.

  • credit_card
  • bank_transfer
  • paypal

Payment.created

Payment Created

Datetime

 

Time the transaction has been created.

  • 04.11.11, 20:59
  • 19.01.14, 18:57
  • 25.08.15, 23:04

Payment.currency

Payment Currency

String

 

Currency in ISO-4217 of the transaction.

  • DZD
  • EUR
  • OMR

Payment.vat

Payment Taxes

Decimal

 

Taxes included in the payment.

  • 0.00
  • 13.23
  • 23.12

Contributions Export Formats

The following files contain the contest's contributions. Optionally, the organizer can choose to only export users with a specific finalization/payment status or age.

Since the participants must fill out their full user details (like name, address or birthday) before finalizing their contribution, there might be some user detail information blank if the export is not filtered by finalization status.

Format: "CSV for ExcelVote"

Export Name: CSV for ExcelVote
Content: Contributions
File Type: CSV

Download example file

Field ID

User.id
User.Detail.forename
User.Detail.lastname
Upload.title
Upload.id
Upload.type
Upload.extension
User.Detail.birth_date
Upload.categoryname
Upload.category_id
Upload.categoryshort
User.Detail.adressline1
User.Detail.adressline2
User.Detail.zip
User.Detail.town
User.email
User.Detail.organization_type_abbreviation
User.Detail.organization_name
Contest.name

The following special transformation rules are applied to this export.

From Field ID To Field ID Transformation Description Example
User.id User.id Left padding of Zeros ("0") until the length of 5 characters is reached 00004
Upload.id Upload.id Left padding of Zeros ("0") until the length of 5 characters is reached 00012
Upload.category_id Upload.categoryname The actual name of the category Schwarz Weiß
Upload.category_id Upload.categoryshort The short name of the category SW
Upload.type Upload.extension The extension of the file uploaded jpg

Format: "Uploads CSV with all fields"

Export Name: Uploads CSV with all fields
Content: Contributions
File Type: CSV

Download example file

Format: "Uploads CSV with all fields"

Field ID

Upload.id
Upload.title
Upload.size
Upload.category_id
Upload.category_name
Upload.category_abbreviation
Upload.created
Upload.filehash
Upload.type
User.id
User.email
User.Detail.forename
User.Detail.lastname
User.Detail.adressline1
User.Detail.adressline2
User.Detail.town
User.Detail.zip
User.Detail.country
User.Detail.birth_date
User.Detail.organization_type_abbreviation
User.Detail.organization_name
User.Detail.entry_class
Contest.name

The following special transformation rules are applied to this export.

From Field ID To Field ID Transformation Description Example
Upload.category_id Upload.categoryname The actual name of the category Black and White
Upload.category_id Upload.categoryshort The short name of the category BW

Payments Export Formats

Format: "Payments CSV with all fields"

Export Name: Payments CSV with all fields
Content: Payments
File Type: CSV

Download example file

Field ID

Payment.id
Payment.status
Payment.total_amount_gross
Payment.total_amount_net
Payment.system
Payment.created
Payment.currency
Payment.vat
User.id
User.email

The following special transformation rules are applied to this export.

From Field ID To Field ID Transformation Description Example
Payment.total_amount_gross, Payment.currency Payment.total_amount_gross Display the field in common currency format, depending on the currency paid in
  • €1.234,99
  • $1,234.99
Payment.total_amount_net, Payment.currency Payment.total_amount_net Display the field in common currency format, depending on the currency paid in
  • €1.234,99
  • $1,234.99
Payment.vat, Payment.currency Payment.vat Display the field in common currency format, depending on the currency paid in
  • €1.234,99
  • $1,234.99

Categories Export Formats

Format: "CSV with all fields"

Export Name: Categories CSV with all fields
Content: Categories
File Type: CSV

Download example file

Field ID

Category.id
Category.name
Category.description
Category.abbreviation
Category.print

Files Export Formats

The administrator can use Contesta Exporter to download the images uploaded by participants. Before downloading the needed ".con" file he can enter a pattern the images are named after. By choosing a pattern for the files he is able to name the files using the images and the participants information (except the optionals). The pattern consists of field names (see above) and functions. The file-naming pattern can also have a path separator "/" in it in order to create sub-folders. The fields usable in the export pattern are defined in the chapter "Export Fields".

Additionally the administrator can use functions in the pattern. These functions can be used to transform the image or participants information or to have conditions (when-then relations). The usable functions are defined below.

The implication of this functionality is that you can probably tell the administrator a format you want to have the picture names in, but also that in the export files (CSV files) there is no possibility to export the "name" of the files since it is chosen during the download of the images.

Function

Usage

Example

Description

leftpad

leftpad([value_to_pad],[number_of_signs_total],[padding_sign])

leftpad(%Upload.id%,5,0)

Adds signs (padding_sign) to the left side of a word or number until it has the required number of signs (number_of_signs_total).

upper

upper([value_to_upper])

upper(%Upload.title%)

Makes the string uppercase.

lower

lower([value_to_lower])

lower(%Upload.title%)

Makes the string lowercase.

length

length([value])

length(%Upload.title%)

Returns the number of signs in the word.

condition

condition([condition],[value_if],[value_else])

condition(%Detail.organization_type_abbreviation% ==SCH,%User.id%,123)

Returns value_if if the condition is true, otherwise value_else.

Predefined File Export Formats

The following file pattern have been pre-defined. Though the organizer can enter his/her own file pattern.

Votesta %Upload.id%.%Upload.extension%
ExcelVote %User.Detail.entry_class%/%Upload.categoryname%/%Upload.id%.%Upload.extension%
Juror %Upload.categoryshort%/%Upload.id%.%Upload.extension%


After the judging has been completed, the admin can import the results to the Contesta platform, for example to display the contest results and send out information emails to the participants.

It is not required to re-import the results, but it helps sending email to the participants and to create the result pages. You can obviously create result pages and send out the result emails manually, but if the used judging system can provide the import files Contesta can do this automatically.

It is important that the result information does not contradict the export information of Contesta, so the images must be in the same categories and there can be no image missing and the ids (images, user, category etc.), entry classes and the Salon name should be correct since they are mapped to the existing categories in Contesta. If the import file is not consistent with the Contesta export, Contesta will decline the upload of the results file with a descriptive error message.

Image Result Import

The image result import defines the results of each single image.

Field Name

Data type

Description

Example

Upload id Unsigned The unique ID of the award - must be the same as exported from contesta 2
User id Unsigned The unique ID of the user that has uploaded the image - must be the same as exported from contesta 3
Category abbreviation String The short name of the category BWP
Category id Unsigned The category id - must be the same as exported from contesta. Only must be present if award is given in a category (such as Rankmedals) 1
Award ids Comma Separated Values The ids of awards (as defined in the file Award Result Import) an image has received 1, 2
Points Integer The points the image has achieved 13
Rank Integer The rank the image has achieved 2
Result Integer Can be Priced (for images that have received an award), Accepted (for images that have not received an award but are above the acceptance limit) or Rejected (for images that are below the acceptance limit) Priced
Salon String The name of the salon of this judging - must be the same as exported from contesta Your Salon
Entry class String The name of the entry class of an image - must be the same as exported from contesta. If there are no entry classes can be empty. Youth

Combination Result Import

The combination result import defines the results for a single user, both in separate categories (category user results) and for the whole salon (salon user results). If no category is given, the result is considered to be a salon user result.

Field Name

Data type

Description

Example

User id Unsigned Unique ID of the user - must be the same as exported from contesta 2
Category abbreviation String The short name of the category. Only must be present for category user results, for salon user results must be left empty. BWP
Category id Unsigned The category id - must be the same as exported from contesta. Only must be present for category user results, for salon user results must be left empty. 1
Award ids Comma Separated Values The ids of awards (as defined in the file Award Result Import) a participant has received 1, 3
Points Integer The points a user has received 22
Rank Integer The rank a user has achieved (either in a category or the whole salon) 5
Salon String The name of the salon of this judging - must be the same as exported from contesta Your Salon
Entry class String The name of the entry class a participant is under must be the same as exported from contesta, if there are no entry classes the default value is 'standard' Youth

Salon Result Import

The result import defines basic information about the salon, such as the minimum/maximum points per image and the entry classes. Contains a single line per category plus one line with information regarding the whole salon.

Field Name

Data type

Description

Example

Salon name String The name of the salon of this judging - must be the same as exported from contesta Your Salon
Category String The short name of the category BWP
Category id Unsigned The category id - must be the same as exported from contesta plus a line for the whole salon with the category id 'CombinationSalon'. 2
Entry Class String The name of the entry class for a salon result - must be the same as exported from contesta, if there are no entry classes the default value is 'standard' Youth
Minimum points for acceptance Integer The minimum number of points an image must have received to still be Accepted 51
Minimum points for award Integer The minimum number of points an image must have received to receive an award 71
Minimum points per image Integer The minimum number of points an image can have received (e.g. 0 if there are 3 judges and 0 minimum points a judge can give to an image) 0
Maximum points per image Integer The maximum number of points an image can have received (e.g. 30 if there are 3 judges and 10 maximum points a judge can give to an image) 80

Award Import

The award import defines the awards that were present in the contest.

Field Name

Data type

Description

Example

id Unsigned Unique ID of the award 2
Patronage name String Name of the patronage an award is under FIAP
Entry class String The name of the entry class for an award. If there are no entry classes the default value is 'standard' Youth
Category abbreviation String The short name of the category. For awards that do not have a category (salon image awards, salon user awards and salon team awards) can be left empty. BWP
Category id Unsigned The category id - must be the same as exported from contesta. Only must be present if award is given in a category (category user awards, category image awards), otherwise can be left empty 1
Award name String Full name of the award Gold medal
Award abbreviation String Unique short name of the Award GMF
Order Unsigned The 'importance' of a medal, starting with 1 1
Award Type String The type of the award.
'category_image_award' for a medal for images in a single category (such as Gold Medal in Category Color)
'salon_image_award' for a medal that is given to a single image over the whole contest (such as Best Image)
'category_user_award' for a medal that is given to a participant in a single category (such as Best User in Category Color)
'salon_user_award' for a medal that is given to a participant over the whole contest (such as Best User)
'salon_team_award' for a medal that is given to a team (such as Best Team)
category_user_award
Given Boolean 'yes' if the medal is distributed to a user/image/team, 'no' if not yes

Team/Organization Result Import

This contains information about organization results.

Field Name

Data type

Description

Example

organization name String The name of the organization/team - must be the same as exported from contesta HTL Ottakring
organization type String The type of the organization - must be the same as exported from contesta School
ranking Integer The rank the team has achieved 2
points Integer The points the team has received 122
Award ids Comma Separated Values The ids of awards (as defined in the file Award Result Import) a team has received 3, 4
Entry class String The name of the entry class a team is under - must be the same as exported from contesta Youth
Salon String The name of the salon of this judging - must be the same as exported from contesta Your Salon

If you have any questions regarding the interfaces feel free to contact us.