Targetprocess

The Targetprocess Developer Hub

Welcome to the Targetprocess developer hub. Here you'll find comprehensive guides and documentation to help you start working with Targetprocess as quickly as possible and support you if you get stuck. Let's jump right in!

Docs

Authentication

To access REST Services you must be authenticated as an active Targetprocess user or as the System User. There is no anonymous access allowed. Requester accounts are not granted access to the API.

Targetprocess REST API client can use cookie, basic or token authentication modes.

HTTP 401 status code (401: Unauthorized) is returned if authentication is failed.

Token Authentication

Token authentication mode uses a custom security token provided with URL. Using the token, your REST client application will obtain the same projects and teams membership and security permissions that the user who is owner of the token has.

Two different types of tokens are available and supported now in Targetprocess:

Service tokens
Access tokens

Parameter name

&token=xxxxxxxxxxxxxx

&access_token=xxxxxxxxxxxxxx

Source from where to obtain

Query API endpoint:
GET /api/v1/Authentication

Targetprocess UI
My profile view > Access Tokens tab

Can be obtained by users by themselves

YES

YES

Administrator can obtain it for other user

YES
GET /api/v1/Authentication?login=mwhite

NO

System User can have it

YES
GET /api/v1/Authentication?login=System

NO

Password-independent

NO
Becomes expired when password of associated user is changed

YES

Multiple application-specific tokens per user are supported

NO

YES

Issue date and last use date are tracked and displayed

NO

YES

Can be deactivated

YES
Make associated user login inactive

YES

Personal Access Tokens set within user interface

Supported in Targetprocess v3.8.2+

In earlier versions only tokens generated by /api/v1/Authentication service can be used.

Obtain a token

The tokens can be added under Access Tokens tab in personal details. Administrators cannot add tokens for other users.

You can use them as long as you want. When the token is not needed anymore it can be deleted.

For security reason a new token is shown and can be copied only after its creation. You can delete old tokens you do not remember them. And you can generate new tokens whenever needed.

You can track tokens usage directly from the same tab.

Use token

The received token could be used with any REST service by adding access_token={token} request parameter to URI.

GET /api/v1/UserStories/?access_token=YWRtaW46QUFBMEEwQTAwMEFBQTBBMDBBMEEwQTBBMEEwMEFBMDA=

Tokens generated by /Authentication service

Obtain a token

To obtain a token, you must be logged in within Targetprocess. To get a security token, you need to query the Authentication REST service via URI below:

GET /api/v1/Authentication

And you will receive the token for yourself:

<Authentication Token="YWRtaW46OTRDRDg2Qzg1NjgzQUZDMzg3Qjg2QTVERTAxRTZEQzY="/>

The token is valid as long as a user does not change their login or password. If a user changes his login and/or password then the new token is generated for him automatically.

The token for an active user is always active as well.

Authentication service supports both XML and JSON formats.

Use token

The received token could be used with any REST service by adding token={token} request parameter to URI.

GET /api/v1/UserStories/?token=YWRtaW46QUFBMEEwQTAwMEFBQTBBMDBBMEEwQTBBMEEwMEFBMDA=

Get Token for other users and System User

Administrators in Targetprocess can also obtain a token for other users. Pass their login name in parameter:

GET /api/v1/Authentication?login=mwhite

Token for System user is obtained the same way:

GET /api/v1/Authentication?login=System

This user has the same permissions in the account like any Administrator user has. With this token any data modifications can be performed.

Cookie Authentication

If you are logged in to a Targetprocess user account, then your web browser remembers your user login within cookies. When you try to reach the /api/v1/UserStories/ resource using the address bar of your browser, a GET request to REST API is sent and your cookie is used for authentication.

The same thing happens by default if you use REST API services from Mashups code. The cookie of the logged in Targetprocess user is used for authentication.

It is possible to use cookies from the web browser when you post REST API requests with a web browser plugin. For example, in the Chrome web browser there is plugin named Advanced REST Client. To obtain a cookie, toggle on 'Use XHR' mode in REST client settings. Additionally, the ARC cookie exchange plugin should be installed.

Basic Authentication

To use Basic Authentication, you need to send an Authorization: Basic header with every request. For example, if you want to be authenticated as admin:admin (login:password), you should send the following request:

GET /api/v1/UserStories/ HTTP/1.1
Authorization: Basic YWRtaW46YWRtaW4=

YWRtaW46YWRtaW4= key is a Base64 encoded login and password values for admin:admin which are default credentials for any new Targetprocess account owner.

You can generate such a key online.

When you encode a login:password pair, please make sure you don't have any extra spaces or carriage return / line break symbols at the beginning or end of the copy-pasted line.

DO NOT use Basic Authentication if the communication channel is not secured via HTTPS, since transmitted credentials are encoded with Base64, not encrypted or hashed.

Using cURL tool you don't need to encode the login and password for Basic authentication, cURL does it for you automatically.

curl --user login:password /api/v1/userstories/

Also you can use a special function in your programming language.

For example, in .NET / C# it will look like that:

var webClient = new WebClient();
webClient.Credentials = new NetworkCredential("admin", "admin");

To consume the REST service from Ruby, you may use HTTParty gem.

class UserStoryResource
  include HTTParty
  base_uri 'testaccount.tpondemand.com'
  format :xml
  def initialize(u, p)
    @auth = {:username => u, :password => p}
  end
  def all_stories(options={})
    options.merge!({:basic_auth => @auth})
    self.class.get("/api/v1/UserStories/", options)
  end
end
...
storyResource = UserStoryResource.new('admin', 'admin')
stories = storyResource.all_stories

Basic Authentication mode is supported for System User when login form is enabled. When login form is disabled in Single Sign-On settings then this type of authentication becomes blocked. Use token-based authentication instead.

Retrieve logged user details using API

After successful authentication, you can I get details about logged user ID and role. Query LoggedUser resource by the following path:

/api/v1/users/LoggedUser/

It will give you details about Logged User.

<User ResourceType="User" Id="334">
  <Kind>User</Kind>
  <FirstName>Teddy</FirstName>
  <LastName>Bear</LastName>
  <Email>xxx@xxx.com</Email>
  <Login>xxx</Login>
  <CreateDate>2006-10-02T16:19:42</CreateDate>
  <ModifyDate>2016-11-17T00:01:16</ModifyDate>
  <DeleteDate nil="true"/>
  <IsActive>true</IsActive>
  <IsAdministrator>true</IsAdministrator>
  <LastLoginDate>2016-11-17T00:00:00</LastLoginDate>
  <WeeklyAvailableHours>20.0000</WeeklyAvailableHours>
  <CurrentAllocation>100</CurrentAllocation>
  <CurrentAvailableHours>0.0000</CurrentAvailableHours>
  <AvailableFrom nil="true"/>
  <AvailableFutureAllocation>0</AvailableFutureAllocation>
  <AvailableFutureHours>0.0000</AvailableFutureHours>
  <IsObserver>false</IsObserver>
  <IsContributor nil="true"/>
  <Locale>en</Locale>
  <Skills>ui</Skills>
  <ActiveDirectoryName>TP\falcon</ActiveDirectoryName>
  <Role ResourceType="Role" Id="8" Name="Head"/>
  <CustomFields>
    <Field Type="Text">
      <Name>Skill Set</Name>
      <Value nil="true"/>
    </Field>
  </CustomFields>
</User>

Troubleshooting

Use token in Excel integration

Q: I have a web query in an Excel file that pulls data from Targetprocess. How can I save my password into the query string — so I don't have to log in three times when I open up the file to update my data?

A: Please create Access Token value using personal details tab in Targetprocess:

And then append &access_token=token_value to your Excel API requests.

Find more details on Integration between Excel and Targetprocess.

Non Authorized error for System User

Q: I obtained a token for my System User. But when I try to use it, I receive a 401 Not Authorized response. How to proceed?

A: In order to establish any integrations where System User credentials are used you must set it's password. It seems you haven't set a password for your System User yet. Please set it in Targetprocess in Settings page → System Settings → General Settings → System User Credentials panel and save your changes.

Non Authorized error for on-site installations

Q: I am trying to use the Token value in my query string, but I am still getting a 401 Not Authorized response. I have an onsite installation. Any ideas?

A: That can probably happen because of Authentication settings in IIS for your local web site. Some of our customers enable Windows Authentication mode for their Targetprocess applications. In this mode Windows Active Directory records are used to authenticate users. In this case for REST client applications you should do the following:

  • For the application root directory and /api/ inner directory please turn on Anonymous Authentication explicitly
  • Use basic or token-based client authentication

Otherwise, you have to provide an NTLM authentication instead of basic one.

Authentication


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.