Web Service API Guide Version 2

Avatar
Clarizen
Follow

Web Service API Guide Version 2

What's inside:

GETTING STARTED

Clarizen provides programmatic access to your organizational information using simple and powerful application programming interface - Clarizen Web Services API.

Using Clarizen Web Services you are able to develop various types of applications, such as:

  • Custom applications: create custom applications to gain additional benefits for your organization using business data located in the Clarizen repository. Provide your employees with specific and familiar User Interface for specific organizational processes
  • Integration with Desktop tools: create integration with desktop authoring tools to bring task management closer to the employee's desktop
  • Integration with legacy systems: create integration with your internal data management systems to exchange relevant data and perform on the fly integration

Introducing CLARIZEN Web Services

Web Service API access is enabled for all Enterprise organizations and does not require a special key to access the API.

Certified partners who develop applications that need to work for Professional edition organizations as wel,l can request a partner ID to access the API.

Please contact us for more information.

This section provides a quick introduction to the Web services API:

  • Supported Editions
  • Standard Compliance
  • Development Platforms
  • API Support Policy

Supported Editions

To use Web Services API, your organization must use Enterprise Edition. If you are already a customer of Clarizen and do not have this edition, please, contact your sales representative.

Clarizen's business and development partners can use the Developer edition. The Developer edition provides access to all functions available in the Enterprise edition.

Standard Compliance

The API is implemented in compliance with the following specifications:

Standard Name Website
Simple Access Object Protocol (SAOP) 1.1 http://www.w3.org/TR/2000/NOTE-SOAP-20000508
Web Service Description Language (WSDL) 1.1 http://www.w3.org/TR/2001/NOTE-wsdl-20010315
WS-I Basic Profile 1.1 http://www.w3-i.org/Profiles/BasicProfile-1.1-2004-08-24.html

Development Platforms

Clarizen Web Services API supports SOAP development environments including, but not limited to .NET 2.0 and Apache Axis. In this document we mainly provide examples in C# (.NET), some of the examples are provided for Java as well.

Note:

If you work with .NET environment, you can use .NET 2003 version and up.

API Support Policy

We recommend that you use the latest version of Clarizen Web services WSDL to benefit from richer features. See “ How to Obtain Web Services WSDL ” and “ Import WSDL File into Development Platform ” under the “ Quick Start ” chapter to learn how to update the WSDL file once Clarizen releases a new version.

Quick Start

In this section you will find details on how to use Microsoft .NET or Java to build an application that uses Clarizen Web services and how to run the sample application provided by Clarizen ( https://api.clarizen.com/v2.0/ClarizenClient.zip ).

To make your experience with using Web Services smooth and efficient, we recommend that you read through the rest of this document before attempting to use the API.

How to Obtain the Web Service WSDL

In order to access the Clarizen Web Service you must first import the Clarizen WSDL into your development environment.

The WSDL is an XML document supported by most development tools which describes the messages and operations supported by a web service.

The current version of the WSDL is located at https://api.clarizen.com/v2.0/Clarizen.svc .

Import WSDL File into Development Platform

Import the appropriate file for visual studio or Java based on the instructions below

Visual Studio

To access the Clarizen web services from .NET you need to import the Clarizen WSDL into visual studio.
This operation generates proxy classes that you can reference in your client code to access the services.

Important:

To import the WSDL you must first have a Visual Studio project opened.

To import the WSDL follow these steps:
  1. In the Project menu, select  “Add Service Reference”
  2. Click “Advanced”, and select “Add Web Reference”
  3. In the URL text box enter the Clarizen web services URL: https://api.clarizen.com/v2.0/Clarizen.svc and click “Go”
  4. In the web reference name text box enter “ClarizenSvc” and click Add Reference
  5. Visual Studio will generate the proxy classes and add them to your project

Java (Apache Axis2)

This section shows how to import the Clarizen WSDL using the Apache Axis2 WSDL2Java tool.
WSDL2Java will generate java proxy classes that you can use in your code to access the Clarizen web service.

To run the WSDL2Java tool, your java classpath must be set correctly. The following command line assumes you are running the tool from the Apache Axis 2 bin directory:

WSDL2Java -uri https://api.clarizen.com/v2.0/Clarizen.svc -d adb -s -uw -f

The above command line will generate a set of Java source files that can be compiled and used in your client code.

Sample Code

The following sample code provides a basic template you can use when creating a client that accesses the Clarizen web service.

C# Sample Code

static void Main(string[] args)

{

 //Create a proxy to the Clarizen Web Service

 clarizenClient = new Clarizen();

 clarizenClient.Timeout = 60 * 1000;

 //Enhance performance by compressing traffic

 clarizenClient.EnableDecompression = true;

 //Call the Login method

 LoginResult lr = clarizenClient.Login(userName, password, null);

 //Use the web service

 …

 …

 //Make sure to Logout after you have finished using the web service

 clarizenClient.Logout();

}

 

Java Sample Code

public  static  void  main(String[] args)  throws  Exception {

 //Create a proxy to the Clarizen Web Service
 ClarizenStub clz = new ClarizenStub();

 org.apache.axis2.client.Options options =  clz._getServiceClient().getOptions();

 // Time out after a minute
 options.setTimeOutInMilliSeconds(60000);

 //Compress responses
 options.setProperty(org.apache.axis2.transport.http.HTTPConstants.MC_ACCEPT_GZIP, true);

 LoginOptions loginOptions = new  LoginOptions();

 //Change to a name describing your application
 loginOptions.setApplicationId("Java test client");

 //Contact the login server to get the URL of your datacenter
 GetServerDefinitionResult srvDef = clz.getServerDefinition("user",

  "password", loginOptions, null);

 //Change the SOAP client endpoint to use the new URL
 clz._getServiceClient().getOptions().setTo(neworg.apache.axis2.addressing.EndpointReference(srvDef.getServerLocation()));

 //Call the Login method
 LoginResult loginResult =  clz.login("user", "password", loginOptions);

 //Create a header that will hold the Session ID returned fron the login operation
 SessionHeader sessionHeader = new SessionHeader();

 sessionHeader.setID(loginResult.getSessionId());

 Session session = new Session();

 session.setSession(sessionHeader);

 //Add the Session ID header to the proxy so the header will
 ArrayOfResult results = clz.execute(.., null, null, session);

}

 

PHP Sample Code

?php

function displayErrors(stdClass $result)

{

$serverErrorObj = $result->ExecuteResult->Result->Error;

if($serverErrorObj)

{

echo '<ul>';

echo '<li>ErrorCode : '.$serverErrorObj->ErrorCode.'</li>';

echo '<li>Message : '.$serverErrorObj->Message.'</li>';

echo '<li>ReferenceId : '.$serverErrorObj->ReferenceId.'</li>';

echo '</ul>';

return true;

}

return false;

}

//LOGIN PROCCESS

$soapUrl = ' https://api.clarizen.com/v2.0/Clarizen.svc?WSDL ';

$soapApiUrl = ' http://clarizen.com/api ';

$soapConfig = array('exceptions' => 1);

$request = array();

$params = array(

'userName'           => 'username',

'password'           => 'password'

);

try{

$client = new SoapClient($soapUrl, $soapConfig);

 

//Contact the login server to get the URL of your data center

$srvdef = $client->GetServerDefinition($params);

//Change the SOAP client endpoint to use the new URL

$client->__setLocation($srvdef->GetServerDefinitionResult->ServerLocation);

$response = $client->Login($params);

$sessionId = $response->LoginResult->SessionId;

$userId = $response->LoginResult->UserId;

$header = new SoapHeader($soapApiUrl, 'Session', array("ID"=>$sessionId));

$client->__setSoapHeaders($header);

$request[] = ... //Create additional request to the API

$result = $client->Execute(array("request"=>$request));

if($result)

{

if (!displayErrors($result))

var_dump($result);

}

}

catch(SoapFault $e){

var_dump($result);

var_dump($e->getMessage());

}

Object Basics

Clarizen Data Model is represented as a set of entity types.
Each entity type represents a specific type of data.
Clarizen entity types correspond to a database table that keeps your organization data.

For example, one of the central entity types in Clarizen is “Work Items”. “Work Items” is an entity type that keeps data on Projects, Milestones, and Tasks that construct Projects you manage in the Clarizen application.

The term “entity” in this document is used to describe particular occurrence of a specific object, for example, specific project “Release V2.0” or task “Check the book”.
Each “Entity” or “Object” corresponds to a row in a database table.

Read more about Clarizen entity types and entities in the “ Data Model ” chapter.

Most of the objects accessible through the API are Read-Write objects. There are cases when such objects are Read-Only by definition, such cases will be specifically indicated in the document.

Note:

Access to specific entity types through API is controlled by the authorization rights of the user that runs the application.

Primitive Field Types

Note:

You can use all field names of the entity types directly as given in this document.

Web Services API uses the following primitive field types:

Name
Description
Integer
Integer fields contain numerical data without the fractional portion after the decimal point.
The Integer field is 32 bits long and can contain signed data in the range of: −2,147,483,648 to +2,147,483,647.
Examples of such fields are SequenceOrder, Priority and others.
Long
Long fields contain numerical data without the fractional portion after the decimal point.
The Long field is 64 bits long and can contain signed data in the range of: −9,223,372,036,854,775,808 to +9,223,372,036,854,775,807.
Examples of such fields are FileSize, TotalSpace, UsedSpace (used in the storage description) and others.
Double
Double fields contain numerical data of type double with a fractional portion after the decimal point.
Examples of such fields are ExpectedProgress, PercentCompleted, ImpactWeight and others.

Specific restriction may be applied to the Double data:
  • Scale – maximum number of digits to the right of the decimal point.
  • Precision – total number of digits to the right and left of the decimal point.
Date
Date fields contain a Date value. Unlike the DateTime field, the Date field does not contain the time portion of the value.

Since the time portion of the date is irrelevant for the Date type, the Date value is always set to midnight.
DateTime
DateTime fields contain both date and time (timestamps) values with a precision of a second.
Examples of such fields are CreatedOn and ModifiedOn that appear in many objects.

DateTime values are kept in the database after they are converted to the Coordinated Universal Format (UTC).
In your client application you need to translate your local time to the UTC format.
There are two special DateTime fields that undergo additional special treatment:
  • StartDate – is always set to 08:00 AM to represent that work should start at the beginning of the work day
  • DueDate – is always set to start of the working day plus working day durationto represent that work should end at the end of the work day
In your client application you do not need to do anything special to support correctness of the values in these fields.
Boolean
Boolean type fields can have one of two possible values: True or False.
Examples of such fields are BelongToCriticalPath or PercentCompleteManuallySet and others.
String
String type fields contain character strings (text).
The maximum size of the string is restricted for specific fields and generally depends on the specific requirements applied in specific case, but cannot be more than 4000 B.
Examples of such fields are Name, Description and others.
Text
Text type fields contain character strings (text).
The maximum size of the string is not restricted as far as programming, the only restriction is that applied by Oracle regarding the maximum size of the CLOB column type.
Examples of such fields are Recommendation, Comment and others.

CLARIZEN Specific Field types

Web Services API introduces the following field types specific to Clarizen :

Name
Description
Entity “ Entity ” type is used to uniquely identify a specific entity.
The Entity type field consists of:
  • Entity type designation
  • Identifier – a string that ensures uniqueness of the entity in the entity type class
This field type is also used to represent a reference to another entity.
For example, the “Comment” Entity Type, has a field called “AttachedTo” which is a reference to the item that the comment was made on.
See the sample code below on how to work with the Entity field.
Duration
Duration field type is used mainly for fields that represent a time period or duration on the work item.
An example of such a field is the Duration field that can be found in all types of work items: projects, milestones and tasks.

The Duration field consists of three (3) sub-fields:
  • Value – Contains the time period
  • Unit – Clarizen supports the following unit types for duration: Minutes, Hours, Days, Weeks and Months.
  • Duration Type – Optional enumeration representing the corresponding time period specifics relatively to working and non-working days. The following options are available:
    • Default – time period contains only working days
    • Consecutive – time period contains all consecutive days
    • OverrideStart – time period can start on a non-working day
    • OverrideEnd – time period can end on a non-working day
    • OverrideBoth – time period can start and end on non-working days
See the sample code below on how to work with the Duration field.

Data Types Used in the API Calls

This section describes special Web Services runtime data types that are used in the API requests.

Entity

An entity in Clarizen is represented in Web Services using the Entity class.
The Entity class is a representation of a Clarizen entity using a generic collection of "field value" pairs (represented as a FieldValue object) where each name represents the name of a field belonging to that Entity.

See the description of RetrieveMessage\ RetrieveMultipleMessage for sample code of how to retrieve a task with a known Id.

static void RetrieveTask(string taskId)

{

 //Create the retrieve message

 RetrieveMessage retrieveMsg = new RetrieveMessage();

 retrieveMsg.Id = new EntityId();

 retrieveMsg.Id.TypeName = "Task";

 retrieveMsg.Id.Value = taskId;

 //Retrieve only the fields you need.
 retrieveMsg.Fields = new string[] {
  "Name",
  "StartDate"
 };

 BaseMessage[] messages = new BaseMessage[] {
  retrieveMsg
 };

 //Send the retrieve message to the server and cast the result to correct type
 RetrieveResult result = (RetrieveResult) client.Execute(messages)[0];

 //Always check the result status
 if (result.Success)

 {

  Entity task = result.Entity;

  //Now you can access the specific fields that were retrieved
  string taskName = (string) task.Values[0].Value;

  DateTime startDate = (DateTime) task.Values[1].Value;

 }

}

 

Using External IDs & References

Entity Identifier

The Entity identifier is an external identifier that provides a means to designate and reference an object.

The Field ID is a String of 40 characters long. It is implemented using a Primary Key database mechanism.

When creating an entity you can either let the system create an Entity Id for you or set it yourself.
If not set specifically during entity creation by the application, the field ID will be automatically populated with a GUID value to keep uniqueness of the field value.

Use external identifiers in various scenarios where you need to control the entity identification at the stage of entity creation.
For example:

  • Create and link two objects. Define the entities' external IDs during their creation and then use these IDs at the consequent stage of link (reference) creation.
Note:

External identifiers can be used by your organization to maintain single meaningful format of entity designation.

Working with References

The term Reference is used to define a reference to any existing entity in Clarizen.

Following are the examples of the references mechanism:

  • Build relations (links) with various application’s between two different entities, for example:
    • Documents attached to the task
    • Milestone that impacts completeness of other milestones
    • User working as a resource on a specific task
    • Others
  • Reference specific entities in the same or a different entity type, for example:
    • Reference pick up values
    • Discussion around specific work item

See the description of UpdateMessage for sample code of how to update a reference between a Task and its Manager.

The following example shows how to create two (2) tasks making one of them the parent of the 2 nd class by creating a link between them:

//Create an entity that represents a task
Entity parentTask = new Entity();

parentTask.Id = new EntityId();

parentTask.Id.TypeName = "Task";

parentTask.Id.Value = Guid.NewGuid().ToString();

FieldValue parentName = new FieldValue();

parentName.FieldName = "Name";

parentName.Value = "Parent Task";

parentTask.Values = new FieldValue[] {
 parentName
};

//Create an entity that represent a child task
Entity childTask = new Entity();

childTask.Id = new EntityId();

childTask.Id.TypeName = "Task";

childTask.Id.Value = Guid.NewGuid().ToString();

FieldValue childName = new FieldValue();

childName.FieldName = "Name";

childName.Value = "Child Task";

childTask.Values = new FieldValue[] {
 childName
};

//Create an entity that represents the link between the parent and the child task
Entity link = new Entity();

link.Id = new EntityId();

link.Id.TypeName = "WorkItemHierarchyLink";

//Create a field that references the parent task Id
FieldValue parentRef = new FieldValue();

parentRef.FieldName = "Parent";

parentRef.Value = parentTask.Id;

//Create a field that references the child task Id
FieldValue childRef = new FieldValue();

childRef.FieldName = "Child";

childRef.Value = childTask.Id;

link.Values = new FieldValue[] {
 parentRef,
 childRef
};

//Now create 3 CreateMessage objects that perform the creation of the tasks
//and the link between them
CreateMessage msg1 = new CreateMessage();

msg1.Entity = parentTask;

CreateMessage msg2 = new CreateMessage();

msg2.Entity = childTask;

CreateMessage msg3 = new CreateMessage();

msg3.Entity = link;

Result[] results = client.Execute(new BaseMessage[] {
 msg1,
 msg2,
 msg3
});

//checks all requests succeeded
…

 

Usage of External Identifiers in the Standard Clarizen Operations

Note:

As a rule external identifiers are required in operations that deal with specific entity / entities.

The following table shows examples of External Identifier requirements in the selected Clarizen operations:

Operation
ID Required
ID Returned on Response
Add No Yes
Update Yes No
Delete Yes No
Retrieve Yes Yes
Lifecycle Yes No
Search Yes / No Yes

API Calls Basics

Using API calls you can perform specific operations applied to the Clarizen entities and metadata , you can:

  • Add, update, or delete entities that belong to different entity types
  • Login into the system
  • Query entities from different entity types
  • Retrieve administrative information
  • Perform other activities in the system

Synchronous Execution of the API

Execution of the API requests are synchronous.
API request is submitted by the client application to Clarizen's Web Service, Clarizen processes the request and returns a relevant response.
Client application should wait for a response on the submitted request. Asynchronous requests are not supported .

Auto Commit Policy

Every request that is submitted by the client application is automatically committed.
Each operations, such as Create, Update and Delete, are treated as a separate transaction.
Client application does not need to send explicit Commit statements.

It is recommended that client application avoid situations where several operations should be handled as one transactional package.
If impossible, such situations should be handled by the client application specifically.
For example, if there are two consequential operations that should both be performed successfully, and the second operation failed, the application must “roll back” to the results of the first operation.

iClarizen Interface

The iClarizen interface contains five (5) methods:

  • Execute (BaseMessage)
  • Login (Username, Password, LoginOptions)
  • Logout
  • Metadata (MetadataMessage)
  • Query (QueryExpression)
Execute

The Execute is used to perform the majority of operations over Clarizen entities and includes: Create, Delete, Update, Retrieve, Upload, Download and more.

See the Working with References section for some sample code using the Execute method.

Login and Logout

The Login is used to login into the system with user credentials and additional options such as partnerId and applicationId.

Logout closes the user’s session.

static void Main(string[] args)

{

 //Create a proxy to the Clarizen Web Service

 clarizenClient = new Clarizen();

 clarizenClient.Timeout = 60 * 1000;

 //Enhance performance by compressing traffic

 clarizenClient.EnableDecompression = true;

 //Call the Login method

 LoginResult lr = clarizenClient.Login(userName, password, null);

 //Use the web service

 …

 …

 //Make sure to Logout after you have finished using the web service

 clarizenClient.Logout();

}

 

Metadata

Metadata is an interface that allows access to various administrative data and information regarding Clarizen's entity types that could be essential at runtime.

The following example shows how to retrieve the metadata description of a Task entity type:

DescribeEntitiesMessage msg = new DescribeEntitiesMessage();

msg.TypeNames = new string[] {
 "Task"
};

DescribeEntitiesResult result = client.Metadata(msg);

EntityDescription description = result.EntityDescriptions[0];

// description.Fields contains the fields that are part of the Task entity type

…

 

Query

Query is used to access pre-saved queries or construct new queries for Clarizen entities.

The following example shows how to use the build in MyWorkItemsQuery to query for active tasks you are currently managing.

MyWorkItemsQuery query = new MyWorkItemsQuery
{
   ItemsType = WorkItemType.Task,
   ItemsTypeSpecified = true,
   ItemsFilter = WorkItemFilter.IAmAManager,
   ItemsFilterSpecified = true,
   ItemsState = WorkItemState.Active,
   ItemsStateSpecified = true,
   Fields = new string[]
   {
     "Name",
     "Importance",
     "DueDate",
     "StartDate",
     "PercentCompleted"
   }
};
Result[] results = client.Execute(new BaseMessage[] { query });

 

Error Handling

Web Services API returns error data that can help you designate and identify erroneous situations created while managing Web Services requests.

There are two kinds of errors that may occur during a web service request:

  • Fault — An exception that causes the entire operation to fail. Usually in this case the request process does not even start. An example of such an exception is a session timeout
  • Error — A failure to process one or more request(s) sent to the web service due to missing or invalid data. For example, trying to set a negative %completed value for a task will result in such an error.

In most programming languages when a fault is returned, the proxy generated on the client will throw an exception.

Handling Session Timeout

The following example shows one way to handle session timeouts in your code:

try

{

 //Call web service methods
} catch (System.Web.Services.Protocols.SoapException e)

{

 if (e.Code.Name == "SessionTimeout")

 {

  //Here you can either re-login and retry the last operation
  //or show a message to the user.
 } else

  throw;

}

 

Handling Errors during API Requests Execution

Every operation performed against the Clarizen web service return a status representing whether the operation succeeded or failed.
The Result Object returned from each call has the following properties to help you identify whether the operation has succeeded or failed as well as failure details.
The result contains the following properties:

  • Success — A boolean value indicating whether the operation succeeded or failed
  • Error — An object of type Error that provides information on why the operation failed

The Error object contains the following properties:

  • ErrorCode — A value from the ErrorCode enumeration that indicates the type of error that occurred
  • Message — A displayable string that describes the error and how to fix it
  • ReferenceId — A string containing a unique identifier representing this error. Always provide this Id when contacting support so we can easily track the error

The following sample code shows how to check for errors when accessing the Clarizen web service:

static void HandleError()

{

 ...

 RetrieveResult result = (RetrieveResult) client.Execute(messages)[0];

 If(result.Success)

 {

  //The operation succeeded – continue as usual
 } else

 {

  if (result.Error.ErrorCode == ErrorCode.EntityNotFound)

  {

   Console.WriteLine("The entity does not exist");

  } else

   Console.WriteLine(result.Error.Message);

 }

}

 

Security

Web Services API leverages the latest industry security standards in order to ensure high-level security for your organizational data.
All Web service requests are controlled by the same security mechanisms as used in the Clarizen application as well as an additional identification procedure during the authentication phase:

  • Authentication
  • Authorization
  • Session management
  • Encryption

Authentication

See also API Keys Support

Authentication is a process of confirming identity of a specific person and / or process.
During the Login process the client application, written using Web Services, should provide the correct user credentials and API identification number:

User credentials are:

  • User Name
  • Password

Clarizen supports two (2) different login options:

  • Customers — Customers who want to use the API to access their data should purchase an Enterprise license.  In which case no special transmission is required during login
  • Partners — Partners are required to provide a Partner Id and an Application Id during login so they can be identified
    • Partner ID – Identification of a Clarizen partner that develops applications using Clarizen Web Services API that are supposed to be used by various Clarizen customers
    • Application ID – Identification of a specific partner application that can be used for licensing purposed. This Id must be registered with Clarizen
Important:

Please, contact your sales manager to get your “Partner ID” before you start using Clarizen Web Services.
Please, contact technical assistance to establish the “Application ID”, if relevant.

See also API Keys Support

Authorization

From Wikipedia: Authorization is the concept of allowing access to resources only to those permitted to use them.

All API calls generated through Clarizen Web Services undergo the same permission checking as applied in the Clarizen application.

Session Management

After a user was successfully authenticated, the system generates a random and unique identifier known as the Session ID.
This identifier is returned to the client as part of the Login return value and the client must pass this Session Id on subsequent requests (See the sample code for details on how to pass the session ID)

A session lifespan is controlled by:

  • Session Timeouts
  • Sessions Numbers Limit

Session Timeout

Similar to Clarizen's UI, the Web services sessions automatically times out after 60 minutes of inactivity, requiring a login to resume activity. However, if the client submits a request the inactivity time is reset.

Note:

For security reasons, we recommend that you close your session using the Logout operation as soon as you are done using the service.

If you explicitly logout of a session, and then attempt to utilize the same session, a SessionTimeout error code is returned.
Your code should be prepared to handle session timeouts by sending a re-login when a session timeout occurs.

If you need to eliminate open sessions for security reasons, you should call logout upon completion of an operation.

Session Number Limits

The number of concurrent sessions authenticated with the same user credentials is limited to two (2).

 

Web Services Governance

In order to optimize performance of the Clarizen application and database servers, Clarizen API engine provides several mechanisms to control consumption of the processes initiated by Web Services.
These mechanisms, monitor and control requests from the Web services to ensure that the user experience is not extensively impacted by the possible heavy processes and that the burden of the Web services is shared among all users.

Web Services Governance is made up of following areas:

  • Request batch limiting: The total number of requests that can be processed in one call to the web service is 100.
  • Request limiting: The total size of the requests sent in one call to the web service must not exceed 25 MB.
  • Call limiting: 1,000 API calls per paid license per day with a maximum of 1,000,000 calls per day.
  • Rate Limiting: Up to 25 requests per second
    Notes: 
    • A bulk request (multiple calls in a single request) is supported, however depending on its position in the queue, subsequent calls may not go through
    • Internal tools and apps, for example, SCIM-based user provisioning, DataLoader, and Doc Publisher are excluded from this quota
      For more information, see Mitigating the API Rate-Limit.

INTRODUCTION TO REFERENCE GUIDE

Please, see detailed reference guide for Clarizen Web Services API calls in the “Clarizen Web Services Reference Guide” document available in the Developer page of Clarizen Web site.

Data Model

This section contains description of the data elements and relationships between these elements within Clarizen

Clarizen data model has an object oriented nature.
At the logical level it is represented by a set of entity types (can also be referenced as Classes ) and their relationships.
At the physical level Clarizen uses the underlying database units, such as tables, indexes, constraints definitions, linking tables, partitioned tables or clusters.
Physical data model is derived from a logical data model.

Some of the Web Service APIs can be manipulated using the metadata notions.
Metadata is data regarding the data model, essentially a description of the logical & physical data model as well as derivation rules between logical & physical representations, such as:

  • Entity type name, description, type, attributes, database table, etc.
  • Collection of fields in specific entity type
  • Collection of possible relations between various entity types
  • Other information

In this section you will find definition for:

  • Classification of the entity types in use
  • Commonly used fields
  • Standard Clarizen objects

Entity Types Classification

An Entity Type or Class is a named collection of fields and the methods that fully describe specific object types and rules, according to which the object of this entity type behaves.

Different Entity Types can share and inherit the same fields, methods and rules of entity behavior.
This concept is reflected in the hierarchical relation between classes.

The hierarchical relationship between entity types / classes involves Subclass (child-classes) and Superclass (parent-classes) concepts.

Regular Entity Types

Regular Entity type is used to store regular objects, such as Projects, Task, Milestones and others.

Link Entity Types

Link Entity types are used to store relations between entities that belong to the same or to different entity types.
Clarizen allows:

  • One-to-One relationship.
  • One-to-Many relationships  - in one-to-many relationship one object can be linked to many other objects which in turn will be linked to this and only this object.
  • Many-to-Many relationships – in many-to-many relationship one object can be linked to many other objects and vice versa.

Link Entity Type always contain the following obligatory fields:

  • RelatedEntitiy1– reference to the first linked object
  • RelatedEntitiy2- reference to the second linked object

Links or relationships between entities can be directed (for example, parent – child relationship) or non-directed links.
Direction of specific type of relation is defined by its business logic and is described below in the relevant sections.

Pick up Tables

Pick up tables are similar to Regular entity types.
Pick up tables usually contain a limited set of fields and limited number of entities and are referenced from the other types of classes.

Other References between Entity Types

Clarizen's data model also supports references between objects that belong to the regular or link entity types.
These types of references are implemented using One-to-Many relationship model.

An example of such a reference is the CreatedBy field that appears in all of Clarizen's entity types. This field references the entity of a specific user in the User entity type.

References from the regular or link entity types to the pick up tables are implemented using the same mechanism.

Commonly Used Fields

Unique Entity Identifier

Name
Type
Description
SYSID String(40) Unique entity identifier given by the system to a specific entity.

Common Fields

The Following table presents fields that appear in all of Clarizen's Entity types:

Name
Type
Description
Entity Entity Entity identifier that uniquely designates the object. See “ Entity Identifier ” section for detailed description.
CreatedOn DateTime Date and time when specific entity was created
CreatedBy Entity Reference to the entity that keeps properties of the user that created the object
ModifiedOn DateTime Date and time when specific entity was last modified
ModifiedBy Entity Reference to the entity that keeps properties of the user that last modified the object.
Note:

In case specific entity was last modified by the system process or job this field will keep reference to the System user. For example, the job that performs scheduled calculation of the Task track status will change value of the TrackStatus field to “Off Track” in case the Task passed it’s DueDate.

Standard Fields

The following table presents fields that appear in the majority of Clarizen's entity types, such as Tasks, Projects, Milestones, Documents and others.

 
Type
Description
Name String (256) Name of the entity
Description String (512) Description of the entity
Note:

In the pickup tables Name uniquely represents specific value in the pickup table.

Lifecycle Fields

Lifecycle fields appear in the majority of Clarizen's entity types, such as Tasks, Projects, Milestones, Documents, Documents and others.

Lifecycle fields serve to trace progress of the corresponding entity through its lifecycle.
The following table represents  the Lifecycle fields:

Name
Type
Description
State Entity Represents the activity's lifecycle State.
For example, possible states of the Work Item objects can be Draft, Active, Cancelled, Completed, On Hold .
Value is a reference to State pickup table.
Phase Entity Represents the entity's lifecycle Phase.
For example, possible states of the Work Item objects can be Concept, Preliminary Design, Implementation, etc .
Value is a reference to Phase pickup table.

Standard Entity Types

Work Item

the Work Item entity type is a superclass currently used to represent three (3) different types of working items:

  • Project
  • Milestone
  • Task

Project, Milestone, and Task are subclasses of the Work Item superclass.  All three subclasses inherit fields defined at the level of the Work Item entity type.
Inherited (shared) fields reside in the Work Item class, while fields that differ between these entity types reside in the corresponding subclass.

While creating an actual object based on one of the work item types, you should use entity type name for Project, Milestone or Task respectively, to designate which entity type you are going to create.

See the description of CreateMessage for a sample code of how to create a Task.

Work Items of all types have the following set of frequently used fields:

  • UniqueEntityIdentifier
  • Common
  • Standard
  • Lifecycle

The following table represents specific fields of Work Item entity type tree:

Name
Type
Mandatory
Description
Name  
ü
 Inherited from Standard
ID     Inherited from UniqueEntityIdentifier. System generated.
Project Entity   Represents project to which work item belongs. Reference to the corresponding project entity.
       
Planning fields      
StartDate DateTime   Planned start date of the work item
DueDate DateTime   Planned end date of the work item
Duration Duration   Planned duration of the work item
ActualEffort TimeEffort   Actual effort that was already invested into work item
EstimatedEffort TimeEffort   Estimated effort that should be invested into the work item
RemainingEffort TimeEffort   Effort that still should be invested into the work item
ActualEndDate DateTime   Date when the work item was actually finished
TrackStatus Entity   Indicates track status of the work item : On Track, On Risk or Off Track . Reference to the Track Status pickup table
ExpectedProgress Double   Completeness progress expected for the current date
Importance Entity   Importance of the work item. Reference to the Importance pickup table
Priority Integer   Priority of the work item
       
Completing Percentage      
PercentCompleted Double   Percent of progress completeness correct for current date
       
Responsibility Fields      
Manager Entity   Functional manager of the work item. Reference to the corresponding user in the User entity type
       
Budget fields      
ActualCost Double   Actual cost invested to the work item
ActualCostManuallySet Boolean   True – indicates that actual cost was set manually rather than calculated from the “child” work items
PlannedBudget Double   Planned budget to be invested into the work item
PlannedBudgetManuallySet Boolean   True – indicates that planned budget was set manually rather than calculated from the “child” work items
PlannedRevenue Double   Income planned for the work item
ActualRevenue Double   Actual income received
Counter Fields      
ChildrenCount Integer   Number of work items that are direct children of this work item
ResourcesCount Integer   Number of resources assigned to this work item
AttachmentsCount Integer   Number of documents attached to this work item
PostsCount Integer   Number of Posts made on this work item
NotesCount Integer   Number of Notes made on this work item

The following table represents Project entity type specific fields:

Name
Type
Description
ProjectManager Entity Represents the user that is a project manager of specific project. Reference to the user entity type.
ProjectTarget String(512) Represents text that is used to describe target of the project
ProjectType Entity Represents type of the project. Reference to Project Type pickup table.
DirtyFlag Long Service field for internal needs. Used to represent that project requires specific type of recalculation.
Parent Entity Direct reference to the parent entity

The following table represents Task entity type specific fields:

Name
Type
Description
Type Entity Represents type of the project. Reference to Tasks Type pickup table.
Parent Entity Direct reference to the parent entity

The following table represents Milestone entity type specific fields:

Name
Type
Description
Type Entity Represents type of the project. Reference to Milestone Type pickup table.

Users

The User entity type represents users working with the system.

User has the following set of frequently used fields:

The following table represents the User entity type specific field tree:

Name
Type
Mandatory
Description
DisplayName String(256) ü Represents the user's display name used in various places of the application UI
UserName String(256) ü Represents the usee's login name. By default it is equal to the user’s email
FirstName String(256) ü Represents the user's first name
LastName String(256) ü Represents the user's last name
Email String(256) ü Represents the user's email address
OfficePhone String(256)   Represents the user's office phone number
OfficeFax String(256)   Represents the user's office fax number
MobilePhone String(256)   Represents the user's mobile phone number
BusinessAddress String(1024)   Represents the user's business address
LastLogin DateTime   Represents the date & time when the user last logged in into the application
AllowEmails Boolean   When True indicates that the user would like to receive emails from the system
CostRateperHour Double   The user's Cost rate per hour

Organizations

Organization entity type represents Organizations working with Clarizen.

Organization has the following set of frequently used fields:

The following table represents specific Organization entity type fields:

Name
Type
Mandatory
Description
Name   ü Inherited from Standard
Country Entity   Represents a country. Reference to the pickup table “Countries”.
CountryState Entity   Represents country state (relevant only for USA). Reference to the pickup table “Country States”.
IndustryType Entity   Represents the organization's industry type. Reference to the pickup table “Industry type”.
CurrencyType Entity   Represents the currency type used in the organization. Reference to the pickup table “Currency type”.
OrganizationLanguage Entity   Represents the language used at the organization level. Reference to the pickup table “NLSLanguage”.
ResourceRateperHour Double   Represents users' default rate per hour.
Note:

All fields of Organization have read-only access through API.

Customers

Customer entity represents customers working with specific Clarizen organization .

The Customers entity have the following set of frequently used fields:

The following table represents specific fields for the Customers entity type:

Name
Type
Mandatory
Description
Name   ü Inherited from Standard
Description     Inherited from Standard
ID     Inherited from UniqueEntityIdentifier. System generated.
BusinessAddress String(1024)   Customer Business address
BillingAddress String(1024)   Customer Billing Address

The following example shows how to get all of the customers in your organization: 

EntityQuery customersQuery = new EntityQuery
{
   TypeName = "Customer",
   Fields = new string[] {"Name"},// Retrieve only name of each customer
   Orders = new OrderBy[] {new OrderBy() {FieldName = "Name"} }// Order results by customer name
};

Result[] queryResults = client.Execute(new BaseMessage[] { customersQuery });
 

 

Contacts

Contact Person (API Name = ContactPerson) entity represents people that serve as contact points between an organization and a specific customer.

Contact Person entity has the following set of frequently used fields:

The following table represents specific Contacts entity type fields:

Name
Type
Mandatory
Description
Email String(256)   The contact person's Email address
OfficePhone String(256)   The contact person's office phone number
MobilePhone String(256)   The contact person's mobile phone number
FaxNumber String(256)   The contact person's fax number

The following example shows how to get all contacts for a specific customer:

string customerId = "210a7ced-a440-45cd-9a30-1ff251b2b1fd";
EntityQuery contactByCustomerQuery = new EntityQuery
{
   TypeName = "ContactPerson",
   Fields = new [] {"Name", "Email"}
};
Compare condition = new Compare
{
   LeftExpression = new FieldExpression {FieldName = "Customer"},
   Operator = Operator.Equal,
   RightExpression =
   new ConstantExpression {Value = new EntityId {TypeName = "Customer", Value = customerId}}
};
contactByCustomerQuery.Where = condition;
Result[] queryResults = client.Execute(new BaseMessage[] { contactByCustomerQuery });

 

All Issue Types

The All Issue Types entity type is a superclass currently used to represent four (4) different types of issues:

  • Issue
  • Bug
  • Risk
  • Enhancement Request

Issue, Bug, Risk and Enhancement Request are subclasses of the All Issue Types superclass.
All four subclasses inherit fields defined at the level of the All Issue Types entity type.
Inherited (shared) fields reside in the All Issue Types class, while fields that differ between these entity types reside in the corresponding subclass.

While creating an actual object of one of the issue types you should use entity type name of Issue, Bug, Risk or Enhancement Request (API name = EnhancementRequest) respectively to designate which entity type you are going to create.

The API name for the entity is Case .

Issues of all types have the following set of frequently used fields:

The following table represents specific fields of All Issue Type entity type:

Name
Type
Mandatory
Description
Title   ü Inherited from Standard ‘Name’ field
ID     Inherited from UniqueEntityIdentifier. System generated.
Description Text   Text of Description as shown to the user. Contains “rich” text characters
PlainText Text   Text of Description as stored in the database for purposes of searches
Severity Entity   Represents severity of the issue. Reference to “Severity” pickup table
Priority Integer   Represents priority of the issue
Mandatory Boolean   Checked if issue’s resolution is mandatory
Owner Entity   User that owns the issue. Reference to the Users entity
DueDate DateTime   Target date to provide solution
AssignedTo Entity   Who is currently assigned to the issue. Reference to the Users entity
AssignmentDate DateTime   Date when the current user was assigned to the issue, Read only field, set by the system
SubmittedBy Entity   Who submitted the case. Reference to the Users entity
SubmissionDate DateTime   Date of the case submission
EvaluatedBy Entity   Who evaluated the case. Reference to the Users entity
EvaluationDate DateTime   Date of the issue evaluation
OpenedBy Entity   Who opened the issue for resolution. Reference to the Users entity
OpeningDate DateTime   Date of opening the issue for resolution
ResolvedBy Entity   Who resolved an issue? Reference to the Users entity
ResolvedDate DateTime   Date when the case was resolved
ResolutionDetails String(2000)   Description of resolution
ClosedBy Entity   Who closed an issue? Reference to the Users entity
ClosureDate DateTime   Date of the issue closure
RejectedBy Entity   Who rejected an issue? Reference to the Users entity
RejectionDate DateTime   Date of the issue rejection
RejectDetails String(2000)   Description of reasons and other details to reject the case
ReopenedBy Entity   Who reopened the case? Reference to the Users entity
ReopeningDate DateTime   Date when the case was reopened
ReopenReasons String(2000)   Description of the reasons for reopening the case
DeferredBy Entity   Who deferred the case? Reference to the Users entity
DeferringDate DateTime   Date of the case deferring
DeferReasons String(2000)   Description of reasons to defer the issue
Comment String(2000)   Free Comments
PlannedFor Entity   When an issue is planned to be resolved. Reference to the Work Items entity.
ReportedbyCustomer Boolean   Reported by the customer
Category String(256)   Category of the issue
DuplicateTo String(256)   ID of the duplicate issue
Issue

No specific fields for the Issue entity type.

Bug

The following table represents Bug entity type specific fields:

Name
Type
Description
Regression Boolean Defines whether the bug is a regression from the previous versions.
ImpactArea String(2000) Description of the resolution impact area
FoundInBuild String(256) In which build it was found
IntegratedInBuild String(256) In which build interated a fix
ClosedInBuild String(256) In which build the bug was closed
ReopenedInBuild String(256) In which build reopened back for fix due to fix falure
Risk

The following table represents Risk entity type specific fields:

Name
Type
Description
PercentProbability Double Probability of occurrence.
Impact Integer Number from 1 to 5 representing the risk impact
TriggerDate DateTime Trigger Date of the incident
MitigationPlan String(2000) Description of the mitigation plan
ContingencyPlan String(2000) Description of the contingency plan
RiskRate Double Risk rating is measured by Impact * %Probability. Read only, Calculated.
Enhancement Request

The API name of the entity is EnhancementRequest.

No specific fields for the EnhancementRequest entity type.

The following example shows how to add / modify an issue of the Risk type:

// Create new Risk
public static void CreateRisk(string riskId)

{

 //Create an entity representing the new task
 Entity task = new Entity();

 risk.Id = new EntityId();

 risk.Id.TypeName = "Risk";

 risk.Id.Value = riskId;

 //Set risk title
 FieldValue titleField = new FieldValue();

 titleField.FieldName = "Title";

 titleField.Value = "My Risk";

 //Assign the fields to the risk
 risk.Values = new FieldValue[] {
  titleField
 };

 CreateMessage createRiskMessage = new CreateMessage();

 createRiskMessage.Entity = risk;

 //Send the CreateMessage to the server for execution
 client.Execute(new BaseMessage[] {
  createRiskMessage
 });

}

 

The following example shows how to get all issues of a specific type reported by you:

string myUserId = loginResult.UserId; //LoginResult is returned after login
EntityQuery query = new EntityQuery
{
   TypeName = "Case",
   Fields = new [] {"Title"}
};
//Change to Risk,Issue or Bug to get specific cases
Compare condition = new Compare
{
   LeftExpression = new FieldExpression {FieldName = "SubmittedBy"},
   Operator = Operator.Equal,
   RightExpression = new ConstantExpression
   {
     Value = new EntityId
     {
       TypeName = "User",
       Value = myUserId
     }
   }
};

query.Where = condition;
Result[] result = client.Execute(new BaseMessage[] { query });

 

Documents

Document entity type represents document object that can be attached to other entities in the system. Document itself can have several datasets attached.

The Document entity has the following set of frequently used fields:

The following table represents specific fields of Document entity type tree:

Name
Type
Description
DocumentType Entity Represents type of the document. Reference to the pickup table “Document Type”.

The following example shows how to upload a new document to Clarizen

public EntityId UploadFile(string filePath, string filename)
        {
            var content = File.ReadAllBytes(filePath);
            var createMessage = new CreateMessage
            {
                Entity = new Entity()
                {
                    Id = new EntityId { TypeName = "Document" },
                    Values = new[]
                    {
                        new FieldValue {FieldName = "Content", Value = content},
                        new FieldValue {FieldName = "Name", Value = filename}
                    }
                }
            };

            var results = _client.Execute(new BaseMessage[] { createMessage });
            var createResult = ((CreateResult)results[0]);

            return createResult.Id;
        }

public void LinkFileToWorkItem(EntityId documentId, string projectId)
        {
            var createMessage = new CreateMessage
            {
                Entity = new Entity
                {
                    Id = new EntityId { TypeName = "AttachmentLink" },
                    Values = new[]
                    {
                        new FieldValue {FieldName = "Document", Value = documentId},
                        new FieldValue{FieldName = "Entity", Value = new EntityId{TypeName = "Project", Value = projectId}}
                    }
                }
            };
            _client.Execute(new BaseMessage[] { createMessage });
        }
The following example shows how to download a document from Clarizen:
public void Download(string documentId)
        {
            var download = new DownloadMessage
            {
                DocumentId = new EntityId
                {
                    TypeName = "Document",
                    Value = documentId
                }
            };
            var downloadResult = (DownloadResult)_clarizen.Execute(new BaseMessage[] { download })[0];

            if (downloadResult.Success)
            {                
                var webRequest = WebRequest.Create(downloadResult.FileInformation.Url);

                using (var response = webRequest.GetResponse())
                using (var content = response.GetResponseStream())
                using (var reader = new StreamReader(content))
                {
                    var strContent = reader.ReadToEnd();
                }
            }

        }

 

Comments - Notes & Discussions

Comment entity type is a superclass for three (3) subclasses:

  • Note
  • Email
  • Discussion

Comment has the following set of frequently used fields:

The following table represents specific Document entity type fields:

Name
Type
Description
Subject   Inherited from Standard ‘Name’ field
Comment Text Comment Text as shown to the user. Contains “rich” text characters
PlainText Text Comment Text as stored in the database for purposes of searches
AttachedTo Entity Represents an entity on which a note or discussion is written. Reference to corresponding entity: Task, Document, other
Visibility Entity Represents whether a specific Note is Public or Private. Reference to the pickup table “Comment Type”.

Relations between Entity Types

All “Link” or “Relation” entity types have two (2) fields that reference two (2) objects creating a specific relationship:

Name
Type
Description
RelatedEntitiy1 Entity Represents the first related object.
RelatedEntitiy2 Entity Represents the second related object.

Basic “Link” type allows building bidirectional many-to-many links.
The direction of a specific relation type is defined by its business logic and is described below in the relevant sections.

Work Item Progress Impact

The Work Item Progress Impact represents a complex relationships between two work items:

  • Hierarchical
  • Progress impact
  • Shortcuts

These relations mainly represent business rules of the progress impact between two work items.

Hierarchical (contained) relation represents the structure of the work item tree. A child work item affects parent’s completion progress, start and due dates, status, budget and alert calculation.

Progress Impact (reflected) relation allows building relations that reflect impact on the completion progress, status, dates of the work items that do not have hierarchical relations.

Shortcut relation represents reference to a reflection of another work item, similar to a shortcut in Microsoft Windows File system. A shortcut has the same effect on its parent as if it was a “real” work item – it affects its completion progress, start & due dates, and status & alert calculation.

Parent item in this relation always plays the role of the impacted by the Child work item.

The following table represents specific fields of Work Item Progress Impact entity type:

Name
Type
Description
Parent Entity Represents a Work Item that plays the role of Parent in the relation, uses RelatedEntity1 placeholder
Child Entity Represents a Work Item that plays the role of Child in the relation, uses RelatedEntity2 placeholder
LinkType Entity Represents a specific type of link. Reference to pick up table “Contained Link type” that has two values “Contained” or “Reflected”
IsShortcut Boolean When False indicates relation between two “real” work items. When True indicates that the Child field represents a “shortcut” to the original work item.
SequenceOrder Integer Represents a sequence order of the child work item within all children of the same parent.
ImpactWeight Double Represents impact weight of the Child work item on the progress of the parent work item.

Dependency

Dependency entity type represents relations between work items of “Scheduling dependency” types.
This link is a many-to-many link that represents the following types of scheduling dependency:

  • Finish to Start
  • Finish to Finish
  • Start to Start
  • Start to Finish

The following table represents specific fields of Dependency entity type:

Name
Type
Description
WorkItem Entity Represents Work Item - successor in the dependency relation, uses RelatedEntity1 placeholder
DependsOn Entity Represents a Work Item - predecessor in the dependency relation, uses RelatedEntity2 placeholder
DependencyType Entity Represents type of scheduling dependency. Reference to pickup table Dependency Type.
Lag TimeEffort Positive vale of Lag field represents delay between two dependant work items, Negative value – leading overlap.

Human Resource

Human Resource entity type represents working relationships between Users and Work Items.
The Human Resource link is a many-to-many link that serves to build various types of work relations between users and work item, such as:

  • Resource that fulfills the work item
  • Reviewer that has view access to work item for review purposes

The following table represents specific fields of Human Resource entity type:

Name
Type
Description
WorkItem Entity Represents related Work Item, uses RelatedEntity1 placeholder
Resource Entity Represents related User that fulfills work for specific Work Item, uses RelatedEntity2 placeholder
ResourceRole Entity Represents role of the user in specific work item. Reference to entity type Role.
Units Double Represents invested percent of work of specific user. Default value = 100.00

Customer - Project Link

Customer – Project link represents the customers that were assigned to a specific project.

The API name of the entity type – CustomerLink.

The following table represents specific fields of the entity type:

Name
Type
Description
Project Entity Represents related project, uses RelatedEntity1 placeholder
Customer Entity Represents related customer, uses RelatedEntity2 placeholder
CostAllocation Double Represents percent of cost allocation per customer. 100% by default

Customer - Issues Link

Customer – Issues link represents the customers that submitted specific issue and/or the issue is committed for resolution to the customer.

The API name of the entity type – CustomerLink.

The following table represents specific fields of the entity type:

Name
Type
Description
Issue Entity Represents related issue, uses RelatedEntity1 placeholder
Customer Entity Represents related customer, uses RelatedEntity2 placeholder
Submitted Boolean Represents whether specific issue was submitted by a specific customer
Committed Boolean Defines whether the Resolution of the issue was committed to the customer
CommittedDate DateTime Target date of commitment

The following example shows how to get all issues of all types reported by the customer:

string customerId = "customerId";
            IssuesQuery query = new IssuesQuery
            {
                TypeName = "Case",
                Fields = new[] {"Title"}
            };
            Compare customersCondition = new Compare
            {
                LeftExpression = new EntityIdExpression(),
                Operator = Operator.Equal,
                RightExpression = new ConstantExpression
                {
                    Value = customerId
                }
            };

            query.CustomerCondition = customersCondition;
            Result[] results = _client.Execute(new BaseMessage[] { query });

 

Issue Related Work

Issue Related Work represents the work, in the terms of Projects, Milestones or Tasks, that should be fulfilled to resolve an issue.

The API name of the entity type – RelatedWork.

The following table represents specific fields of the entity type:

Name
Type
Description
Issue Entity Represents related issue, uses RelatedEntity1 placeholder
Work Item Entity Represents related work item, uses RelatedEntity2 placeholder

Issue Team Members

Issue Team Members entity represents the stakeholder interested in the life cycle of a specific issue.

The API name of the entity type – IssueTeamMembers.

The following table represents specific fields of the entity type:

Name
Type
Description
Issue Entity Represents related issue, uses RelatedEntity1 placeholder
User Entity Represents related user, uses RelatedEntity2 placeholder

Attachment

Attachment entity type represents relations between Work Items or Issues and Documents.
This link is a one-to-many link in current implementation, meaning that a specific document can be linked only to one work item / issue, while there can be several documents linked to one work item/issue.

The following table represents fields of Attachment entity type:

Name
Type
Description
WorkItem Entity Represents related Work Item, uses RelatedEntity1 placeholder. Reference to Work Item entity type.
Document Entity Represents document attached to specific Work Item, uses RelatedEntity2 placeholder. Reference to Document entity type.

Pick list Entities

All Pick list Table type entities have the following set of frequently used fields:

The following table represents specific fields of the Pick-list Table entity types:

Name
Type
Description
ValueOrder Integer Used to indicate the order of how the values in the pick-list table should appear in the UI.
Used for pick-list tables in which order of values is not alpha-numeric.
IsDefaultValue Boolean When True – indicates value that is given by default during creation of the object that references pick-list table

Core Requests

The following table lists the core requests that can be sent to the web service using the Execute method and provides a brief description of each request.

A more detailed description for the mostly used requests is provided in the sections below. Details on other requests can be found in the "Web Services Reference Guide".

Request
Response
Description
CreateMessage CreateResult Add a new entity to your organization's data
UpdateMessage Result Update an existing entity
RetrieveMessage RetrieveResult Retrieve an entity
RetrieveMultipleMessage RetrieveMultipleResult Retrieve multiple entities from the same entity type
DeleteMessage Result Delete an entity
LifecycleMessage Result Perform life cycle operations on an entity or group of entities
DownloadMessage DownloadResult Downloads a file that is attached to a document object
UploadMessage Result Uploads or replaces a file that is attached to a document object

Create Message

Use the CreateMessage to add an entity such as a Task or Document to your organization’s data.

The CreateMessage has one property named Entity. Use this property to provide details of the entity you’d like to add.

Depending on the type of entity you are adding, you may need to provide data for certain fields which are marked as “mandatory”. For example, when creating a Task, the field Name must have a value.

Important Do not forget to fill mandatory fields

A response of type CreateResult is returned for this message.

If the operation succeeds, the CreateResult will contain the Entity Id of the new Entity.
If you provided an Entity Id during the creation of the object, the same Entity will be returned. If you did not provide an Entity Id, a unique Entity Id will be generated and returned.
You can use this Entity Id later to identity in operations such as Retrieve, Update or Delete.

The following example shows how to create a task and set its name and start date fields:

// Create new Task
public static void CreateTask(string taskId)

{

 //Create an entity representing the new task
 Entity task = new Entity();

 task.Id = new EntityId();

 task.Id.TypeName = "Task";

 task.Id.Value = taskId;

 //Set task name
 FieldValue nameField = new FieldValue();

 nameField.FieldName = "Name";

 nameField.Value = "My Task";

 //Set task start date
 FieldValue startDateField = new FieldValue();

 startDateField.FieldName = "StartDate";

 startDateField.Value = DateTime.Now;

 //Assign the fields to the task
 task.Values = new FieldValue[] {
  nameField,
  startDateField
 };

 CreateMessage createTaskMessage = new CreateMessage();

 createTaskMessage.Entity = task;

 //Send the CreateMessage to the server for execution
 client.Execute(new BaseMessage[] {
  createTaskMessage
 });

}

 

PHP Sample Code

//Create an entity representing the new task

$newTask = new stdClass();

$newTask->Id = new stdClass();

$newTask->Id->TypeName = 'Issue';

$newTask->Id->Value = null;

//Set issue name

$nameField = new stdClass();

$nameField->FieldName = "Title";

$nameField->Value = new SoapVar("My Issue", XSD_STRING, "string", " http://www.w3.org/2001/XMLSchema" );

//Set task start date

$startDateField = new stdClass();

$startDateField->FieldName = "DueDate";

$date = '2012-05-01';

$startDateField->Value = new SoapVar($date, XSD_DATETIME, "dateTime", " http://www.w3.org/2001/XMLSchema" );

//Assign the fields to the task

$newTask->Values = array($nameField, $startDateField);

$createMeesage = new stdClass();

$createMeesage->Entity = new SoapVar($newTask, SOAP_ENC_OBJECT, "Entity", ' http://clarizen.com/api' );

$request[] = new SoapVar($createMeesage, SOAP_ENC_OBJECT, 'CreateMessage', $soapApiUrl);

$result = $client->Execute(array("request"=>$request));

Java Sample Code

// Create new Task
public static void CreateTask(String taskId) throws Exception {

 // Create an entity representing the new task

 Entity task = new Entity();

 EntityId id = new EntityId();

 id.setTypeName("Task");

 id.setValue(taskId);

 task.setId(id);

 // Set task name
 FieldValue nameField = new FieldValue();

 nameField.setFieldName("Name");

 nameField.setValue("My Task");

 // Set task start date
 FieldValue startDateField = new FieldValue();

 startDateField.setFieldName("StartDate");

 startDateField.setValue(new java.util.Date());

 // Assign the fields to the task
 ArrayOfFieldValue fieldValues = new ArrayOfFieldValue();

 fieldValues.setFieldValue(new FieldValue[] {
  nameField,
  startDateField
 });

 task.setValues(fieldValues);

 CreateMessage createTaskMessage = new CreateMessage();

 createTaskMessage.setEntity(task);

 ArrayOfBaseMessage messagesArray = new ArrayOfBaseMessage();

 messagesArray.setBaseMessage(new BaseMessage[] {
  createTaskMessage
 });

 // Send the CreateMessage to the server for execution
 ArrayOfResult results = clz.execute(messagesArray, null, null, session);

}

 

UpdateMessage

Use the UpdateMessage request when you need to update the fields of an entity.
UpdateMessage has one property named Entity.
Use this property to fill new values of the fields you want to update.
To indicate which object should be updated, you must provide an Entity Id for the Entity you pass.

Important When updating an entity, make sure you pass only the fields that need to be updated. Doing so, you will avoid possible performance implications, as well as erroneous situations similar to example below.

Following is an example of erroneous case, caused by redundant fields in the UpdateMessage:

If you retrieve a Task entity with its Name and StartDate and EndDate fields populated, and you want to update the task StartDate, you should create a new Entity, set its Entity Id, add only the StartDate field and set its new value and then send the UpdateMessage request. If, for example, you will send the EndDate field too, the following problems may occur:

-  You might overwrite changes made to the EndDate field by another user.

-  If EndDate has to be calculated by the system according to the StartDate and Duration of a task, it will now be considered "Manually Set" by the user.

A response of type Result will be returned for UpdateMessage requests. The result does not contain properties specific to the Update operation.

The following example shows how to update a reference between a task and its Manager using the UpdateMessage request:

static void UpdateManager(string taskId, string managerId)

{

 //Create an entity representing the task to update
 Entity task = new Entity();

 task.Id = new EntityId();

 task.Id.TypeName = "Task";

 task.Id.Value = taskId;

 //Create a FieldValue representing the Manager field
 FieldValue managerField = new FieldValue();

 managerField.FieldName = "Manager";

 //Set the field value to the external identifier of the new manager
 EntityId manager = new EntityId();

 manager.TypeName = "User";

 manager.Value = managerId;

 managerField.Value = manager;

 task.Values = new FieldValue[] {
  managerField
 };

 UpdateMessage updateMsg = new UpdateMessage();

 updateMsg.Entity = task;

 //Update the entity
 Result result = client.Execute(new BaseMessage[] {
  updateMsg
 })[0];

 if (result.Success)

 {

  ...

 }

}

 

PHP Sample Code

$updatedIssue = new stdClass();

$updatedIssue->Id = new stdClass();

$updatedIssue->Id->TypeName = 'Issue';

$updatedIssue->Id->Value = '84842b75-b2e0-4a05-a44c-1f581d8d73ab';

p class="CodeSampleCxSpMiddle">

//Set issue name

$nameField = new FieldValue();

$nameField->FieldName = "Title";

$nameField->Value = new SoapVar("My Updated Issue", XSD_STRING, "string", " http://www.w3.org/2001/XMLSchema" );

$updatedIssue->Values = array($nameField);

$updateMessage = new stdClass();

$updateMessage->Entity = new SoapVar($updatedIssue, SOAP_ENC_OBJECT, "Entity", ' http://clarizen.com/api' );

$request[] = new SoapVar($updateMessage, SOAP_ENC_OBJECT, 'UpdateMessage', $soapApiUrl);

$result = $client->Execute(array("request"=>$request));

Java Sample Code

public static void UpdateManager(String taskId, String managerId) throws Exception

{

 //Create an entity representing the task to update
 Entity task = new Entity();

 EntityId id = new EntityId();

 id.setTypeName("Task");

 id.setValue(taskId);

 task.setId(id);

 //Create a FieldValue representing the Manager field
 FieldValue managerField = new FieldValue();

 managerField.setFieldName("Manager");

 //Set the field value to the external identifier of the new manager
 EntityId manager = new EntityId();

 manager.setTypeName("User");

 manager.setValue(managerId);

 managerField.setValue(manager);

 ArrayOfFieldValue fieldValues = new ArrayOfFieldValue();

 fieldValues.setFieldValue(new FieldValue[] {
  managerField
 });

 task.setValues(fieldValues);

 UpdateMessage updateMsg = new UpdateMessage();

 updateMsg.setEntity(task);

 //Update the entity
 ArrayOfBaseMessage messagesArray = new ArrayOfBaseMessage();

 messagesArray.setBaseMessage(new BaseMessage[] {
  updateMsg
 });

 ArrayOfResult results = clz.execute(messagesArray, null, null, session);

}

 

RetrieveMessage\ RetrieveMultipleMessage

Use the RetrieveMessage and RetrieveMultipleMessage requests to retrieve a single or multiple entities by specifying their IDs.

Be sure that you request entities that belong to the same Entity type through RetrieveMultipleMessage request. If you need to retrieve entities that belong to different Entity types, you should issue several RetrieveMultipleMessage requests.

Important Only entities that belong to the same Entity type can be retrieved in one RetrieveMultipleMessage request,

Both request types allow you to indicate which fields to retrieve.
You should retrieve only minimal required fields to keep good performance during the database query and to minimize the amount of data transferred from server to the client.

Important To avoid performance implications retrieve only fields essential to cover required functionality.

A response of type RetrieveResult or RetrieveMultipleResult is returned containing the requested entities with the requested fields populated. If the entity cannot be retrieved for one of the reasons listed below, null will be returned and the Error field will contain the reason:

  • Entity does not exist, could be deleted by the other user
  • -       User does not have sufficient privileges to access it

RetrieveMultipleResult contains an array of RetrieveResult objects each correlated with the Entity IDs requested in the RetrieveMultipleMessage request.

Note:

RetrieveMultipleResult will always contain the same number of RetrieveResult objects, placed in the same order as was requested.

For example, if you request 10 entities, RetrieveMultipleResult will always contain 10 RetrieveResult objects in the same order as requested, also in case when specific entity(s) was not found due to one of the reasons listed above.

The following sample code shows how to retrieve a task with a known Entity Id and access its Name and StartDate fields:

static void RetrieveTask(string taskId)

{

 //Create the retrieve message
 RetrieveMessage retrieveMsg = new RetrieveMessage();

 retrieveMsg.Id = new EntityId();

 retrieveMsg.Id.TypeName = "Task";

 retrieveMsg.Id.Value = taskId;

 //Retrieve only the fields you need.

 retrieveMsg.Fields = new string[] {
  "Name",
  "StartDate"
 };

 BaseMessage[] messages = new BaseMessage[] {
  retrieveMsg
 };

 //Send the retrieve message to the server and cast the result to correct type
 RetrieveResult result = (RetrieveResult) client.Execute(messages)[0];

 //Always check the result status
 if (result.Success)

 {

  Entity task = result.Entity;

  //Now you can access the specific fields that were retrieved
  string taskName = (string) task.Values[0].Value;

  DateTime startDate = (DateTime) task.Values[1].Value;

 }

}

 

PHP Sample Code

//Retrieve an Issue Title and DueDate

$retreiveIssue = new stdClass();

$retreiveIssue->Id = new stdClass();

$retreiveIssue->Id->TypeName = 'Issue';

$retreiveIssue->Id->Value = '84842b75-b2e0-4a05-a44c-1f581d8d73ab'; //ID of the issue

$retreiveIssue->Fields =  array('Title','DueDate');

$request[] = new SoapVar($retreiveIssue, SOAP_ENC_OBJECT, 'RetrieveMessage', $soapApiUrl);

$result = $client->Execute(array("request"=>$request));

Java Sample Code

static void RetrieveTask(String taskId) throws Exception

{

 //Create the retrieve message
 RetrieveMessage retrieveMsg = new RetrieveMessage();

 EntityId id = new EntityId();

 id = new EntityId();

 id.setTypeName("Task");

 id.setValue(taskId);

 retrieveMsg.setId(id);

 //Retrieve only the fields you need.
 StringList fields = new StringList();

 fields.addString("Name");

 fields.addString("StartDate");

 retrieveMsg.setFields(fields);

 ArrayOfBaseMessage messagesArray = new ArrayOfBaseMessage();

 messagesArray.setBaseMessage(new BaseMessage[] {
  retrieveMsg
 });

 //Send the retrieve message to the server and cast the result to correct type
 RetrieveResult result = (RetrieveResult) clz.execute(messagesArray, null, null, session).getResult()[0];

 //Always check the result status
 if (result.getSuccess())

 {

  Entity task = result.getEntity();

  //Now you can access the specific fields that were retrieved
  String taskName = (String) task.getValues().getFieldValue()[0].getValue();

  GregorianCalendar startDate = (GregorianCalendar) task.getValues().getFieldValue()[1].getValue();

  Date stDate = startDate.getTime();

 }

}

 

DeleteMessage

Use the DeleteMessage request to delete an entity by specifying its ID.

PHP Sample Code

$deleteIssue = new stdClass();

$deleteIssue->Id = new stdClass();

$deleteIssue->Id->TypeName = 'Issue';

$deleteIssue->Id->Value = '84842b75-b2e0-4a05-a44c-1f581d8d73ab';

$request[] = new SoapVar($deleteIssue, SOAP_ENC_OBJECT, 'DeleteMessage', $soapApiUrl);

$result = $client->Execute(array("request"=>$request));

Java Sample Code

static void DeleteTask(String taskId) throws Exception

{

 //Create the retrieve message
 DeleteMessage deleteMsg = new DeleteMessage();

 EntityId id = new EntityId();

 id = new EntityId();

 id.setTypeName("Task");

 id.setValue(taskId);

 deleteMsg.setId(id);

 ArrayOfBaseMessage messagesArray = new ArrayOfBaseMessage();

 messagesArray.setBaseMessage(new BaseMessage[] {
  deleteMsg
 });

 Result result = clz.execute(messagesArray, null, null, session).getResult()[0];

 if (result.getSuccess())

 {

  …

 }

} 

Miscellaneous Requests

Missing Timesheet Days API

The Missing Timesheet Days API is a dedicated API to retrieve missing timesheets by day for developers implementing their own time reporting solutions. The API retrieves missing timesheets by day. Missing timesheets are considered Timesheets that do not have a State that is Submitted or Approved.

Parameters:

  • user
  • StartDate (inclusive)
  • EndDate (exclusive)
  • tolerance (in minutes)

Returns:

For each day where timesheets < working hours

  • User
  • Date
  • workingHours
  • reportedHours
  • missingHours

Click here to learn more and see a code example.

Have more questions? Submit a request

Comments

  • Avatar
    David Leyden

    This page has dead links.