Planfix API project.getList

From PlanFix
Jump to: navigation, search

Function for getting a list of projects. Request format:

<?xml version="1.0" encoding="UTF-8"?>
<request method="project.getList">
  <account></account>
  <sid></sid>
  <user>
    <id></id>
  </user>
  <target></target>
  <status></status>
  <sortType></sortType>
  <pageCurrent></pageCurrent>
  <pageSize></pageSize>
  <client>
    <id></id>
  </client>
  <filters>
    <filter>
      <type></type>
      <operator></operator>
      <value></value>
      <field></field>
      ...
    </filter>
    ...
  </filters>
  <signature></signature>
</request>
Name Type Value Notes
user Planfix user not required. use in order to view projects in which the specified user is participating. this parameter should only be used if a request is made from an account with admin rights
user.id int user identifier
target enum filter by tab not required. for a list of valid values see the tab filter for projects section
status enum filter by status not required. for a list of valid values for this field, see the project statuses section.
sortType enum sorting type not required. for a list of valid values, see the sorting types for projects section.
pageCurrent int page navigation not required. values less than 1 or omitting this parameter will initiate the procedure for counting the number of elements.
pageSize int number of values returned. cannot exceed 100 parameter not required. if omitted, the default value is used.
client not required
client.id int counterparty identifier, works as a filter
filters additional complex filters for a list of available values and formats, see the project filters section.
signature string(32) signature

All parameters except account, sid, and signature are not required. If the user parameter is omitted, you will get a list of projects available for the current user. Keep in mind that only administrators can view projects of other participants.

Response:

<?xml version="1.0" encoding="UTF-8"?>
<response status="ok">
  <projects count="count" totalCount="totalCount">
    <project>
      <id></id>
      <title></title>
      <description></description>
      <owner>
        <id></id>
        <name></name>
      </owner>
      <client>
        <id></id>
        <name></name>
      </client>
      <group>
        <id></id>
        <name></name>
      </group>
      <parent>
        <id></id>
      </parent>
      <template>
        <id></id>
      </template>
      <status></status>
      <hidden></hidden>
      <hasEndDate></hasEndDate>
      <endDate></endDate>
      <beginDate></beginDate>
      <taskCount></taskCount>
      <isOverdued></isOverdued>
      <isCloseToDeadline></isCloseToDeadline>
      <customData>
        <customValue>
          <field>
            <id></id>
            <name></name>
          </field>
          <value></value>
          <text></text>
        </customValue>
        <customValue>
          <!-- ... -->
        </customValue>
        <!-- ... -->
      </customData>
    </project>
    <!-- ... -->
  </projects>
</response>
Name Type Value Notes
projects root element, contains a list of projects
projects count int number of nodes/projects returned as a result of the request
projects totalCount int number of projects satisfying the request
project root element that describes a project in the list
id int project identifier
title string project name
description string project description
owner project owner/creator
owner.id int user identifier
owner.name string name of the user who created the project
client counterparty
client.id int counterparty identifier
client.name string counterparty name
group project group
group.id int project group identifier
group.name string project group name
parent parent project
parent.id int parent project identifier
template template
template.id int template identifier
status enum current project status for a list of valid values for this field, see the project statuses project statuses section
hidden bool hidden
hasEndDate bool indicator of whether or not the project has an end date
endDate DateTime project end date only set when hasEndDate = true
beginDate DateTime project creation date
taskCount int number of tasks in the project
isOverdued bool attribute that indicates if the project is overdue
isCloseToDeadline bool time left until deadline is 25%, or 75% of dedicated time has passed
customData values of task custom fields
customData.customValue.field.id custom field identifier
customData.customValue.field.name custom field name
customData.customValue.value custom field value
customData.customValue.text text value of the custom field

The attribute totalCount of the projects element shows how many projects can be returned by this request. This prevents you from having to additionally request the total number of projects. If you only need to know the number of elements, send a request with the parameter pageCurrent=0.

An empty response will not generate an error. If there are no projects in the resulting selection, the response will look as follows:

<?xml version="1.0" encoding="UTF-8"?>
<response status="ok">
  <projects count="0" totalCount="0"></projects>
</response>

Otherwise, an error response will be returned:

<?xml version="1.0" encoding="UTF-8"?>
<response status="error">
  <code></code>
</response>


Go To