Формат полей формы

Облачный Pyrus

Безоблачный Pyrus

Поле формы описывается JSON объектом, который содержит уникальный номер поля, название, его тип, текущее значение и дополнительную информацию о правилах его заполнения.

{
  "id": 15,
  "name": "Summary",
  "type": "text",
  "value": "Printer does not print",
  "code": "SummaryCode",
  "info": {
    "immutable_step": 1,
    "required_step": 1
  }
}

В зависимости от вызываемого метода передается и возвращается только часть свойств:

Запрос	id	name	type	value	info	parent_id	row_id	code
GET /forms	✔	✔	✔		✔	✔
GET /forms/{form-id}	✔	✔	✔		✔
GET /forms/{form-id}/register	✔	✔	✔	✔		✔	✔
GET /tasks/{task-id}	✔	✔	✔	✔		✔	✔	✔
POST /tasks/{task-id}/comments	✔*			✔				✔
POST /tasks	✔*			✔				✔

* Необходимо указать хотя бы один из этих параметров

Типы полей и примеры

Бывают простые и составные типы полей. В качестве значения простые типы принимают значения стандартных типов данных (строка, число, дата), составные — JSON объект.

Простые типы

Тип	Описание	Пример
text		"value": "IT Conference"
money		"value": 1365.27
number		"value": 157.2134
date	Формат даты: YYYY-MM-DD	"value": "2017-03-16"
time	Формат времени: HH:mm	"value": "17:26"
checkmark	Возможные значения: checked unchecked	"value": "checked"
due_date	Формат даты: YYYY-MM-DD "duration": длительность в минутах, необязательное значение	"value": "2017-03-16" "duration": "140"
due_date_time	Формат даты: YYYY-MM-DDThh:mm:ssZ "duration": длительность в минутах, необязательное значение	"value": "2017-03-16T14:53:23Z" "duration": "140"
email		"value": "consumer@mycompany.com"
phone		"value": "+7 800 555 3565"
flag	Возможные значения: none checked unchecked	"value": "unchecked"
step	только для чтения	"value": 1
status	только для чтения Возможные значения: open closed	"value": "open"
creation_date	только для чтенияФормат даты: YYYY-MM-DDThh:mm:ssZ возвращается дата и время по UTC	"value": "2017-03-18T14:53:23Z"
note	только для чтения	"value": "This is a tooltip"

Для записи в примитивный тип необходимо передать идентификатор id или имя поля name, а также новое значение в поле value.

Составные типы

catalog Чтение:

Справочник с единственным выбором:

"value": {
    "item_id": 80797460,
    "item_ids": [
        80797460
    ],
    "headers": [
        "Vendor Name",
        "Vendor Code"
    ],
    "values": [
        "GE",
        "123"
    ],
    "rows": [
        [
            "GE",
            "123"
        ]
    ]
}

Справочник со множественным выбором:

"value": {
    "item_ids": [
        80797460,
        80797461
    ],
    "headers": [
        "Vendor Name",
        "Vendor Code"
    ],
    "rows": [
        [
            "GE",
            "123"
        ],
        [
            "VN",
            "321"
        ]
    ]
}

Запись:

Справочник с единственным выбором: для записи значения можно передать как идентификатор элемента в каталоге,

"value": {
  "item_id": 23
}

так и название элемента:

"value": {
  "item_name": "GE"
}

Справочник со множественным выбором:

"value": {
    "item_ids": [
        80797460,
        80797461
    ]
}

или:

"value": {
    "item_names": [
        "GE",
        "VN"
    ]
}

file Чтение:

"value": [{
  "id": 17563,
  "name": "S15294-16.pdf",
  "size": 541512,
  "md5": "202cb962ac59075b964b07152d234b70",
  "url": "https://api.pyrus.com/files/17563",
  "version": 2,
  "root_id": 17562
}]

Запись:

См. формат значений параметра attachments метода создания задачи или метода добавления комментария.

person Чтение:

"value": {
  "id": 1730,
  "first_name": "Jane",
  "last_name": "Doe",
  "email": "Jane.Doe@gmail.com",
  "type": "user"
}

Запись:

Для записи можно передать как идентификатор пользователя:

"value": {
  "id": 1730,
}

так и его email:

"value": {
  "email": "Jane.Doe@gmail.com",
}

author (только для чтения) Чтение:

"value": {
  "id": 1730,
  "first_name": "Jane",
  "last_name": "Doe",
  "email": "Jane.Doe@gmail.com",
  "type": "user"
}

table Чтение:

"value": [
    {
    "row_id": 0,
    "position": 1,
    "cells": [
      {
        "id": 6,
        "type": "date",
        "name": "Date",
        "value": "2017-08-26",
        "parent_id": 5,
        "row_id": 0,
      },
      {
        "id": 9,
        "type": "money",
        "name": "Amount",
        "value": 10000,
        "parent_id": 5,
        "row_id": 0,
      }
    ]
  },
  {
    "row_id": 1,
    "position": 1,
    "cells": [
    {
      "id": "6",
      "type": "date",
      "name": "Date",
      "value": "2017-08-27",
      "parent_id": 5,
      "row_id": 1,
    },
    {
      "id": 9,
      "type": "money",
      "name": "Amount",
      "value": 306.25,
      "parent_id": 5,
      "row_id": 1,
    }
  ]}
]

Запись:

"value": [{
    "row_id": 0,
    "position": 1,
    "delete": true
  },
  {
  "row_id": 1,
  "cells": [
    {
      "id": 9,
      "value": 351.25
    },
    {
      "id": 6,
      "value": "2017-08-21"
    }
  ]
}]

Обратите внимание: при отображении таблицы порядок её строк определяется параметром позиции — position. Если этот параметр не указан, то порядок формируется на основе идентификаторов строк row_id — от меньшего к большего. Благодаря этому можно добавить новую строку в середину таблицы или изменить порядок её строк.

multiple_choice Чтение:

"value": {
  "choice_ids": [5],
  "choice_names": ["Yes"]
  "fields": [
    {
      "id": 6,
      "type": "text",
      "name": "Comment",
      "value": "Additional information about choice",
      "parent_id": 4
    },
    {
      "id": 9,
      "type": "number",
      "name": "Quantity",
      "value": 15,
      "parent_id": 4
    }
  ]
}

Запись:

"value": {
    "choice_ids": [5]
    "fields": [
      {
        "id": 9,
        "value": 1
      }
    ]
  }

title Чтение:

"value": {
  checkmark: "checked",
  "fields": [
    {
      "id": "3",
      "type": "date",
      "name": "Date",
      "value": "2017-08-19",
      "parent_id": 2
    },
    {
      "id": "4",
      "type": "text",
      "name": "Description",
      "value": "My issue",
      "parent_id": 2
    }
  ]
}

Запись:

"value": {
  "fields": [
    {
      "id": 4,
      "value": "It is not an issue"
    }
  ]
}

form_link Чтение:

"value": {
  "task_ids": [1573],
  "subject": "Expense report"
}

Запись:

"value": {
  "task_ids" : [1753]
}

project (устарело, только для чтения) Чтение:

"value": {
  "projects: [
    {
      "id": 1,
      "name": "Root Project"
    },
    {
      "id": 3,
      "name": "Child Project",
      "parent": {
        "id": 2,
        "name": "Another root project"
      }
    }
  ]
}

Дополнительная информация о поле

Объект info может содержать 2 ключа для всех типов полей:

required_step — указывает номер шага, начиная с которого поле становится обязательным для заполнения;
immutable_step — указывает номер шага, начиная с которого пользователь не может изменять значение поля. Нумерация шагов начитается с единицы.

Также объект info может содержать информацию о user_id из поля типа Код и о том, что поле включается в заголовок задачи по форме.

Помимо указанных ключей, объект info в зависимости от типа будет содержать один из дополнительных ключей, описанных ниже:

Тип	Ключ	Пример
multiple_choice	options	"options": [ { "choice_id": 0, "choice_value": "Not Set" }, { "choice_id": 1, "choice_value": "Yes", "fields": { "id": 4, "type": "text", "name": "Reason", "parent_id": 3, } }, { "choice_id": 2, "choice_value": "No", }, { "choice_id": 3, "choice_value": "MayBe", "deleted": true } ]
catalog	catalog_id	"catalog_id": 165
table	columns	"columns": [ { "id": 9, "type": "money", "name": "Amount", "parent_id": 5, }, { "id": 6, "type": "date", "name": "Date", "parent_id": 5, } ]
title	fields	"fields": [ { "id": 9, "type": "money", "name": "Amount", "parent_id": 5, }, { "id": 6, "type": "date", "name": "Date", "parent_id": 5, } ]
form_link	form_id	"form_id": 1453
number	decimal_places	"decimal_places": 5
catalog	multiple_choice	"multiple_choice": true

Формат полей формы

Типы полей и примеры

Простые типы

Составные типы

Дополнительная информация о поле

Была ли эта статья полезной?