Returns folders that meet the specified condition. If no condition is specified, the method returns all folders in all areas of the specified projects.

The operation can get folders from one or several projects. To specify a project to get folders from, use the ProjId value in the AuthenticationData object in the request body. To get folders from several projects, use the ProjIds value in the AuthenticationData object to specify the list of project IDs.

The method returns results in pages (subsets of data) rather than all at once. The number of pages and the number of folders each page contains is controlled by the PageSize and PageNumber parameters. For information about working with pages, see LoadByCriteria Operations.

Requirements

The user must belong to a security group that has the Read privilege for Folder Maintenance of the application areas to which the folders belong.

Parameters

The operation uses the following parameters:

AuthenticationData : , required

An AuthenticationData object with the login information and the ID of the project (or the list of project IDs) whose folders you want to get.

Condition : string, required

An XML-formatted string that describes the folders you want to get. For the syntax and examples, see Condition Syntax.

If you create SOAP requests manually, place the condition string inside CDATA.

To get all folders, use an empty string or a null value.

Sorting : string, required

The order to sort the results before returning them from the web service. For example, by folder ID or last updated date. The format is:

Property1 [ASC | DESC ][, Property2 [ASC | DESC ]] [, ...]]]

where property names are those of the Folder object. If you omit ASC or DESC after a property name, folders are sorted in ascending order.

Example values:

FolderId

ParentName, FolderName

DateUpdated DESC

To keep the default sort order, use an empty string or a null value.

PageSize : integer, required

Limits the number of folders to return in one page. Possible values: 1..200.

The last page may have less items than PageSize. This means the end of the result set.

PageNumber : integer, required

A number starting from 1 that specifies the data page to return in the response. To get all pages, send several requests with increasing PageNumber values. For example, if PageSize is 100, PageNumber of 1 will return folders 1..100, PageNumber of 2 - folders 101..200 and so on.

If PageNumber exceeds the range, an empty array is returned. If PageNumber is the last page, this page may have less items than PageSize.

Result

An array of the Folder objects that meet the criteria.

Example

Sample Code

C#

Java

C#

string login = "[email protected]";
string password = "p@ssword";

ServiceSoapClient service = new ServiceSoapClient();

// Prepare AuthenticationData
LoginInfo loginInfo = service.GetLoginInfo("", login, password);
AuthenticationData authData = new AuthenticationData();
authData.AppCode = loginInfo.AppCode;
authData.UserId = loginInfo.UserId;
authData.PassCode = password;
authData.DeptId = loginInfo.DeptId;
authData.ProjId = loginInfo.ProjId;

// Specify the condition
string condition =
        @"<Conditions xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'
        xmlns:xsd='http://www.w3.org/2001/XMLSchema' Operation='opEQU'>
          <Items Type='tField'>
            <Value xsi:type='xsd:string'>EntityCode</Value>
          </Items>
          <Items Type='tString'>
            <Value xsi:type='xsd:string'>Bugs</Value>
          </Items>
        </Conditions>";

// Specify the sorting
string sorting = "FolderId";
// Specify the number of folders on a page
int pageSize = 200;
// Specify the number of a page
int pageNumber = 1;

// Get the array of folders
Folder[] folders;
do
{
  folders = service.Folders_LoadByCriteria(authData, condition, sorting, pageSize, pageNumber);
    foreach (Folder folder in folders)
    {
      // Print ID and name of each folder
      Console.WriteLine("{0}: {1}", folder.FolderId, folder.FolderName);
    }
  pageNumber++;
}
while (folders.Length == pageSize);

Java

String login = "[email protected]";
String password = "p@ssword";

ServiceSoap service = new Service().getServiceSoap12();

// Prepare AuthenticationData
LoginInfo loginInfo = service.getLoginInfo("", login, password);
AuthenticationData authData = new AuthenticationData();
authData.setAppCode(loginInfo.getAppCode());
authData.setUserId(loginInfo.getUserId());
authData.setPassCode(password);
authData.setDeptId(loginInfo.getDeptId());
authData.setProjId(loginInfo.getProjId());

// Specify the condition
String condition =
          "<Conditions xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'\n" +
          "  xmlns:xsd='http://www.w3.org/2001/XMLSchema' Operation='opEQU'> \n" +
          "  <Items Type='tField'> \n" +
          "    <Value xsi:type='xsd:string'>EntityCode</Value> \n" +
          "  </Items> \n" +
          "  <Items Type='tString'> \n" +
          "    <Value xsi:type='xsd:string'>Bugs</Value> \n" +
          "  </Items> \n" +
          "</Conditions>";

// Specify the sorting
String sorting = "FolderId";
// Specify the number of folders on a page
int pageSize = 200;
// Specify the number of a page
int pageNumber = 1;
List<Folder> folders;
do
{
  // Get the array of folders
  folders = service.foldersLoadByCriteria(authData, condition, sorting, pageSize, pageNumber).getFolder();
  for (Folder folder : folders)
  {
      // Print the ID and name of each folder
    System.out.format("%d: %s%n", folder.getFolderId(), folder.getFolderName());
  }
  pageNumber++;
}
while (folders.size() == pageSize);

Sample Request XML

SOAP 1.1

SOAP 1.2

POST /psws/psws.asmx HTTP/1.1
Host: myteam.mysite.com
Content-Type: text/xml; charset=utf-8
Content-Length: 1012 {Insert an appropriate value here}
SOAPAction: "http://www.pragmaticsw.com/Folders_LoadByCriteria"

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <Folders_LoadByCriteria xmlns="http://www.pragmaticsw.com/">
      <AuthenticationData>
        <AppCode>agSP</AppCode>
        <DeptId>8162</DeptId>
        <ProjId>11873</ProjId>
        <UserId>24661</UserId>
        <PassCode>p@ssword</PassCode>
      </AuthenticationData>
      <Condition> <Conditions xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'
          xmlns:xsd='http://www.w3.org/2001/XMLSchema' Operation='opEQU'>
          <Items Type='tField'> 
            <Value xsi:type='xsd:string'>EntityCode</Value> 
          </Items> 
          <Items Type='tString'> 
            <Value xsi:type='xsd:string'>Bugs</Value> 
          </Items> 
</Conditions></Condition>
      <Sorting>FolderId</Sorting>
      <PageSize>200</PageSize>
      <PageNumber>1</PageNumber>
    </Folders_LoadByCriteria>
  </soap:Body>
</soap:Envelope>

SOAP 1.2

POST /psws/psws.asmx HTTP/1.1
Host: myteam.mysite.com
Content-Type: application/soap+xml; charset=utf-8
Content-Length: 1020 {Insert an appropriate value here}

<?xml version="1.0" encoding="utf-8"?>
<soap12:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap12="http://www.w3.org/2003/05/soap-envelope">
  <soap12:Body>
    <Folders_LoadByCriteria xmlns="http://www.pragmaticsw.com/">
      <AuthenticationData>
        <AppCode>agSP</AppCode>
        <DeptId>8162</DeptId>
        <ProjId>11873</ProjId>
        <UserId>24661</UserId>
        <PassCode>p@ssword</PassCode>
      </AuthenticationData>
      <Condition> <Conditions xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'
          xmlns:xsd='http://www.w3.org/2001/XMLSchema' Operation='opEQU'>
          <Items Type='tField'> 
            <Value xsi:type='xsd:string'>EntityCode</Value> 
          </Items> 
          <Items Type='tString'> 
            <Value xsi:type='xsd:string'>Bugs</Value> 
          </Items> 
</Conditions></Condition>
      <Sorting>FolderId</Sorting>
      <PageSize>200</PageSize>
      <PageNumber>1</PageNumber>
    </Folders_LoadByCriteria>
  </soap12:Body>
</soap12:Envelope>

Sample Response XML

SOAP 1.1

SOAP 1.2

HTTP/1.1 200 OK
Content-Type: text/xml; charset=utf-8
Content-Length: 1594 {The server returns an appropriate value here}

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <Folders_LoadByCriteriaResponse xmlns="http://www.pragmaticsw.com/">
      <Folders_LoadByCriteriaResult>
        <Folder>
          <FolderId>4</FolderId>
          <ProjId>11873</ProjId>
          <FolderName>Product Backlogs</FolderName>
          <Description>Recent product backlogs</Description>
          <EntityCode>Bugs</EntityCode>
          <IsPublic>Y</IsPublic>
          <OwnerUserId>24661</OwnerUserId>
          <DeptId>8162</DeptId>
          <ParentName>Backlogs</ParentName>
          <IsActive>Y</IsActive>
          <IsVersion>N</IsVersion>
          <FullFolderName>Backlogs/Product Backlogs</FullFolderName>
          <OwnerUserName>Doe, John</OwnerUserName>
          <DateCreated>2014-07-17T06:33:08</DateCreated>
          <DateUpdated>2014-07-20T11:23:17</DateUpdated>
          <UpdateUserId>24661</UpdateUserId>
          <UserName>Doe, John</UserName>
        </Folder>
        <Folder>
          <FolderId>5</FolderId>
          <ProjId>11873</ProjId>
          <FolderName>Environment Backlogs</FolderName>
          <Description>Environment backlogs</Description>
          <EntityCode>Bugs</EntityCode>
          <IsPublic>Y</IsPublic>
          <OwnerUserId>24661</OwnerUserId>
          <DeptId>8162</DeptId>
          <ParentName>Backlogs</ParentName>
          <IsActive>Y</IsActive>
          <IsVersion>N</IsVersion>
          <FullFolderName>Backlogs/Environment Backlogs</FullFolderName>
          <OwnerUserName>Doe, John</OwnerUserName>
          <DateCreated>2014-07-18T08:27:02.38</DateCreated>
          <DateUpdated>2014-07-18T08:27:02</DateUpdated>
          <UpdateUserId>24661</UpdateUserId>
          <UserName>Doe, John</UserName>
        </Folder>
      </Folders_LoadByCriteriaResult>
    </Folders_LoadByCriteriaResponse>
  </soap:Body>
</soap:Envelope>

SOAP 1.2

HTTP/1.1 200 OK
Content-Type: application/soap+xml; charset=utf-8
Content-Length: 1604 {The server returns an appropriate value here}

<?xml version="1.0" encoding="utf-8"?>
<soap12:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap12="http://www.w3.org/2003/05/soap-envelope">
  <soap12:Body>
    <Folders_LoadByCriteriaResponse xmlns="http://www.pragmaticsw.com/">
      <Folders_LoadByCriteriaResult>
        <Folder>
          <FolderId>4</FolderId>
          <ProjId>11873</ProjId>
          <FolderName>Product Backlogs</FolderName>
          <Description>Recent product backlogs</Description>
          <EntityCode>Bugs</EntityCode>
          <IsPublic>Y</IsPublic>
          <OwnerUserId>24661</OwnerUserId>
          <DeptId>8162</DeptId>
          <ParentName>Backlogs</ParentName>
          <IsActive>Y</IsActive>
          <IsVersion>N</IsVersion>
          <FullFolderName>Backlogs/Product Backlogs</FullFolderName>
          <OwnerUserName>Doe, John</OwnerUserName>
          <DateCreated>2014-07-17T06:33:08</DateCreated>
          <DateUpdated>2014-07-20T11:23:17</DateUpdated>
          <UpdateUserId>24661</UpdateUserId>
          <UserName>Doe, John</UserName>
        </Folder>
        <Folder>
          <FolderId>5</FolderId>
          <ProjId>11873</ProjId>
          <FolderName>Environment Backlogs</FolderName>
          <Description>Environment backlogs</Description>
          <EntityCode>Bugs</EntityCode>
          <IsPublic>Y</IsPublic>
          <OwnerUserId>24661</OwnerUserId>
          <DeptId>8162</DeptId>
          <ParentName>Backlogs</ParentName>
          <IsActive>Y</IsActive>
          <IsVersion>N</IsVersion>
          <FullFolderName>Backlogs/Environment Backlogs</FullFolderName>
          <OwnerUserName>Doe, John</OwnerUserName>
          <DateCreated>2014-07-18T08:27:02.38</DateCreated>
          <DateUpdated>2014-07-18T08:27:02</DateUpdated>
          <UpdateUserId>24661</UpdateUserId>
          <UserName>Doe, John</UserName>
        </Folder>
      </Folders_LoadByCriteriaResult>
    </Folders_LoadByCriteriaResponse>
  </soap12:Body>
</soap12:Envelope>

Folders_LoadByCriteria Operation

Requirements

Parameters

Result

Example

Sample Code

Sample Request XML

Sample Response XML

See Also