DocsAPI ReferenceBlog
Docs

Resources and collections

Suggest Edits

Entity

Entity represents Targetprocess objects such as User Story, Bug, Task, Project, Iteration etc. It contains Fields, Nested entities and Collections of Nested entities. Here is an example of simplified entity structure for User Story:

1096

📘

You can get various entities like User Stories, Bugs, Tasks, Iterations, Releases, Test Cases, etc. Check API Reference documentation for more details.

Entity always has an Id field.

<UserStory ResourceType="UserStory" Id="1667" Name="Create landing page for site">
  <!-- Fields -->
  <Description nil="true"/>
  <StartDate>2016-10-16T04:27:10</StartDate>
  <EndDate nil="true"/>
  <CreateDate>2016-10-16T04:27:10</CreateDate>
  <ModifyDate>2016-10-16T04:27:48</ModifyDate>
  <LastCommentDate nil="true"/>
  <Tags/>
  <NumericPriority>270.375</NumericPriority>
  <Effort>0.0000</Effort>
  <EffortCompleted>0.0000</EffortCompleted>
  <EffortToDo>0.0000</EffortToDo>
  <Progress>0.0000</Progress>
  <TimeSpent>0.0000</TimeSpent>
  <TimeRemain>0.0000</TimeRemain>
  <LastStateChangeDate>2016-10-16T04:27:10</LastStateChangeDate>
  <PlannedStartDate nil="true"/>
  <PlannedEndDate nil="true"/>
  <InitialEstimate>0.0000</InitialEstimate>
    <!-- References to other resources -->
  <EntityType ResourceType="EntityType" Id="4" Name="UserStory"/>
  <Project ResourceType="Project" Id="1583" Name="dsfsdf">
    <Process ResourceType="Process" Id="3" Name="Scrum"/>
  </Project>
  <Owner ResourceType="GeneralUser" Id="1">
    <FirstName>Administrator</FirstName>
    <LastName>Administrator</LastName>
    <Login>admin</Login>
  </Owner>
  <LastCommentedUser nil="true"/>
  <LinkedTestPlan nil="true"/>
  <Release nil="true"/>
  <Iteration nil="true"/>
  <TeamIteration nil="true"/>
  <Team nil="true"/>
  <Priority ResourceType="Priority" Id="5" Name="Nice To Have">
    <Importance>5</Importance>
  </Priority>
  <EntityState ResourceType="EntityState" Id="46" Name="Open">
    <NumericPriority>46</NumericPriority>
  </EntityState>
  <ResponsibleTeam nil="true"/>
  <Feature nil="true"/>
  <!-- Collections -->
  <Tasks>
    <Task ResourceType="Task" Id="137130" Name="Design"/>
    <Task ResourceType="Task" Id="137132" Name="HTML coding"/>
  </Tasks>
  <CustomFields>
    <Field Type="DropDown">
      <Name>Risk</Name>
      <Value nil="true"/>
    </Field>
  </CustomFields>
</UserStory>

To retrieve a single Entity use format:

/api/v1/{Entities}/[id]

For example, to retrieve a Bug with Id = 84 send the following request:

/api/v1/Bugs/84

Hierarchy

Some of the Entities are organized into the following hierarchy:

  • General
    • Assignable
      • InboundAssignable
      • OutboundAssignable
      • Epic
      • Feature
      • UserStory
      • Task
      • Bug
      • TestPlan
      • TestPlanRun
      • Request
    • Project
    • Program
    • Release
    • Iteration
    • TeamIteration
    • Team
    • TestCase

So instead of working with a particular Entity Type, like User Story, we can work with an Assignable or General type instead. Working with the Assignable and General types are the same as with any other entity type:

/api/v1/Assignables

Nested entity

When two entities are connected (e.g. User Story belongs to a Project, or User Story has Entity State), they are connected by ID.
It means that if you want to create a new User Story in Project, you need to know Project ID:

POST /api/v1/UserStories/
Content-Type: application/json
 
{"Name":"New Story", "Project":{"ID":2}}

The same rule is applied when you update an entity. For example, changing User Story State to Done will require knowing ID of this Entity State:

POST /api/v1/UserStories/123
Content-Type: application/json
 
{"EntityState":{"ID":6}}

Collection

Collection represents a set of Entities of the same type. It can be a list of User Stories, Bugs, Tasks or any other objects.

<UserStories Next="/api/v1/UserStories/?take=25&amp;skip=25">
 <UserStory Id="196" Name="Set Due Date">
 <!-- ... -->
 </UserStory>
 <UserStory Id="192" Name="Make Task Important">
 <!-- ... -->
 </UserStory>
</UserStories>

To retrieve a collection of all Entities use format:

/api/v1/{Entities}/

For example, this request retrieves all Bugs:

/api/v1/Bugs/

🚧

One page of entities by default contains only 25 elements.
Learn more about that at Paging section.

Inner Collections

You can retrieve inner collections for entity. For example, User Story contains a collection of Bugs. In this case you can retrieve them:

/api/v1/UserStories/34256/Bugs

❗️

You cannot add item to an inner collection.

Let's say you want to add a new item to an inner collection of Bugs for User Story with ID #123. Since you cannot add a new Bug directly to the inner collection, you need to add it to just plain collection of Bugs instead and to connect this Comment to original User Story by ID.

POST /api/v1/Bugs
Content-Type: application/json
 
{"UserStory":{"Id":123}, "Name":"This is a new bug", "Project":{"Id":2}}

Sometimes the way of connection between entities can be via a base class. For example, Time or Comment can be connected not only with User Story, but also with Tasks, Bugs or other Entity Types.
For example, if we continue to work with User Story with ID #123 and this time we want to add a new Comment to it. Again we need to add it to the plain collection of Comments and to connect this Comment to original User Story by ID. But since Comments can be added to any General Entity, we'll put the User Story ID in the General ID field.

POST /api/v1/Comments
Content-Type: application/json
 
{"General":{"Id":123}, "Description":"This is a new comment"}

Updated over 5 years ago