Event Feed

From ICPC-Contest Control Standard

NOTICE: This draft proposal is unlikely to ever be implemented. There is a new CCS REST interface proposal and JSON event feed in progress that has supplanted this draft as the new direction.


The Event Feed is an externally-accessible XML feed of contest data supplied by a Contest Control System. The event feed is the primary way that external clients can get the state of a running contest.

Getting the feed

Connect to port 4713 and the entire feed for the contest will be sent to you. When the contest is finalized, the contest tag will be closed and the connection closed.

Connect to port 4714 and the entire feed for the contest will be sent to you, with the exception that no judgement information will be sent for runs submitted during the last hour. When the contest is finalized, the contest tag will be closed and the connection closed (but you will still not get judgements for runs submitted the last hour).

Information updates

CCSs will typically send all configuration elements, followed by a set of events.

Under some circumstances configuration or event elements may be resent. These circumstances include but are not limited to:

  • Changing some contest configuration, such as the start time
  • Rejudgements of runs
  • Fixing typos in names

Under some circumstances the connection may be dropped. These circumstances include but are not limited to:

  • Removal (or reinsertion) of a time interval

When reconnecting, all elements will

If a client reconnects to the event feed it will get all configuration and events from the beginning. The client cannot assume that it will see the exact same elements after a reconnect and should discard any state constructed from the event feed prior to reconnecting.

Top level structure

The event feed is an XML document within the root element <contest>.

Within the contest element are a number of configuration items and events, each of which are separate top-level elements:

Event types & tags:

Element Contains Type
info contest information and updates Configuration
language submission language information Configuration
region superregion information Configuration
judgement judgement information Configuration
problem problem information Configuration
team team information Configuration
clar-request clarification request Event
clar-response clarification (answers to clarification requests) or broadcast messages Event
submission submission from a team Event
submission-judgement result of submission from a team Event
run judgement of individual input file for a run Event
finalized the contest standings/medals are assigned, contest is over Event

Other elements beyond what is documented here may also be sent, these should be ignored. This applies both at the top level and within the top-level elements.

Notes

  1. All child-elements are required unless otherwise documented.
  2. All contest-time elements are in decimal seconds.
  3. All timestamp elements are in decimal seconds since the Unix epoch, Jan 1st, 1970 00:00:00 UTC.

Configuration elements

Configuration elements will be sent in the beginning of the feed. The exception to this rule is if the data in a configuration element is changed in which case it will be resent

Info

Format:

Name Description Type
title Contest title xsd:string
length Length of contest xsd:string HH:MM:SS
scoreboard-freeze-length Length of time at the end of the contest when scoreboard is frozen xsd:string HH:MM:SS
penalty-amount Penalty time xsd:int minutes
start-time Wall-clock start time of the contest xsd:decimal seconds (timestamp)

Any new info element overrides earlier elements.

Example:

<info>
  <title>The 2010 World Finals of the ACM International Collegiate Programming Contest</title>
  <length>05:00:00</length>
  <scoreboard-freeze-length>01:00:00</scoreboard-freeze-length>
  <penalty-amount>20</penalty>
  <start-time>1265335138.26</start-time>
</info>

Language

Format:

Name Description Type
name Language name xsd:string

Example:

<language>
  <name>C++</name>
</language>

Group

Format:

Name Description Type
name Group name from groups.tsv xsd:string

Example:

<group>
  <name>Europe</name>
</group>

Judgement

Format:

Name Description Type
acronym Judgement acronym xsd:string
name Judgement full name xsd:string
penalty True if this judgement is a failure that causes penalty time to be added xsd:boolean

Example:

<judgement>
  <acronym>WA</acronym>
  <name>Wrong Answer</name>
  <penalty>true</penalty>
</judgement>

Problem

Format:

Name Description Child Element/Attribute Type
label Problem label, typically a single upper case letter element xsd:string
name Problem name element xsd:string

A problem element is identified by it's label. If a problem element with the same label as an earlier element arrives the latter overrides the former.

Example:

<problem>
  <label>A</label>
  <name>APL Lives!</name>
</problem>

Team

Format:

Name Description Type
n Team number xsd:int
icpc-id ID from ICPC registration system. Used to match this team to other resources, such as university logos or team pictures optional xsd:int
name Team name xsd:string
nationality Country code, ISO 3166-1 alpha-3 xsd:string
university University name xsd:string
group Group name, must match some name given in a group element optional xsd:string
WF CCS must include icpc-id and group. This requirement should be put in CCS document

A team element is identified by it's team number. If a team element with the same team number as an earlier element arrives the latter overwrites the former.

Example:

<team>
  <n>1</n>
  <icpc-id>23412</icpc-id>
  <name>American University of Beirut</name>
  <nationality>LBN</nationality>
  <university>American University of Beirut</university> 
  <group>Europe</group> 
</team>

Event elements

Clarification request

The clar-request event is sent when a team submits a clarification request.

Format:

Name Description Type
id Clarification Request ID xsd:int
team-number Team ID xsd:int
question A question, typically from a team xsd:string
category Clarification category xsd:string
contest-time Contest-time when the clarification was submitted xsd:decimal
timestamp Wall-clock time when the clarification was submitted xsd:decimal

Example:

<clar-request>
  <id>1</id>
  <team-number>0</team-number>
  <question>What is the upper limit on the number of pieces of chocolate requested by the friends?</question>
  <category>Problem C</category>
  <contest-time>118.48</contest-time>
  <timestamp>1265335256.74</timestamp>
</clar-request>

Clarification response

The clar response event is sent when a clar request has been answered.

Format:

Name Description Type
clar-request-id Clarification Request ID xsd:int
question A question, typically from a team xsd:string
answer Judge's answer to the question xsd:string
to-all True if the response was sent to all teams xsd:boolean
contest-time Contest time when the response was submitted xsd:decimal
timestamp Wall-clock time when the response was submitted xsd:decimal

Example:

<clar-response>
  <clar-request-id>1</clar-request-id>
  <question>What is the upper limit on the number of pieces of chocolate requested by the friends?</question>
  <answer>The number of pieces will fit in a signed 32-bit integer.</answer>
  <to-all>true</to-all>
  <contest-time>118.48</contest-time>
  <timestamp>1265335256.74</timestamp>
</clar-response>

Submission

An event sent whenever a team makes a submission.

Format:

Name Description Type
id Submission ID xsd:int
team-number Team Number xsd:int
problem-label Problem label xsd:string
language Language name xsd:string
contest-time Contest time when the run was submitted xsd:decimal
timestamp Wall-clock time when the submission was made xsd:decimal

Example:

<submission>
  <id>1410</id>
  <team-number>74</team-number>
  <problem-label>D</problem-label>
  <language>C++</language>
  <contest-time>17960.74</contest-time>
  <timestamp>1265353100.29</timestamp>
</submission>

Submission judgement

A run judgement event is sent whenever a judgement has been assigned to a run.

Format:

Name Description Type
submission-id Submission ID xsd:int
judgement Judgement acronym xsd:string
contest-time Contest time when the judgement was assigned xsd:decimal
timestamp Wall-clock time when the judgement was assigned xsd:decimal
scoreboard-update Information about scoreboard row updated as a result of this judgement element

Format of element scoreboard-update:

Name Description Type
sort-key Sort key that represents the scoreboard in descending order. I.e. the row with the highest sort key represents the team currently in the lead. Sort keys are equal if and only if position is tied. Sort key for rows not yet seen (i.e. representing teams with no judgements so far) is zero. xsd:integer
team Team number. Must always be the same as the team number for the submission event with submission id as in the parent element. Is repeated here for simplicity for clients xsd:int
solved-count Number of solved problems xsd:int
time Total penalty time xsd:int
problem Scoreboard data for a problem element

Format of element problem:

Name Description Type
label Problem label, typically a single upper case letter. Must match label given in some earlier problem element. Only problems where information is not false and zeroes must be listed. A label may only occur once in a given scoreboard-update xsd:string
solved Is problem with associated label solved by associated team xsd:boolean
subs Number of submissions on problem by team xsd:string
time Total penalty time on problem xsd:string


Example:

<submission-judgement>
  <submission-id>1410</submission-id>
  <judgement>WA</judgement>
  <contest-time>179.74</contest-time>
  <timestamp>1265353100.29</timestamp>
  <scoreboard-update>
    <sort-key>12345</sort-key>
    <team>23</team>
    <solved-count>9</solved-count>
    
    <problem>
      <label>A</label><solved>true</solved><subs>3</subs>
    </problem>
    <problem>
      <label>B</label><solved>true</solved><subs>3</subs>
    </problem>
    <problem>
      <label>C</label><solved>true</solved><subs>3</subs>
    </problem>
    <problem>
      <label>D</label><solved>true</solved><subs>3</subs>
    </problem>
    <problem>
      <label>E</label><solved>true</solved><subs>3</subs>
    </problem>
  </scoreboard-update>
</submission-judgement>

Run

A run event is sent when a submission is judged against an input file.

Format:

Name Description Child Element/Attribute Type
submission-id Submission ID of submission that this run is part of attribute xsd:int
idx Input file index (1-based) attribute xsd:int
count Total number of input files attribute xsd:int
judgement Judgement acronym. Must match an acronym given in some earlier judgement element element xsd:string
contest-time Contest time when the test was judged element xsd:decimal
timestamp Wall-clock time when the test was judged element xsd:decimal

Example:

<run>
  <submission-id>1</run-id>
  <idx>1</idx>
  <judgement>WA</judgement>
  <count>1</count>
  
  <timestamp>1265336078.01</timestamp>
</run>

Finalized

The finalized event is sent when the contest is finalized.

Format:

Name Description Type
timestamp Wall-clock time when the contest was finalized xsd:decimal seconds
last-gold The last place to receive a gold (should always be 4 for a compliant system) xsd:int
last-silver The last place to receive a silver (should always be 8 for a compliant system) xsd:int
last-bronze The last place to receive a bronze (should often be 12 but could very possibly be something else) xsd:int
comment A comment provided during the finalization xsd:string

Example:

<finalized>
  <timestamp>1265336078.01</timestamp>
  <last-gold>4</last-gold>
  <last-silver>8</last-silver>
  <last-bronze>12</last-bronze>
  <comment>Finalized by John Doe and Jane Doe</comment>
</finalized>

Change List

The following is a list of behavioural changes from the 2014 event feed:

  • Removed <started> boolean from <info>
  • Removed <id> from <language>
  • Renamed <run> to <submission>
  • Renamed <testcase> to <run>