Set Fields and Properties

In this article we describe how to set values of fields in REST API v1 Create and Update calls. Same data format is used in these calls. When ID value is specified in the URL or in data payload, then the system tries to update existing entity. When ID is not specified then the system tries to create a new entity.

In all the following examples we'll use a URL for updating a single User Story with ID #1234.

Set basic fields and properties

In order to pass text (string) value, put it into quotes in JSON object.

POST /api/v1/UserStories/1234
Content-Type: application/json
 
{
  "Name":"New User Story",
}

Escape double quotes in payloads when you post data to text fields within Targetprocess API. Replace " with \".

Set Rich Text Fields

Built-in Description field and Rich Text custom fields contain text with special formatting. Default format is HTML. Markdown formatting can be activated as system setting.

Set links to objects and entities

In order to pass reference to an object already registered in Targetprocess - such as Project, Entity State, Business Value, Severity etc., pass its numeric ID. Do not pass name or other properties of the related object.

POST /api/v1/UserStories/1234
Content-Type: application/json
 
{
  "Project":{"Id":2},
  "EntityState":{"Id":12}
}

Set Assignments

Post Role and User references to Assignments collection.

POST /api/v1/UserStories/1234
Content-Type: application/json

{
  "Assignments":{"Items": [
    {"GeneralUser":{"Id":1},"Role":{"Id":13}}
  ]}
}

// a default user Jane Smith (ID #1) is assigned to a Request with the Role Support Person (ID #4)
// a default user John Black (ID #8) is assigned to a Request with the Role Top Manager (ID #8)

POST /api/v1/Requests/1234
Content-Type: application/json

{
	"Assignments": {
		"Items": [
			{"GeneralUser": {"Id": 1}, "Role": {"Id": 4}},
			{"GeneralUser": {"Id": 8}, "Role": {"Id": 8}} 
		]
	}
}

Set Team Assignments

Post Team reference to AssignedTeams collection.

POST /api/v1/Features/123
Content-Type: application/json

{
  "AssignedTeams":{"Items": [
    {"Team":{"Id":56}}
  ]}
}

POST /api/v1/Features/123
Content-Type: application/json

{
  "AssignedTeams":{"Items": [
    {"Team":{"Id":56}},
    {"Team":{"Id":78}}
  ]}
}

Set Effort

Post Effort values and Role references to RoleEfforts collection. Total Effort is calculated by Targetprocess automatically.

POST /api/v1/UserStories/1234
Content-Type: application/json

{
 "RoleEfforts": {
   "Items": [
     {
       "Role": {"Id": 1},
       "Effort": 8
     }
   ]
 } 
}

POST /api/v1/UserStories/1234
Content-Type: application/json

{
 "RoleEfforts": {
   "Items": [
     {"Role": {"Id": 1}, "Effort": 8},
     {"Role": {"Id": 9}, "Effort": 5}
   ]
 } 
}

Set values of Custom Fields

Set Text and Number values:

POST /api/v1/UserStories/1234
Content-Type: application/json

{
  "CustomFields": [
    {
     "Name": "MyTextFieldName",
     "Value": "MyTextFieldValue"
    }, 
    {
     "Name": "MyNumberFieldName", 
     "Value": 1
    }
  ]
}

POST /api/v1/UserStories/1234
Content-Type: application/xml

<UserStory> 
    <CustomFields> 
     <Field>  
     <Name>MyTextFieldName</Name> 
     <Value>MyTextFieldValue</Value>  
     </Field>
     <Field>
     <Name>MyNumberFieldName</Name> 
     <Value>1</Value>  
     </Field>       
    </CustomFields>
</UserStory>

Set Targetprocess Entity value:

POST /api/v1/UserStories/1234
Content-Type: application/json

{
  "CustomFields": [
    {
      "Name": "Related Release",
      "Value": {
        "Id": 21229,
        "Kind":"Release"
      }
    }
  ]
}

Set Tags


{ "Tags":"test,hi" }	replace existing tags with these two
{ "TagObjects": [ {"Name":"one"}, {"Name":"new"} ] }	create two new tags and add them to the existing tags. if at least one tag already exists, it fails
{ "TagObjects": [ {"Id":59}, {"Id":77} ] }	find tags by ID and add them to the existing tags. if at least one tag doesn't exist, it fails.