ПланФикс API task.add — различия между версиями

Материал из ПланФикс
Перейти к: навигация, поиск
 
(не показано 36 промежуточных версий 5 участников)
Строка 1: Строка 1:
 +
{{#seo:
 +
|title=ПланФикс API task.add
 +
|titlemode=append
 +
|keywords=планфикс, задачи, апи, api
 +
|description=ПланФикс API task.add
 +
}}
 +
 
Функция позволяет создать новую задачу. Формат запроса:
 
Функция позволяет создать новую задачу. Формат запроса:
 
<source lang="xml">
 
<source lang="xml">
Строка 6: Строка 13:
 
   <sid></sid>
 
   <sid></sid>
 
   <task>
 
   <task>
 +
    <template></template>
 
     <title></title>
 
     <title></title>
 
     <description></description>
 
     <description></description>
 
     <importance></importance>
 
     <importance></importance>
 
     <status></status>
 
     <status></status>
 +
    <statusSet></statusSet>
 
     <checkResult></checkResult>
 
     <checkResult></checkResult>
 
     <owner>
 
     <owner>
Строка 23: Строка 32:
 
       <id></id>
 
       <id></id>
 
     </client>
 
     </client>
 +
    <beginDateTime></beginDateTime>
 +
    <startDateIsSet></startDateIsSet>
 +
    <startDate></startDate>
 +
    <startTimeIsSet></startTimeIsSet>
 
     <startTime></startTime>
 
     <startTime></startTime>
 +
    <endDateIsSet></endDateIsSet>
 +
    <endDate></endDate>
 +
    <endTimeIsSet></endTimeIsSet>
 
     <endTime></endTime>
 
     <endTime></endTime>
 +
    <isSummary></isSummary>
 +
    <duration></duration>
 +
    <durationUnit></durationUnit>
 +
    <durationIsSet></durationIsSet>
 
     <workers>
 
     <workers>
 
       <users>
 
       <users>
Строка 36: Строка 56:
 
         <!-- ... -->
 
         <!-- ... -->
 
       </groups>
 
       </groups>
−
     </workers>
+
     </workers>  
−
     <periodicity>
+
     <members>
−
       <!-- ежедневно -->
+
       <users>
−
       <daily>
+
        <id></id>
−
         <type>{EVERY|EVERY_WORKING|AFTER_COMPLETE}</type>
+
        <id></id>
−
         <shift></shift>
+
        <!-- ... -->
−
       </daily>
+
       </users>
−
      <!-- еженедельно -->
+
      <groups>
−
       <weekly>
+
         <id></id>
−
         <type>{EVERY|AFTER_COMPLETE}</type>
+
         <id></id>
−
         <shift></shift>
+
        <!-- ... -->
−
         <days><!-- список дней через запятую --></days>
+
       </groups>
−
       </weekly>
+
    </members>    
−
      <!-- ежемесячно -->
+
    <auditors>
−
       <monthly>
+
       <users>
−
        <type>{AFTER_COMPLETE|DAY_OF_MONTH|BY_CONDITION}</type>
+
         <id></id>
−
        <month></month>
+
         <id></id>
−
         <day></day>
+
         <!-- ... -->
−
         <dayType></dayType>
+
      </users>
−
       </monthly>
+
       <groups>
−
     </periodicity>
+
        <id></id>
 +
        <id></id>
 +
        <!-- ... -->
 +
       </groups>
 +
    </auditors>
 +
    <customData>
 +
      <customValue>
 +
         <id></id>
 +
         <value></value>
 +
       </customValue>
 +
      <!-- ... -->
 +
     </customData>
 
   </task>
 
   </task>
 +
  <signature></signature>
 
</request>
 
</request>
 
</source>
 
</source>
 
{| class="wikitable" style="margin-top: 1em; width:100% "
 
{| class="wikitable" style="margin-top: 1em; width:100% "
 
!width="150"|Название !!width="200"| Тип !!width="50%"| Значение !! Примечание  
 
!width="150"|Название !!width="200"| Тип !!width="50%"| Значение !! Примечание  
 +
|-
 +
|template ||id ||идентификатор шаблона задачи || id в ответе [[ПланФикс API task.getList|task.getList]] с target = template
 +
|-
 +
|colspan="4"|Реализация создания задачи по шаблону в API на текущий момент неполна.
 +
 +
Из шаблона устанавливается форма создания задачи (и соответственно имеющиеся в задаче пользовательские поля) и часть её свойств.
 +
 +
Из шаблона на текущий момент не устанавливаются: сроки задачи, аудиторы, аналитики, файлы, напоминания, чек-листы. Исполнители и участники устанавливаются из шаблона, если они отсутствуют в запросе.
 
|-
 
|-
 
|title ||string ||название задачи ||
 
|title ||string ||название задачи ||
Строка 69: Строка 109:
 
|importance || enum||срочность || перечень допустимых значений смотри в разделе [[ПланФикс API:Срочность задачи|срочность задач]]
 
|importance || enum||срочность || перечень допустимых значений смотри в разделе [[ПланФикс API:Срочность задачи|срочность задач]]
 
|-
 
|-
−
|status ||enum ||статус задачи || перечень допустимых значений смотри в разделе [[ПланФикс API:Статусы задач|статусы задач]]
+
|status ||enum/int ||статус задачи || Допустимы значения из раздела [[ПланФикс API:Системные статусы задач|Системные статусы задач]] или идентификаторы статусов, полученные в результате вызова функции [[ПланФикс API taskStatus.getListOfSet|taskStatus.getListOfSet]]
 +
|-
 +
|statusSet ||int ||процесс задачи || Идентификаторы процессов можно получить в результате вызова функции [[ПланФикс API taskStatus.getSetList|taskStatus.getSetList]]
 
|-
 
|-
 
|checkResult ||bool ||является ли задача задачей с обязательной проверкой результата ||
 
|checkResult ||bool ||является ли задача задачей с обязательной проверкой результата ||
Строка 75: Строка 117:
 
|owner || || создатель задачи||необязательное поле. Если не указано - берется пользователь от имени которого выполняется функция
 
|owner || || создатель задачи||необязательное поле. Если не указано - берется пользователь от имени которого выполняется функция
 
|-
 
|-
−
|owner.id ||int ||идентификатор пользователя ||
+
|owner.id ||int ||идентификатор пользователя || если это контакт - нужно использовать userid из ответа [[ПланФикс API contact.get|contact.get]]
 
|-
 
|-
 
|parent || ||над задача || необязательное поле
 
|parent || ||над задача || необязательное поле
Строка 87: Строка 129:
 
|client || || контрагент|| необязательный параметр
 
|client || || контрагент|| необязательный параметр
 
|-
 
|-
−
|client.id ||int ||идентификатор контрагента ||допустимо значение 0
+
|client.id ||int ||идентификатор контрагента (id из ответа contact.get) ||допустимо значение 0
 +
|-
 +
|beginDateTime ||DateTime || дата/время создания - не обязательный, по-умолчанию текущие || может заполняться, только если авторизация была сделана под сотрудником с правами администратора
 +
|-
 +
|startDateIsSet ||bool (0/1)|| задана ли дата начала работы ||
 +
|-
 +
|startDate ||Date || дата начала работы || в интерфейсе ПланФикс поле ''приступить к работе''
 +
|-
 +
|startTimeIsSet ||bool (0/1)|| задано ли время начала работы ||
 +
|-
 +
|startTime ||Time || время начала работы || в интерфейсе ПланФикс поле ''приступить к работе''
 +
|-
 +
|endDateIsSet ||bool (0/1)|| задана ли дата завершения работы ||
 +
|-
 +
|endDate ||Date || дата завершения работы || в интерфейсе ПланФикс поле ''закончить работу До''
 +
|-
 +
|endTimeIsSet ||bool (0/1)|| задано ли время завершения работы ||
 +
|-
 +
|endTime ||Time || время завершения работы || в интерфейсе ПланФикс поле ''закончить работу До''
 +
|-
 +
|isSummary ||bool (0/1)|| задача является суммарной ||
 
|-
 
|-
−
|startTime ||DateTime || время начала работы || в интерфейсе ПланФикс поле ''приступить к работе''
+
|durationIsSet||bool|| задана ли длительность ||  
 
|-
 
|-
−
|endTime ||DateTime || время окончания задачи ||в интерфейсе ПланФикс поле ''закончить работу До''
+
|duration||int|| длительность ||
 +
|-
 +
|durationUnit||int|| 0 - минуты, 1 - часы, 2 - дни ||  
 
|-
 
|-
 
|workers || ||корневой элемент списка исполнителей задачи ||
 
|workers || ||корневой элемент списка исполнителей задачи ||
Строка 97: Строка 161:
 
|workers.users || || корневой элемент списка пользователей, которым поставлена задача ||
 
|workers.users || || корневой элемент списка пользователей, которым поставлена задача ||
 
|-
 
|-
−
|workers.users.id ||int ||идентификатор пользователя которому поставлена задача ||
+
|workers.users.id ||int ||идентификатор пользователя которому поставлена задача || для контактов - нужно использовать userid из ответа [[ПланФикс API contact.get|contact.get]]
 
|-
 
|-
 
|workers.groups || ||корневой элемент списка групп, которым поставлена задача ||
 
|workers.groups || ||корневой элемент списка групп, которым поставлена задача ||
Строка 103: Строка 167:
 
|workers.groups.id ||int || идентификатор группы||
 
|workers.groups.id ||int || идентификатор группы||
 
|-
 
|-
−
|periodicity ||node ||задает периодичность выполнения задачи || смотри описание структуры узла ниже
+
|members || ||корневой элемент списка участников задачи ||
 
|-
 
|-
−
|}
+
|members.users || || корневой элемент списка участников задачи ||
−
Добавляемые даты могут задаваться в двух форматах. Первый формат короткий, указывается только число, год и месяц. Второй формат - полный, дополнительно указывается время начала/завершения, если того требует задача. Периодичность - не обязательный параметр. Внутри тега '''periodicity''' может быть только один из перечисленных элементов: ''daily'', ''weekly'', ''monthly''.
+
|-
−
 
+
|members.users.id ||int ||идентификатор участника задачи || для контактов - нужно использовать userid из ответа [[ПланФикс API contact.get|contact.get]]
−
=== описание параметра periodicity ===
 
−
Описание параметра ''daily'', параметры ''weekly'' и ''monthly'' в этом случае не могут быть заданы. Указывает что задача должна повторяться ежедневно, согласно установленным критериям:
 
−
{| class="wikitable" style="margin-top: 1em; width:100% "
 
−
!width="150"|Название !!width="200"| Тип !!width="50%"| Значение !! Примечание
 
 
|-
 
|-
−
|type ||enum||определяет периодичность || допустимые значения EVERY или EVERY_WORKING, или AFTER_COMPLETE
+
|members.groups || ||корневой элемент списка групп участников ||
 
|-
 
|-
−
|shift || int||определяет сдвиг в днях || используется только при значениях type равным  EVERY или AFTER_COMPLETE
+
|members.groups.id ||int || идентификатор группы участников ||
 
|-
 
|-
−
|}
+
|auditors || ||корневой элемент списка аудиторов задачи, содержимое аналогично workers и members ||
−
Значение EVERY интерпретируется как каждый N-й день, заданный в параметре '''shift'''. EVERY_WORKING - каждый рабочий день.  Значение AFTER_COMPLETE интерпретируется как ставить новую задачу через N-й день после каждого завершения, заданный в параметре '''shift'''.
 
−
 
 
−
Описание параметра ''weekly'', параметры ''daily'' и ''monthly'' в этом случае не могут быть заданы. Указывает что задача должна повторяться еженедельно, согласно установленным критериям:
 
−
{| class="wikitable" style="margin-top: 1em; width:100% "
 
−
!width="150"|Название !!width="200"| Тип !!width="50%"| Значение !! Примечание
 
 
|-
 
|-
−
|type ||enum || определяет периодичность || допустимые значения EVERY или AFTER_COMPLETE
+
|customData|| ||значения пользовательских полей задачи ||
 
|-
 
|-
−
|shift ||int || сдвиг в днях ||  
+
|customData.customValue.id|| ||идентификатор пользовательского поля задачи ||
 
|-
 
|-
−
|days ||set/list || перечень дней недели, разделитель символ запятой (,). понедельник имеет индекс 1, воскресение - 7. || используется только при type=AFTER_COMPLETE
+
|customData.customValue.value|| ||значение пользовательского поля задачи || (для полей типа набор задач, список сотрудников, набор записей справочника - идентификаторы через запятую в квадратных скобках)
 
|-
 
|-
 
|}
 
|}
−
Значение AFTER_COMPLETE интерпретируется как: ставить задачу через N-й неделю после каждого завершения, заданную в параметре '''shift'''.
+
Добавляемые даты могут задаваться в двух форматах. Первый формат короткий, указывается только число, год и месяц. Второй формат - полный, дополнительно указывается время начала/завершения, если того требует задача.  
  
−
Описание параметра ''monthly'', параметры ''daily'' и ''weekly'' в этом случае не могут быть заданы. Указывает что задача должна повторяться ежемесяно, согласно установленным критериям:
+
Ответ при удачном выполнении операции:
 +
<source lang="xml">
 +
<?xml version="1.0" encoding="UTF-8"?>
 +
<response status="ok">
 +
  <task>
 +
    <id></id>
 +
    <general></general>
 +
  </task>
 +
</response>
 +
</source>
 
{| class="wikitable" style="margin-top: 1em; width:100% "
 
{| class="wikitable" style="margin-top: 1em; width:100% "
 
!width="150"|Название !!width="200"| Тип !!width="50%"| Значение !! Примечание  
 
!width="150"|Название !!width="200"| Тип !!width="50%"| Значение !! Примечание  
 
|-
 
|-
−
|type ||enum || периодичность || допустимые значения AFTER_COMPLETE или DAY_OF_MONTH, или BY_CONDITION
+
|task.id ||int ||идентификатор созданной задачи ||
−
|-
 
−
|month ||int ||задает месяц в/через который должно действие/задача повторяться ||
 
 
|-
 
|-
−
|day ||int ||задает день в/через который должна задача повторяться || не используется при type=AFTER_COMPLETE
+
|task.general ||int ||сквозной номер созданной задачи||
−
|-
 
−
|dayType ||enum || ||
 
 
|-
 
|-
 
|}
 
|}
  
−
Ответ при удачном выполнении операции:
+
 
 +
В противном случае будет возвращен ответ с ошибкой:
 
<source lang="xml">
 
<source lang="xml">
 
<?xml version="1.0" encoding="UTF-8"?>
 
<?xml version="1.0" encoding="UTF-8"?>
−
<response status="ok">
+
<response status="error">
−
<task>
+
  <code></code>
−
<id></id>
 
−
</task>
 
 
</response>
 
</response>
 
</source>
 
</source>
Строка 159: Строка 218:
  
 
== Перейти ==
 
== Перейти ==
−
*[[ПланФикс API]]
 
 
*[[ПланФикс API:Задачи]]
 
*[[ПланФикс API:Задачи]]
 +
*[[Коды ошибок]]
 +
*[[Список функций]]

Текущая версия на 05:52, 26 августа 2021

Функция позволяет создать новую задачу. Формат запроса: 

<?xml version="1.0" encoding="UTF-8"?>
<request method="task.add">
  <account></account>
  <sid></sid>
  <task>
    <template></template>
    <title></title>
    <description></description>
    <importance></importance>
    <status></status>
    <statusSet></statusSet>
    <checkResult></checkResult>
    <owner>
      <id></id>
    </owner>
    <parent>
      <id></id>
    </parent>
    <project>
      <id></id>
    </project>
    <client>
      <id></id>
    </client>
    <beginDateTime></beginDateTime>
    <startDateIsSet></startDateIsSet>
    <startDate></startDate>
    <startTimeIsSet></startTimeIsSet>
    <startTime></startTime>
    <endDateIsSet></endDateIsSet>
    <endDate></endDate>
    <endTimeIsSet></endTimeIsSet>
    <endTime></endTime>
    <isSummary></isSummary>
    <duration></duration>
    <durationUnit></durationUnit>
    <durationIsSet></durationIsSet>
    <workers>
      <users>
        <id></id>
        <id></id>
        <!-- ... -->
      </users>
      <groups>
        <id></id>
        <id></id>
        <!-- ... -->
      </groups>
    </workers>    
    <members>
      <users>
        <id></id>
        <id></id>
        <!-- ... -->
      </users>
      <groups>
        <id></id>
        <id></id>
        <!-- ... -->
      </groups>
    </members>      
    <auditors>
      <users>
        <id></id>
        <id></id>
        <!-- ... -->
      </users>
      <groups>
        <id></id>
        <id></id>
        <!-- ... -->
      </groups>
    </auditors>
    <customData>
      <customValue>
        <id></id>
        <value></value>
      </customValue>
      <!-- ... -->
    </customData>
  </task>
  <signature></signature>
</request>
Название Тип Значение Примечание
template id идентификатор шаблона задачи id в ответе task.getList с target = template
Реализация создания задачи по шаблону в API на текущий момент неполна.

Из шаблона устанавливается форма создания задачи (и соответственно имеющиеся в задаче пользовательские поля) и часть её свойств.

Из шаблона на текущий момент не устанавливаются: сроки задачи, аудиторы, аналитики, файлы, напоминания, чек-листы. Исполнители и участники устанавливаются из шаблона, если они отсутствуют в запросе.

title string название задачи
description string о чем задача, описание
importance enum срочность перечень допустимых значений смотри в разделе срочность задач
status enum/int статус задачи Допустимы значения из раздела Системные статусы задач или идентификаторы статусов, полученные в результате вызова функции taskStatus.getListOfSet
statusSet int процесс задачи Идентификаторы процессов можно получить в результате вызова функции taskStatus.getSetList
checkResult bool является ли задача задачей с обязательной проверкой результата
owner создатель задачи необязательное поле. Если не указано - берется пользователь от имени которого выполняется функция
owner.id int идентификатор пользователя если это контакт - нужно использовать userid из ответа contact.get
parent над задача необязательное поле
parent.id int идентификатор задачи, которая будет являться над задачей допустимо значение 0 (ноль)
project в рамках какого проекта поставлена задача
project.id int идентификатор проекта
client контрагент необязательный параметр
client.id int идентификатор контрагента (id из ответа contact.get) допустимо значение 0
beginDateTime DateTime дата/время создания - не обязательный, по-умолчанию текущие может заполняться, только если авторизация была сделана под сотрудником с правами администратора
startDateIsSet bool (0/1) задана ли дата начала работы
startDate Date дата начала работы в интерфейсе ПланФикс поле приступить к работе
startTimeIsSet bool (0/1) задано ли время начала работы
startTime Time время начала работы в интерфейсе ПланФикс поле приступить к работе
endDateIsSet bool (0/1) задана ли дата завершения работы
endDate Date дата завершения работы в интерфейсе ПланФикс поле закончить работу До
endTimeIsSet bool (0/1) задано ли время завершения работы
endTime Time время завершения работы в интерфейсе ПланФикс поле закончить работу До
isSummary bool (0/1) задача является суммарной
durationIsSet bool задана ли длительность
duration int длительность
durationUnit int 0 - минуты, 1 - часы, 2 - дни
workers корневой элемент списка исполнителей задачи
workers.users корневой элемент списка пользователей, которым поставлена задача
workers.users.id int идентификатор пользователя которому поставлена задача для контактов - нужно использовать userid из ответа contact.get
workers.groups корневой элемент списка групп, которым поставлена задача
workers.groups.id int идентификатор группы
members корневой элемент списка участников задачи
members.users корневой элемент списка участников задачи
members.users.id int идентификатор участника задачи для контактов - нужно использовать userid из ответа contact.get
members.groups корневой элемент списка групп участников
members.groups.id int идентификатор группы участников
auditors корневой элемент списка аудиторов задачи, содержимое аналогично workers и members
customData значения пользовательских полей задачи
customData.customValue.id идентификатор пользовательского поля задачи
customData.customValue.value значение пользовательского поля задачи (для полей типа набор задач, список сотрудников, набор записей справочника - идентификаторы через запятую в квадратных скобках)

Добавляемые даты могут задаваться в двух форматах. Первый формат короткий, указывается только число, год и месяц. Второй формат - полный, дополнительно указывается время начала/завершения, если того требует задача.

Ответ при удачном выполнении операции: 

<?xml version="1.0" encoding="UTF-8"?>
<response status="ok">
  <task>
    <id></id>
    <general></general>
  </task>
</response>
Название Тип Значение Примечание
task.id int идентификатор созданной задачи
task.general int сквозной номер созданной задачи


В противном случае будет возвращен ответ с ошибкой: 

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


Перейти

Источник — «http://planfix.ru/wiki/index.php?title=ПланФикс_API_task.add&oldid=34744»