Unfuddle API: Data Models

Account,
Attachment,
Backup,
Changeset,
Comment,
Component,
CustomFieldValue,
Involvement,
Message,
Milestone,
Notebook,
Page,
Person,
Project,
Repository,
Severity,
Subscription,
Ticket,
TicketAssociation,
TicketReport,
TimeEntry,
Version

Introduction

The following list contains definitions for all data models used in the Unfuddle API.

All field values are strings unless otherwise specified via the 'type' attribute.
If the value of a field is restricted to closed set of values, these values have been provided in brackets [v1,v2,etc].
Read/write fields are dark blue, versus read only fields which are red.
If the model is returned in a response body as something other than XML, then the fields will be the same, but the format will naturally be different (i.e. fields in JSON will have underscores, not dashes).
When using the query string parameter "formatted=true", all "created_at" and "updated_at" fields will have the formatted counterparts "created_at_formatted" and "updated_at_formatted".

Account

<account>
  <access-key> </access-key>
  <created-at type="datetime"> </created-at>
  <default-ticket-report-id type="integer"> </default-ticket-report-id>
  <default-time-zone> <!-- i.e. "Pacific Time (US & Canada)" --> </default-time-zone>
  <description> </description>
  <disk-usage type="integer"> <!-- in Kilobytes --> </disk-usage>
  <id type="integer"> </id>
  <plan> [private, micro, compact, corporate, enterprise] </plan>
  <subdomain> </subdomain>
  <!-- a list with valid markups; the first value is the default one -->
  <text-markup> [markdown, textile, plain] </text-markup> 
  <title> </title>
  <updated-at type="datetime"> </updated-at>
  
  <!-- the following is read-only and describes the feature set of an account -->
  <features>
    <attachments type="boolean"> [true, false] </attachments>
    <ssl type="boolean"> [true, false] </ssl>
    <storage type="integer"> <!-- in Megabytes --> </storage>
    <time-tracking type="boolean"> [true, false] </time-tracking>
  </features>
</account>

Attachment

<attachment>
  <content-type> </content-type>
  <created-at type="datetime"> </created-at>
  <filename> </filename>
  <id type="integer"> </id>
  <parent-id type="integer"> </parent-id>
  <parent-type> [Message, Ticket, Notebook, Comment] </parent-type>
  <size> </size>
  <updated-at type="datetime"> </updated-at>

  <!--
  when creating a new attachment, the following section must also
  be including in order to reference the upload key you received
  after uploading the file to the API
  -->
  <upload>
    <key> </key>
  </upload>
</attachment>

Backup

<backup>
  <created-at type="datetime"> </created-at>
  <id type="integer"> </id>
  <parts type"integer"> </parts>
  <processed type="boolean"> [true, false] </processed>
  <processed-at type="datetime"> </processed-at>
  <project-id type="integer"> </project-id>
  <requester-id type="integer"> </requester-id>
</backup>

Changeset

<changeset>
  <!--
  Note that not all repositories systems distinguish between
  the author and committer (i.e. Subversion does not)
  -->
  <author-id type="integer"> </author-id>
  <author-name> </author-name>
  <author-email> </author-email>
  <author-date type="datetime"> <!-- the date the patch was authored --> </author-date>
  <committer-id type="integer"> </committer-id>
  <committer-name> </committer-name>
  <committer-email> </committer-email>
  <committer-date type="datetime"> <!-- the date of the commit --> </committer-date>
  <created-at type="datetime"> </created-at>
  <id type="integer"> </id>
  <message> </message>
  <message-formatted> <!-- only available if formatted=true --> </message-formatted>
  <repository-id type="integer"> </repository-id>
  <revision> </revision>
</changeset>

Comment

<comment>
  <author-id type="integer"> </author-id>
  <body> </body>
  <body-format> [markdown, textile, plain] </body-format>
  <body-formatted> <!-- only available if formatted=true --> </body-formatted>
  <created-at type="datetime"> </created-at>
  <id type="integer"> </id>
  <parent-id type="integer"> </parent-id>
  <parent-type> [Message, Ticket] </parent-type>
  <updated-at type="datetime"> </updated-at>
  
  <attachments type="array"><!-- only available if attachments=true -->
    <attachment>...</attachment>
    ...
  </attachments>
</comment>

Component

<component>
  <created-at type="datetime"> </created-at>
  <id type="integer"> </id>
  <name> </name>
  <project-id type="integer"> </project-id>
  <updated-at type="datetime"> </updated-at>
</component>

CustomFieldValue

<custom-field-value>
  <created-at type="datetime"> </created-at>
  <field-number type="integer"> [1, 2, 3] </field-number>
  <id type="integer"> </id>
  <project-id type="integer"> </project-id>
  <updated-at type="datetime"> </updated-at>
  <value> </value>
</custom-field-value>

Involvement

<involvement>
  <created-at type="datetime"> </created-at>
  <id type="integer"> </id>
  <!--
  Within the Involvement model, setting 'is-administrator' to true will
  make the person a project administrator for the given project.
  -->
  <is-administrator type="boolean"> [true, false] </is-administrator>
  <messages> [none, read, readcreate, manage] </messages>
  <milestones> [none, read, manage] </milestones>
  <notebooks> [none, read, manage] </notebooks>
  <people> [none, read, invite, manage] </people>
  <person-id type="integer"> </person-id>
  <project-id type="integer"> </project-id>
  <source> [none, read, commit] </source>
  <tickets> [none, read, create, readcreate, manage] </tickets>
  <updated-at type="datetime"> </updated-at>
</involvement>

Message

<message>
  <author-id type="integer"> </author-id>
  <body> </body>
  <body-format> [markdown, textile, plain] </body-format>
  <body-formatted> <!-- only available if formatted=true --> </body-formatted>
  <created-at type="datetime"> </created-at>
  <id type="integer"> </id>
  <project-id type="integer"> </project-id>
  <title> </title>
  <updated-at type="datetime"> </updated-at>
  
  <!--
  If categories are specified on UPDATE, then the existing categories
  will be completely replaced by the newly provided categories.
  -->
  <categories>
    <category id="5555"/>
    ...
  </categories>
  
  <comments type="array"><!-- only available if comments=true -->
    <comment></comment>
    ...
  </comments>
  
  <attachments type="array"><!-- only available if attachments=true -->
    <attachment>...</attachment>
    ...
  </attachments>
</message>

Milestone

<milestone>
  <archived type="boolean"> [true, false] </archived>
  <completed type="boolean"> [true, false] </completed>
  <created-at type="datetime"> </created-at>
  <due-on type="date"> </due-on>
  <due-on-formatted> </due-on-formatted>
  <id type="integer"> </id>
  <person-responsible-id type="integer"> </person-responsible-id>
  <project-id type="integer"> </project-id>
  <title> </title>
  <updated-at type="datetime"> </updated-at>
</milestone>

Notebook

<notebook>
  <created-at type="datetime"> </created-at>
  <default-page-id type="integer"> </default-page-id>
  <id type="integer"> </id>
  <project-id type="integer"> </project-id>
  <title> </title>
  <updated-at type="datetime"> </updated-at>
  
  <attachments type="array"><!-- only available if attachments=true -->
    <attachment>...</attachment>
    ...
  </attachments>
</notebook>

Page

<page>
  <author-id type="integer"> </author-id>
  <body> </body>
  <body-format> [markdown, textile, plain] </body-format>
  <body-formatted> <!-- only available if formatted=true --> </body-formatted>
  <created-at type="datetime"> </created-at>
  <id type="integer"> </id>
  <message> </message>
  <message-formatted> <!-- only available if formatted=true --> </message-formatted>
  <notebook-id type="integer"> </notebook-id>
  <number type="integer"> </number>
  <title> </title>
  <updated-at type="datetime"> </updated-at>
  <version type="integer"> </version>

  <!--
  This is not an actual attribute, but when updating a page,
  including this boolean and setting it to true will cause the
  page to be overwritten as a minor change.
  -->
  <minor type="boolean"> [true, false] </minor>
</page>

Person

<person>
  <!-- only available for the /api/v1/people/current endpoint -->
  <access-key> </access-key>
  <account-id type="integer"> </account-id>
  <created-at type="datetime"> </created-at>
  <email> </email>
  <first-name> </first-name>
  <id type="integer"> </id>
  <!--
  Within the Person model, setting 'is-administrator' to true will
  make the person an account administrator.
  -->
  <is-administrator type="boolean"> [true, false] </is-administrator>
  <is-removed type="boolean"> [true, false] </is-removed>
  <last-name> </last-name>
  <last-signed-in type="datetime"> </last-signed-in>
  <last-signed-in-formatted> <!-- only available if formatted=true --> </last-signed-in-formatted>
  <notification-frequency> [immediate, 30mins, hourly, dailyam, dailypm, never] </notification-frequency>
  <notification-ignore-self type="boolean"> [true, false] </notification-ignore-self>
  <notification-last-sent type="datetime"> </notification-last-sent>
  <notification-scope-messages> [all, none] </notification-scope-messages>
  <notification-scope-milestones> [all, none] </notification-scope-milestones>
  <notification-scope-source> [all, none] </notification-scope-source>
  <notification-scope-tickets> [all, involved, none] </notification-scope-tickets>
  <show-help-messages type="boolean"> [true, false] </show-help-messages>
  <text-markup> [markdown, textile, plain] </text-markup>
  <time-zone> <!-- i.e. "Pacific Time (US & Canada)" --> </time-zone>
  <updated-at type="datetime"> </updated-at>
  <!-- The username it is not available for removed people -->
  <username> </username>
</person>

Project

<project>
  <account-id type="integer"> </account-id>
  <archived type="boolean"> [true, false] </archived>
  <assignee-on-resolve> [reporter, none, nochange] </assignee-on-resolve>
  <backup-frequency type="integer">0</backup-frequency>
  <close-ticket-simultaneously-default type="boolean"> [true, false] </close-ticket-simultaneously-default>
  <created-at type="datetime"> </created-at>
  <default-ticket-report-id type="integer"> </default-ticket-report-id>
  <description> </description>
  <disk-usage type="integer"> <!-- in Kilobytes --> </disk-usage>
  <enable-time-tracking type="boolean"> [true, false] </enable-time-tracking>
  <id type="integer"> </id>
  <s3-access-key-id></s3-access-key-id>
  <s3-backup-enabled type="boolean">false</s3-backup-enabled>
  <s3-bucket-name></s3-bucket-name>
  <short-name> </short-name>
  <theme> [blue, green, grey, orange, purple, red, teal] </theme>
  <ticket-field1-active type="boolean"> [true, false] </ticket-field1-active>
  <ticket-field1-title> </ticket-field1-title>
  <ticket-field1-disposition> [list, text] </ticket-field1-disposition>
  <ticket-field2-active type="boolean"> [true, false] </ticket-field2-active>
  <ticket-field2-title> </ticket-field2-title>
  <ticket-field2-disposition> [list, text] </ticket-field2-disposition>
  <ticket-field3-active type="boolean"> [true, false] </ticket-field3-active>
  <ticket-field3-title> </ticket-field3-title>
  <ticket-field3-disposition> [list, text] </ticket-field3-disposition>
  <title> </title>
  <updated-at type="datetime"> </updated-at>
</project>

Repository

<repository>
  <abbreviation> </abbreviation>
  <account-id type="integer"> </account-id>
  <created-at type="datetime"> </created-at>
  <description> </description>
  <id type="integer"> </id>
  <system> [git,svn] </system>
  <title> </title>
  <updated-at type="datetime"> </updated-at>

  <!--
  If projects are specified on UPDATE, then the existing projects
  will be completely replaced by the newly provided projects.
  -->
  <projects>
    <project id="22222"/>
    ...
  </projects>
</repository>

Severity

<severity>
  <created-at type="datetime"> </created-at>
  <id type="integer"> </id>
  <name> </name>
  <project-id type="integer"> </project-id>
  <updated-at type="datetime"> </updated-at>
</severity>

Subscription

<subscription>
  <created-at type="datetime"> </created-at>
  <id type="integer"> </id>
  <parent-id type="integer"> </parent-id>
  <parent-type> [Ticket] </parent-type>
  <person-id type="integer"> </person-id>
  <updated-at type="datetime"> </updated-at>
</subscription>

Ticket

<ticket>
  <assignee-id type="integer"> </assignee-id>
  <component-id type="integer"> </component-id>
  <created-at type="datetime"> </created-at>
  <description> </description>
  <description-format> [markdown, textile, plain] </description-format>
  <description-formatted> <!-- only available if formatted=true --> </description-formatted>
  <due-on type="date"> </due-on>
  <due-on-formatted> </due-on-formatted>
  <field1-value-id="integer"> </field1-value-id>
  <field2-value-id="integer"> </field2-value-id>
  <field3-value-id="integer"> </field3-value-id>
  <hours-estimate-current type="float"> </hours-estimate-current>
  <hours-estimate-initial type="float"> </hours-estimate-initial>
  <id type="integer"> </id>
  <milestone-id type="integer"> </milestone-id>
  <number type="integer"> </number>
  <priority> [1, 2, 3, 4, 5] </priority>
  <project-id type="integer"> </project-id>
  <reporter-id type="integer"> </reporter-id>
  <resolution> [fixed, works_for_me, postponed, duplicate, will_not_fix, invalid] </resolution>
  <resolution-description> </resolution-description>
  <resolution-description-format> [markdown, textile, plain] </resolution-description-format>
  <resolution-description-formatted> <!-- only available if formatted=true --> </resolution-description-formatted>
  <severity-id type="integer"> </severity-id>
  <status> [new, unaccepted, reassigned, reopened, accepted, resolved, closed] </status>
  <summary> </summary>
  <updated-at type="datetime"> </updated-at>
  <version-id type="integer"> </version-id>
    
  <!--
  The following are not actual ticket attributes, but when creating or updating
  a ticket, including any of these three attributes instead of the corresponding
  <fieldN-value-id> attributes will allow you to create a new value for
  the ticekt field if that field is of the "text" disposition.
  -->
  <field1-value> </field1-value>
  <field2-value> </field2-value>
  <field3-value> </field3-value>
  
  <comments type="array"><!-- only available if comments=true -->
    <comment></comment>
    ...
  </comments>
  
  <attachments type="array"><!-- only available if attachments=true -->
    <attachment>...</attachment>
    ...
  </attachments>
</ticket>

TicketAssociation

<ticket-association>
  <created-at type="datetime"> </created-at>
  <id type="integer"> </id>
  <relationship> [parent, duplicate, related] </relationship>
  <ticket1-id type="integer"> </ticket1-id>
  <ticket2-id type="integer"> </ticket2-id>
</ticket-association>

TicketReport

<ticket-report>
  <conditions-string>
    <!--
    A comma separated list of report criteria composed as "field-expr-value, field-expr-value"
      
      "field" is one of the following: [number, summary, priority, status, resolution, milestone, component, version, severity, reporter, assignee, created_at, updated_at, last_comment_at, due_on, field_1, field_2, field_3]
      "expr" is one of the following: [eq, neq, gt, lt, gteq, lteq]
      "value" is an appropriate value for the given field; "value" can also be "current" for fields that represent people.
      
    Example: "assignee-eq-current,status-eq-closed,milestone-eq-34584"
    -->
  </conditions-string>
  <created-at type="datetime"> </created-at>
  <fields-string>
    <!--
    A comma separated list composed of any or all of the following:
    
    [project, number, summary, priority, component, version, severity, milestone, due_on, reporter, assignee, status, resolution, comments, associations, hours_estimate_initial, hours_estimate_current, hours_actual, percentage_complete, created_at, updated_at, closed_on, field_1, field_2, field_3]    
    -->
  </fields-string>
  <group-by> [project, priority, component, version, severity, milestone, due_on, reporter, assignee, status, resolution, field_1, field_2, field_3] </group-by>
  <id type="integer"> </id>
  <parent-id type="integer"> </parent-id>
  <parent-type> [Account, Project] </parent-type>
  <sort-by> </sort-by>
  <sort-direction> [ASC, DESC] </sort-direction>
  <title> </title>
  <updated-at type="datetime"> </updated-at>
  
  <!--
  If you 'generate' the report, then the following section will also
  be available in the response.
  -->
  <groups>
    <group>
      <title> </title>
      <tickets>
        <ticket> ... </ticket>
        ...
      </tickets>
    </group>
    ...
  </groups>
</ticket-report>

Time Entry

<time-entry>
  <created-at type="datetime">  </created-at>
  <date type="date"> </date>
  <description> </description>
  <hours type="float"> </hours>
  <id type="integer"> </id>
  <person-id type="integer"> </person-id>
  <ticket-id type="integer"> </ticket-id>
  <updated-at type="datetime"> </updated-at>
</time-entry>

Version

<version>
  <created-at type="datetime"> </created-at>
  <id type="integer"> </id>
  <name> </name>
  <project-id type="integer"> </project-id>
  <updated-at type="datetime"> </updated-at>
</version>

Unfuddle API: Data Models

Introduction

Account

Attachment

Backup

Category

Changeset

Comment

Component

CustomFieldValue

Involvement

Message

Milestone

Notebook

Page

Person

Project

Repository

Severity

Subscription

Ticket

TicketAssociation

TicketReport

Time Entry

Version

Unfuddle API

Usage Scenarios

Reference