Перейти на сайт Case.one

Группы методов для работы с объектами

Методы для работы с объектами, их классами и типами, а также папками и проектами распределены по следующим группам:

  • Классы объектов — ObjectClasses
  • Типы объектов — ObjectTypes
  • Папки дел/объектов — Folders
  • Проекты — Projects
  • Объекты — Objects
  • Проекты — Projects
  • Роли в деле — RolesInCase

По всем методам работы с объектами в V1 доступны аналогичные методы, которые выполняются только для дел (методы V1 полностью перенесены в методы V2).

Специфика работы с методами API, которые предназначены для работы с объектами и делами, а также с классами и типами объектов, паками, проектами и участниками в деле:

  1. Если у пользователя права на Просмотр или нет прав на блок в объекте/деле, то при создании/редактировании такого объекта/дела через публичный API, заполняя/редактируя блок, в результате будет получен ответ 201, а отправленные значения игнорируются.
  2. Заполнение кастомных полей:
    • В методах API по работе с объектом/делом доступно заполнить кастомные поля дела/объекта, передав JSON-объект в формате — тег поля : значение
    • Заполнение системных полей таким образом не предусмотрено
    • Система позволяет работать с объектами любого класса
    • Если у поля нет тега, то в качестве тега используется Id поля (данное значение не отображается на UI)
    • В методах публичного API v1 и v2 по работе с объектами выполняется проверка формата кастомных полей, что позволяет корректно заполнять поля карточки дела и избежать ошибок при формировании отчетов по этим полям
  3. Таблицы объектов — в следующих методах API отсутствуют блоки с типом Таблица в ответе:
    • ObjectTypes/GET/api/v1/caseTypes/{id}
    • ObjectTypes/GET/api/v1/objectTypes/{id}
    • ObjectTypes/GET/api/v2/caseTypes/{id}
    • ObjectTypes/GET/api/v2/objectTypes/{id}
  4. Проверка на дубли — при создании или редактировании объектов через публичный API в запросе присутствует параметр CheckForDuplicates для проведения валидации данных объекта по правилам определения дубликатов:
    • Параметр CheckForDuplicates доступен в следующих методах поддерживаемых версий:
      • Создание объекта
      • Обновление объекта (PUT)
      • Редактирование объекта: (PATCH)
      • Архивация объекта
      • Восстановление объекта из архива
    • При установке значения False в параметре CheckForDuplicates:
      • Валидация данных объекта не выполняется
      • Объект создается / редактируется через API без валидации атрибутов предаваемого объекта по правилам определения дубликатов
    • Если установлено значения True в параметре CheckForDuplicates при передаче запроса вышеуказанными методами, валидация атрибутов предаваемого объекта по правилам определения дубликатов работает по следующему по принципу:
      • Проверяемый объект валидируются по правилу определения дубликата соответствующего типа объектов:
        • Если предаваемый объект не определен как дубликат — объект создается, изменения в объекте сохраняются
        • Если предаваемый объект определен как дубликат — объект не создается, изменения в объекте не сохраняются и будет отправлен ответ об ошибке с полями (см. в таблице ниже)
      • Валидация проверяемого объекта по правилам определения дубликатов не учитывает флаг Запрещать создавать дубликаты — вне зависимости от установки флага при передаче запроса по API, если передаваемый объект определен как дубликат, он не будет создан, все изменения не будут сохранены (процесс создания и редактирования объектов соответствует стандартному механизму):
        • Если правило определения дубликатов не настроено для типа объекта
        • Если правило определения дубликатов не настроено для типа объекта, но в атрибуте запроса CheckForDuplicates передано значение True, параметр игнорируется
        • Если настроенное правило стало невалидным из-за удаления поля, участвующего в правиле, валидация по такому правилу не запускается
Название поляОписаниеЗначения поля
ErrorНазвание ошибкиНевозможно создать дубликат.
ErrorTypeТип ошибкиConflict.
ConflictMessageОписание конфликтаВ Системе уже есть объекты с похожим набором данных (список уникальных полей из правила определения дубликатов).
ConflictObjectsМассив идентификаторов объектов, по которым проверяемый объект определен как дубликатМассив идентификаторов.

Классы объектов — ObjectClasses

Доступные версии: V1, V2:

  • GET /api/v2/objectClasses/{id} — метод позволяет получить класс объекта по идентификатору, в результате будет возвращена подробная информация по указанному классу объекта.
  • GET /api/v2/objectClasses — метод позволяет получить все классы объектов:
    • Доступна фильтрация по классу объекта
    • Список классов выводится объектов без паджинации

Типы объектов — ObjectTypes

Доступные версии: V1, V2:

  • GET /api/v2/objectTypes/{id} (или /api/v2/caseTypes/{id}) — метод позволяет получить тип объекта по идентификатору, в результате будет возвращена подробная информация по указанному типу объекта/дела (тип объекта/дела содержит метаданные объектов/дел), включая информацию о классе объекта.
  • GET /api/v2/objectTypes (или /api/v2/caseTypes) — метод позволяет получить все типы объектов:
    • В выходных данных отображается статус типа объекта/дела: активен/ удален
    • Доступна фильтрация по классу объекта

Папки дел/объектов — Folders

Доступные версии: V1, V2:

  • GET /api/v2/folders/{id} — метод позволяет получить указанную папку, которая содержит объекты, дела и проекты, по идентификатору.
  • GET /api/v2/folders — метод позволяет получить список папок:
    • Доступна фильтрация по классу объекта
    • В API V1:
      • В выходных данных нельзя запросить папки с учетом вложенности
      • Выходные данные не содержат информацию о вложенности
    • В выходных данных папки отсортированы по алфавиту (паджинация по 100 значений)
    • Метод позволяет возвращать:
      • Дочерние папки по указанному Id папки родителя
      • Папки по указанному имени папки — поиск выполняется по вхождению, при этом каждая папка возвращается со всеми вложенными папками
      • Структуру папок и вложенных подпапок с учетом прав (числовое значение)
    • Особенности поиска и паджинации:
      • Если PageSize — 20, будут возвращены первые 20 папок и все подпапки в них
      • Если поиск по имени вернет 2 папки, причем одна папка является подпапкой другой, вернутся список из 2-х папок (включая их иерархию)
      • Если указаны и Id папки, и Название, поиск выполняется по названию папки, среди папок, являющихся дочерними для папки, Id которой указано в запросе

Пример:  

Папка 1

  • Папка 1.1
  • Папка 1.2
    • Папка 1.2.1
      • Папка 1.2.1.1
      • Папка 1.2.1.2
    • Папка 1.2.2.
      • Папка 1.2.2.1

При поиске по Папка 1 в результате будет вся описанная выше структура.

При поиске по Папка 1.2.1 в результате будет:

  • Папка 1.2.1
    • Папка 1.2.1.1
    • Папка 1.2.1.2

Проекты — Projects

Доступные версии: V1, V2:

  • GET /api/v2/projects/{id} — метод позволяет получить указанный проект, который содержит объекты/дела, по идентификатору.
  • GET /api/v2/projects — метод позволяет получить список проектов для дел/объектов и их положение в папках:
    • Доступна фильтрация по папке и по классу объекта
    • В выходных данных проекты отсортированы по алфавиту (паджинация по 100 значений)

Объекты — Objects

Доступные версии: V1, V2, V3.

В публичном API получения, создания и редактирования объекта доступно использование полей с типом Объект-Пользователь.

API V2 (V1):

  • POST /api/v2/objects — метод позволяет создать объект с блоками:
    • Создание объекта должно выполняться одним запросом — т.е. в одном запросе сразу указывается тип объекта, проект и папка для объекта и данные из карточки объекта
    • Метод не относится к созданию дела из клиентского запроса
    • Возможно заполнение полей объекта по внешнему идентификатору (External ID):
      • Идентификатор позволяет заполнить одно или несколько полей объекта без учета структуры объекта — т.е. доступно передать значение нескольких полей в объекте с их External ID и в объекте заполнятся только эти значения (остальные значения полей не будут удаляться)
      • Если в блоке есть одно или несколько заполненных полей, при редактировании любого поля в этом блоке все обязательные поля в этом блоке также должны быть заполнены
      • Для заполнения мультистрок/мультиблока значения полей передаются в виде массива
  • PUT /api/v2/objects/{id} — метод позволяет обновить объект с блоками по идентификатору:
    • В методе есть необязательные параметры, которые позволяют проверить актуальность сохраненной версии карточки объекта/дела при редактировании в многопользовательском режиме:
      • Version — версия объекта (integer($int64))
      • IsVersionEnabled — проверить версию объекта (boolean)
    • Работа метода зависит от этих необязательных параметров:
      • Если параметры не переданы, методы выполняются как раньше
      • Если параметры переданы, сначала выполняется проверка на актуальность версии дела/объекта — если передана не актуальная версия, обновление дела/объекта не выполняется, возвращается ошибка
  • PATCH /api/v2/objects/{id} — метод позволяет изменить объект с блоками по идентификатору:
    • В методе доступно удалить сразу весь блок и/или строку, избегая изменения массива значений каждого поля:
      • Явно указывается порядковый номер мультистроки и/или мультиблока в деле, которые необходимо удалить
      • Доступно удаление пустой строки и/или блока, в котором есть поле формата Чекбокс
    • В методе есть необязательные параметры, которые позволяют проверить актуальность сохраненной версии карточки объекта/дела при редактировании в многопользовательском режиме:
      • Version — версия объекта (integer($int64))
      • IsVersionEnabled — проверить версию объекта (boolean)
    • Работа метода зависит от этих необязательных параметров:
      • Если параметры не переданы, методы выполняются как раньше
      • Если параметры переданы, сначала выполняется проверка на актуальность версии дела/объекта — если передана не актуальная версия, обновление дела/объекта не выполняется, возвращается ошибка
  • GET /api/v2/objects/{id} — метод позволяет получить объект по идентификатору, включая информацию обо всех заполненных полях в объекте:
    • В выходных параметрах отображается параметр DocumentFolderId, указывающий на корневую папку дела
    • Значение null приходит только для полей, которые не определены
  • GET /api/v2/objects и GET /api/v2/cases — методы позволяют получить список объектов/дел с папками и проектами:
    • Доступна фильтрация по последней дате изменения объекта/дела, дате создания, ответственному, статус (архив/в работе), папке, проекту, типу объекта, классу объекта
    • В выходных данных объекты отсортированы по алфавиту и далее – по дате создания, паджинация по 100 значений
    • В выходных данных содержится информация: тип объекта, ответственный, дата создания, статус, проект и папка
    • В выходных параметрах отображается параметр DocumentFolderId, указывающий на корневую папку дела
    • Доступно выполнять поиск по пустым или непустым значениям — в блоке Filters доступен необязательный атрибут IsEmpty (аналогично решению в Отчетах) с возможными атрибутами:
      • null — не используется фильтрация
      • true — фильтрация по пустым полям
      • false — фильтрация по заполненным полям

Пример запроса с заполненным блоком Filters:

{
"ObjectClassId": "5a0f18af-d677-ec11-80e6-000d3af7ae73",
 "Filters": [
   {
    "FieldTag": "td_tag1",
    "IsEmpty": false,
   }],
 "IsFormattedTextEnabled": true,
 "Page": 1,
 "PageSize": 1
}

Если используется конструкция "IsEmpty": false, невозможно использовать другие способы фильтрации (будет ошибка в ответе):

"SearchValues": [
 "string"
 ],
 "BeginValue": "string",
 "EndValue": "string"

Например, при использовании конструкции:

"Filters": [
 {
   "FieldId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
   "FieldTag": "tag1",
   "IsEmpty": true,
   "SearchValues": [
     "4"
    ], }]
  • POST /api/v2/objects/{id}/archive и POST /api/v2/cases/{id}/archive — методы позволяют заархивировать объект/дело.
  • POST /api/v2/objects/{id}/restore и POST /api/v2/cases/{id}/restore — методы позволяют восстановить объект/дело из архива.
  • DELETE /api/v2/objects/{id} и DELETE /api/v2/cases/{id} — методы позволяют удалить объект/дело (удаление доступно только для архивных объектов/дел).
  • POST /api/v2/objects/{id}/participants и POST /api/v2/cases/{id}/participants — методы позволяют добавить участника в объект/дело и при необходимости установить роль участнику в объекте/деле. Необходимы права Редактирование на объект/дело и Просмотр на участников.

API V3 — в методах API V3 доступно выгрузить объекты любого типа с указанием параметров (например, в качестве параметров могут выступать теги):

  • POST /api/v3/objects/GetObjects — метод позволяет получить список объектов, среди параметров могут быть теги, и должна быть возможность указывать несколько значений для нескольких тегов. Доступно получить список объектов с фильтрацией по ответственному, где в качестве значения фильтра указана группа пользователей.
  • POST /api/v3/objects/GetCases — метод позволяет получить список дел, среди параметров могут быть теги, и должна быть возможность указывать несколько значений для нескольких тегов. Доступно получить список дел с фильтрацией по ответственному, где в качестве значения фильтра указана группа пользователей.
  • POST /api/v3/objects/GetTableObjects — метод позволяет получить список объектов, которые находятся в таблице, с информацией по каждому объекту:
    • Метод позволяет получить по идентификатору блока:
      • Список объектов, которые находятся в таблице
      • Список данных по каждому объекту
    • В одном запросе доступно получить данные по одной таблице
    • Если идентификатор блока таблицы указан некорректно или не существует, в ответе возвращается ошибка
    • Порядок значений для мультиполей может не совпадать с порядком полей, которые выведены в таблице
    • Доступно получить список дел с фильтрацией по ответственному, где в качестве значения фильтра указана группа пользователей

Во входящих параметрах метода:

  • Обязательный параметр — ID блока таблица.
  • Необязательные параметры:
    • ID объекта, в котором вложена таблица
    • Поле, по которому производится сортировка данных в таблице
    • Инлайн фильтры по таблице
    • Полнотекстовый поиск

На выходе возвращается массив, содержащий список объектов с паджинацией:

  • Идентификатор объекта.
  • Значение кастомных полей:
    • В формате: “tag”: “string”, если у поля есть тег
    • В формате: “id”: “string”, если у поля нет тега
    • Для мультиполей (в обычном блоке, в мультиблоке) передается один массив значений
  • Для системных полей вместо Id передается название поля в следующем соответствии:
    • Название — Project_Name
    • Номер — Project_FullNumber
    • Время создания — Project_CreationDate_Time
    • Дата создания — Project_CreationDate
    • Клиент — Project_Client_Name
    • Описание — Project_Description
    • Ответственный — Project_Responsible
    • Стадия — Project_Stage_Name
    • Статус — Project_IsArchive
    • Тип — Project_ProjectType_Name

Связанные объекты — RelatedObjects

В качестве основы методов взяты методы внутреннего API в упрощенном виде:

  • GET /api/v2/objects/{objectId}/relatedObjects — метод позволяет получить список связанных объектов по идентификатору дела/объекта (права на дело должны быть Просмотр или выше).
  • POST /api/v2/objects/{objectId}/relatedObjects — метод позволяет создать связанный объект (права на дело должны быть Редактирование или выше).
  • DELETE /api/v2/objects/{objectId}/relatedObjects — метод позволяет удалить объект из списка связанных объектов в выбранном объекте (права на дело должны быть Редактирование или выше).

Если уровня прав не хватает или отсутствуют права, отобразится ошибка. Не проверяются права на добавленные объекты.

Доступная версия — V2.

Роли в деле — RolesInCase

Доступные версии: V1, V2:

  • GET /api/v2/rolesInCase/{id} — метод позволяет получить подробную информацию об указанной роли в деле/объекте по идентификатору.
  • GET /api/v2/rolesInCase — метод позволяет получить список всех ролей в деле/объекте.