Visual Studio

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

Java (Apache Axis2)

This section shows how to import the AdaptiveWork WSDL using the Apache Axis2 WSDL2Java tool.
WSDL2Java will generate java proxy classes that you can use in your code to access the AdaptiveWork 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/AdaptiveWork.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.

C# Sample Code

static void Main(string[] args)

{

 //Create a proxy to the AdaptiveWork Web Service

 clarizenClient = new AdaptiveWork();

 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 AdaptiveWork Web Service
 AdaptiveWorkStub clz = new AdaptiveWorkStub();

 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/AdaptiveWork.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());

}

Entity

An entity in AdaptiveWork is represented in Web Services using the Entity class.
The Entity class is a representation of a AdaptiveWork 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;

 }

}

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.

Working with References

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

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 AdaptiveWork Operations

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

Execute

The Execute is used to perform the majority of operations over AdaptiveWork 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 AdaptiveWork Web Service

 clarizenClient = new AdaptiveWork();

 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 AdaptiveWork'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 AdaptiveWork 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 });

Session Timeout

Similar to AdaptiveWork'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.

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).

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.

Commonly Used Fields

Standard Entity Types

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 });
 

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 });

// 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
 });

}

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 });

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 });
        }

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);

}

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);

}

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();

 }

}

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())

 {

  …

 }

}