Справка

Формы

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

Форма — это набор полей и правил маршрутизации, которые описывают бизнес-процесс.

Типичным примером бизнес-процесса может быть возмещение сотруднику командировочных расходов.

Поля формы — это набор данных, с которым работает участник бизнес-процесса.

Например, в процессе возмещения командировочных расходов такими полями могут быть "Фамилия сотрудника", "Дата командировки", "Сумма расходов к возмещению" и "Подтверждающие документы".

Маршрутизация — это набор правил, которые описывают движение документа (задачи) в бизнес-процессе. Обычно маршрутизация разбита на этапы. Каждому этапу можно задать название, а так же правила, по которым на этот этап добавляются участники.

Например, возмещение командировочных расходов можно разбить на такие этапы: "Заполнение", на котором автор заявки заполняет поля и прикладывает подтверждающие документы, "Согласование", на котором в зависимости от суммы могут стоять разные пользователи и "Бухгалтерия", на котором стоит бухгалтер для возмещения денежных средств работнику.

Подробнее о формах можно прочитать в справке.

Методы

GET /forms

Метод возвращает описание всех форм, в которых текущий пользователь является менеджером или участником.

GET https://api.pyrus.com/v4/forms

Тело ответа

{
  "forms": [
    {
      "id": 36120,
      "name": "Payments",
      "steps": {
        "1": "Manager",
        "2": "Accounting",
        "4": "CEO"
      },
      "fields": [
        {
          "id": 1,
          "type": "text",
          "name": "Purpose",
          "info": {
            "required_step": 1,
            "immutable_step": 1
          }
        },
        {
          "id": 2,
          "type": "money",
          "name": "Amount",
        },
        {
          "id": 3,
          "type": "catalog",
          "name": "Payment type",
          "info": {
            "catalog_id": 277
          }
        },
        {
          "id": 4,
          "type": "table",
          "name": "Payment Schedule",
          "info": {
            "columns": [
              {
                "id": 5,
                "type": "date",
                "name": "Date",
                "parent_id": 4
              },
              {
                "id": 6,
                "type": "money",
                "name": "Amount",
                "parent_id": 4
              }
            ]
          }
        }
      ],
      "deleted_or_closed": false,
      "print_forms": [
        {
          "print_form_id": 2633,
          "print_form_name": "templateA.docx"
        },
        {
          "print_form_id": 2645,
          "print_form_name": "templateB.xlsx"
        }
      ],
      "folder": [folder1]
    }
  ]
}

curl

curl -X GET \
  'https://api.pyrus.com/v4/forms/' \
  -H 'Authorization: Bearer <YOUR_ACCESS_TOKEN>' \
  -H 'Content-Type: application/json'

Полный список типов полей формы находится в разделе Формат полей формы.

GET /forms/{form-id}

Метод возвращает описание формы с указанным id.

GET https://api.pyrus.com/v4/forms/36120

Тело ответа

{
  "id": 36120,
  "name": "Payments",
  "steps": {
	"1": "Manager",
	"2": "Accounting",
	"4": "CEO"
  },
  "fields": [
	{
	  "id": 1,
	  "type": "text",
	  "name": "Purpose",
	  "info": {
		"required_step": 1,
		"immutable_step": 1
	  }
	},
	{
	  "id": 2,
	  "type": "money",
	  "name": "Amount",
	},
	{
	  "id": 3,
	  "type": "catalog",
	  "name": "Payment type",
	  "info": {
		"catalog_id": 277
	  }
	},
	{
	  "id": 4,
	  "type": "table",
	  "name": "Payment Schedule",
	  "info": {
		"columns": [
		  {
			"id": 5,
			"type": "date",
			"name": "Date",
			"parent_id": 4
		  },
		  {
			"id": 6,
			"type": "money",
			"name": "Amount",
			"parent_id": 4
		  }
		]
	  }
	}
  ],
  "deleted_or_closed": false,
  "print_forms": [
	{
	  "print_form_id": 2633,
	  "print_form_name": "templateA.docx"
	},
	{
	  "print_form_id": 2645,
	  "print_form_name": "templateB.xlsx"
	}
  ],
  "folder": [folder1]
}

curl

curl -X GET \
  'https://api.pyrus.com/v4/forms/36120' \
  -H 'Authorization: Bearer <YOUR_ACCESS_TOKEN>' \
  -H 'Content-Type: application/json'

Полный список типов полей формы находится в разделе Формат полей формы.

GET /forms/{form-id}/register

Метод возвращает список задач, созданных по форме. В ответе возвращаются только общая информация о задаче, список заполненных полей формы и номер этапа, на котором находится задача. Для получения всех комментариев к задаче воспользуйтесь методом GET /tasks/{task-id}.

GET https://api.pyrus.com/v4/forms/1423/register
?fld2=gt10000,LT15000
&fld1=it%20conference%20in%20Amsterdam
&fld3=277
&include_archived=y
&sort=tsk

Тело ответа

{
  "tasks": [{
    "id": 11610,
    "create_date": "2017-08-20T12:31:14Z",
    "last_modified_date": "2017-08-23T10:20:11Z",
    "current_step": 1,
    "fields": [
      {
        "id": 1,
        "type": "text",
        "name": "Purpose",
        "value": "IT conference in Amsterdam"
      },
      {
        "id": 2,
        "type": "money",
        "name": "Amount",
        "value": 10306.25
      },
      {
        "id": 3,
        "type": "catalog",
        "name": "Payment type",
        "value": {
          "item_id": 845,
          "headers": [
            "Payment types"
          ],
          "values": [
            "IT Conference"
          ]
        }
      },
      {
        "id": 4,
        "type": "table",
        "name": "Payment Schedule",
        "value": [
          {
            "row_id": 0,
            "cells": [
              {
                "id": 5,
                "type": "date",
                "name": "Date",
                "value": "2017-08-26",
                "parent_id": 4,
                "row_id": 0
              },
              {
                "id": 6,
                "type": "money",
                "name": "Amount",
                "value": 10000,
                "parent_id": 4,
                "row_id": 0
              }
            ]
          },
          {
            "row_id": 1,
            "cells": [
              {
                "id": 5,
                "type": "date",
                "name": "Date",
                "value": "2017-08-27",
                "parent_id": 4,
                "row_id": 1
              },
              {
                "id": 6,
                "type": "date",
                "name": "Amount",
                "value": 306.25,
                "parent_id": 4,
                "row_id": 1
              }
            ]
          }
        ]
      }
    ]
  }]
}

curl

curl -X GET \
  'https://api.pyrus.com/v4/forms/327874/register?fld2=gt10000,lt15000&fld1=IT%20conference%20in%20Amsterdam&fld3=277&include_archived=y&sort=tsk' \
  -H 'Authorization: Bearer <YOUR_ACCESS_TOKEN>' \
  -H 'Content-Type: application/json'

Также метод позволяет производить текстовый поиск в реестре в точном соответствии со значением поля формы. В этом случае запрос будет иметь вид:

GET  https://api.pyrus.com/v4/forms/1423/register
?fld2=gt10000,LT15000
&fld1=eq.it%20conference%20in%20Amsterdam
&fld3=277
&include_archived=y
&sort=tsk

Тело ответа

{
    "fld2": "gt10000,lt15000",
    "fld3": "eq277",
    "fld1": "IT conference",
    // или "fld1": "eq.IT conference in Amsterdam",
    "include_archived": "y",
    "sort":"tsk" 
    
}

curl

curl -X GET \
'https://api.pyrus.com/v4/forms/327874/register?fld2=gt10000,lt15000&fld1=eq.IT%20conference%20in%20Amsterdam&fld3=277&include_archived=y&sort=tsk' \
 -H 'Authorization: Bearer <YOUR_ACCESS_TOKEN>' \
 -H 'Content-Type: application/json'

Если длины адресной строки недостаточно для передачи всех параметров фильтрации, вы можете вызвать данный метод с помощью HTTP-метода POST. Параметры указываются в формате JSON в теле запроса:

{
    "fld2": "gt10000,lt15000",
    "fld1": "IT conference in Amsterdam",
    "fld3": "eq277",
    "include_archived": "y",
    "sort":"tsk"
    
}

Параметры

stepsНомер этапа, можно указать несколько этапов через запятую.
task_idsНомера задач, которыми ограничится выборка задач реестра формы.
include_archivedУкажите "y", если хотите включить в результат архивные задачи.
field_idsИдентификаторы полей, значения которых будут возвращены в ответе. Несколько значений идентификаторов указываются через запятую. Данный параметр влияет на порядок возвращаемых полей в случае формата csv. Если параметр не передан, возвращаются все поля, если параметр передан, но не содержит идентификаторов, то в ответе поля формы будут отсутствовать.

fld{field_id}

Фильтр задач по полю:

  • Точное вхождение: fld1=Payment**
  • Точное соответствие (включая пробелы): fld1=eq.it%20conference%20in%20Amsterdam
  • Входит в список: fld14=15,20
  • Не заполнено: fld14=empty
  • Больше или равно: fld3=gt15
  • Меньше или равно: fld5=lt2017-01-01
  • В диапазоне: fld3=gt15.5,lt21

Операторы lt и gt применимы только к полям типа date, money, number, due_date, creation_date.

Оператор вхождения в список применим к полям типа multiple_choice, catalog, person, author, form_link.

Оператор empty применим только для полей типа multiple_choice, catalog, person, author, form_link.

Для составных типов в качестве значения фильтрации передается только идентификатор записи.

Более подробная информация о типах полей находится в разделе Формат полей формы.

Фильтрация для полей с типом file, time, title, project, note не поддерживается.

** Следует учесть, что поиск по точному соответствию не учитывает служебные слова (частицы, союзы, предлоги)

id

Фильтр по идентификатору задачи:

  • Точное соответствие: id=12345
  • Входит в список: id=12345,12450
  • Больше чем: id=gt12345
  • Меньше чем: id=lt12450
  • В диапазоне: id=gt12345,lt12450
sortСортировка по идентификатору задачи в порядке возрастания: sort=id

due_filter

Фильтр задач по просроченности:

  • overdue: задачи, в которых истек общий срок выполнения.
  • overdue_on_step: задачи, в которых в настоящий момент просрочен текущий этап.
  • past_due: задачи, в которых истек общий срок выполнения или срок текущего этапа.
  • задачи, в которых истек срок выполнения на указанных этапах:{ “overdue_steps”: [1,2,3] }
formatУкажите "csv", если хотите получить результат в формате csv. По умолчанию формат ответа — json.
delimiterРазделитель полей в csv файле. По умолчанию — ",".
encodingКодировка ответа. По умолчанию — "utf-8".
simple_formatУкажите "y", если хотите получить csv в упрощенном формате.Все переносы строк будут заменены на пробелы.
modified_beforeЗадачи, измененные до указанной даты по UTC (включительно).Формат: YYYY-MM-DDThh:mm:ssZ
modified_afterЗадачи, измененные после указанной даты по UTC (включительно).Формат: YYYY-MM-DDThh:mm:ssZ
created_beforeЗадачи, созданные до указанной даты по UTC (включительно).Формат: YYYY-MM-DDThh:mm:ssZ
created_afterЗадачи, созданные после указанной даты по UTC (включительно).Формат: YYYY-MM-DDThh:mm:ssZ
closed_beforeЗадачи, завершенные до указанной даты по UTC (включительно).Формат: YYYY-MM-DDThh:mm:ssZ
closed_afterЗадачи, завершенные после указанной даты по UTC (включительно). Формат: YYYY-MM-DDThh:mm:ssZ
item_countМаксимальное количество задач в ответе. Значение должно быть больше 0 и меньше или равно 20000.

Доступы к форме

Вы можете редактировать права доступа к форме. Подробнее о доступах к форме можно прочитать в справке.

Формат уровней прав доступа:

  • "administrator" — администратор формы;
  • "manager" — менеджер формы (без условий);
  • "restricted_manager" — менеджер части процесса;
  • "member" — участник формы;
  • "none" — без доступа (используется только при изменении прав доступа, чтобы лишить пользователя доступа к форме).

GET /forms/{form-id}/permissions

Метод позволяет получить список доступов пользователей к форме.

GET https://api.pyrus.com/v4/forms/36120/permissions

Тело ответа

{
    "permissions": {
        "1733": "manager",
        "1731": "administrator"
    }
}

curl

curl -X GET \
  'https://api.pyrus.com/v4/forms/327874/permissions' \
  -H 'Authorization: Bearer <YOUR_ACCESS_TOKEN>' \
  -H 'Content-Type: application/json'

POST /forms/{form_id}/permissions

Чтобы изменить права доступа у пользователя, в теле запроса нужно указать новые права для пользователя. Формат тела ответа такой же, как и в получении списка доступов для формы.

Ограничения:

  • нельзя добавлять новых администраторов в форму;
  • нельзя добавлять менеджеров формы по условию.
POST https://api.pyrus.com/v4/forms/36120/permissions

Тело запроса

{
    "permissions": {
        "1733": "member"
    }
}

Тело ответа

{
    "permissions": {
        "1733": "member",
        "1731": "administrator"
    }
}

curl

curl -X POST \
  https://api.pyrus.com/v4/forms/36120/permissions \
  -H 'Authorization: Bearer <YOUR_ACCESS_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
    "permissions": {
        "1733": "member"
    }
}'

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