HTTP API контекстных переменных

Общие сведения

Класс действия: ru.bgcrm.core.contextVariable.struts.action.ContextVariableAction.

Базовый путь: /user/contextVariable.do. Ответы используют стандартную оболочку bgcrm: status, message, data, eventList.

Доступны две операции:

  • catalog — ключи и человекочитаемые названия переменных;

  • values — значения выбранных ключей для конкретного объекта.

Оба действия объявлены с allowAll="1". Отдельное право в редакторе прав отсутствует, однако маршрут /user/ требует авторизованную сессию.

API не является границей объектной авторизации. Действие не проверяет, разрешено ли пользователю открывать переданный процесс, контрагента или договор. Среди штатных переменных есть bgbilling-commonContract:password, поэтому не передавайте в общий интерфейс произвольные objectType и objectId без собственной проверки доступа.

Каталог

Метод действия: catalog

URL: /user/contextVariable.do?action=catalog

Параметр Обязателен Описание

objectType

Да

Тип объекта из каталога

processTypeId

Нет

ID типа процесса; используется только для списка параметров процесса, без него возвращаются только постоянные переменные

Сокращённый пример с условными данными:

/user/contextVariable.do?action=catalog&objectType=process&processTypeId=11167
{
  "status": "ok",
  "message": "",
  "data": {
    "variables": [
      {
        "id": "process:id",
        "title": "Процесс: ID"
      },
      {
        "id": "process:title",
        "title": "Процесс: название"
      },
      {
        "id": "process:param5503",
        "title": "Параметр: Адрес"
      }
    ]
  },
  "eventList": []
}

Постоянные переменные идут первыми в порядке объявлений билдера, параметры — после них в порядке, который вернули кэши типа объекта.

Для неизвестного objectType возвращается пустой список. Для process без существующего processTypeId возвращаются только постоянные переменные.

Значения

Метод действия: values

URL: /user/contextVariable.do?action=values

Параметр Обязателен Описание

objectType

Да

Тип объекта

objectId

Да

Положительный ID существующего объекта

keys

Нет

Ключи через запятую; пустой список даёт пустой объект values

Сокращённый пример с условными данными:

/user/contextVariable.do?action=values&objectType=process&objectId=127&keys=process:id,process:title,process:param5503
{
  "status": "ok",
  "message": "",
  "data": {
    "values": {
      "process:id": "127",
      "process:title": "Заявка по адресам",
      "process:param5503": "г. Уфа, ул. Ленина, д. 1"
    }
  },
  "eventList": []
}

Неизвестный или незаполненный ключ не включается в values. Это отличается от шаблонизатора, который заменяет неизвестную переменную пустой строкой.

Дубли в keys удаляются. Даже если запрошен один ключ, ContextVariableValuesQuery сначала строит полный контекст объекта и только затем вызывает поставщики выбранных значений.

Ошибки контракта:

Ситуация Результат

Пустой objectType

Ошибка «Не указан тип объекта»

objectId отсутствует, равен нулю или отрицателен

Ошибка «Не указан объект»

Объект известного типа не найден

BGMessageException с типом и ID объекта

Неизвестный тип

Значения только из ContextVariablesBuildEvent; без слушателя — пустой объект

Фронтовый репозиторий

ContextVariableRepository экспортируется глобальным тезаурусом и описан типами IContextVariableRepository.

const repository = new ContextVariableRepository().use('data')

const {variables} = await repository.catalog({
  objectType: 'process',
  processTypeId: 11167
})

const {values} = await repository.values({
  objectType: 'process',
  objectId: 127,
  keys: 'process:id,process:title'
})

Файлы реализации:

  • frontend/src/main/resources/webapps/js/thesaurus/repositories/core/contextVariable/ContextVariableRepository.js;

  • frontend/src/main/resources/webapps/ts/types/repositories/core/context-variable/index.ts.

На текущий момент ядро предоставляет репозиторий, но отдельного штатного Vue-компонента выбора контекстной переменной нет. Потребитель сам решает, как показать каталог и куда подставить ключ.