Обзор

REST API дает доступ ко всем основным интерфейсам движка.

Структура

Справочник описывает все методы REST API. Для каждого метода приводятся:

  • Описание

  • HTTP-глагол и URL

  • Возможные параметры запроса (query), пути (path) или тела сообщения (message body)

  • Подробное описание содержимого ответа

  • Возможные коды ответа

  • Краткий пример запроса и ответа

Использование движка

Описанные методы работают с процессным движком по умолчанию, который возвращает доступный сервис ProcessEngineProvider.

Чтобы обратиться к другому движку, добавьте к пути метода префикс /engine/{name} (если не указано иное). Здесь {name} означает имя процессного движка, которое возвращает ProcessEngine#getName(), например /engine/myEngineName/task.

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

Для каждого метода в справочнике перечислены возможные коды HTTP-статуса. Описаны не все причины ошибок при обработке запроса: например, большинство запросов не выполнится, если недоступна база данных. Все такие недокументированные ошибки возвращаются как ошибка HTTP 500.

У каждой ошибки есть тело ответа в формате JSON такого вида:

  {
    "type" : "SomeExceptionClass",
    "message" : "a detailed message",
    "code" : 10000
  }

Исключения авторизации

Если аутентифицированный пользователь обращается к ресурсу без нужных прав, возвращается код статуса 403 Forbidden. Подробности приводятся в теле ответа.

Тип

AuthorizationException

Тело ответа

{
 "type" : "AuthorizationException",
 "message" : "The user with id 'jonny' does not have 'DELETE' permission on resource 'Mary' of type 'User'.",
 "code" : 0,
 "userId" : "jonny",
 "permissionName" : "DELETE",
 "resourceName" : "User",
 "resourceId" : "Mary"
}

Исключения валидации миграции

Если план миграции с одной версии определения процесса на другую некорректен, выбрасывается исключение миграции. Это исключение валидации плана миграции (migration plan validation exception), если некорректен сам план, например содержит некорректную инструкцию. Или исключение валидации мигрируемого экземпляра процесса (migrating process instance validation exception), если план миграции нельзя применить к конкретному экземпляру процесса, например активное активити не сопоставлено в плане миграции.

Исключения валидации плана миграции

Тип

MigrationPlanValidationException

Тело ответа

JSON-объект со следующими свойствами:

Имя Тип Описание

type

String

Тип исключения, здесь MigrationPlanValidationException.

message

String

Сообщение об ошибке.

code

Number

По коду клиентское приложение может распознать ошибку автоматически. Значения встроенных кодов и способ добавить собственные коды описаны в Руководстве пользователя.

validationReport

Object

JSON-объект с подробностями обо всех найденных ошибках валидации. Его свойства описаны ниже.

Каждый объект отчёта о валидации содержит следующие свойства:

Имя Тип Описание

instructionReports

Array

JSON-массив отчетов о валидации отдельных инструкций. Каждый объект отчета состоит из некорректной инструкции instruction и массива failures, содержащего сообщения валидации для этой инструкции.

Пример

{
  "type": "MigrationPlanValidationException",
  "message": "ENGINE-23001 Migration plan for process definition 'invoice:1:8aa1533c-23e5-11e6-abb7-f6aefe19b687' to 'invoice:2:8accd012-23e5-11e6-abb7-f6aefe19b687' is not valid:\n\t Migration instruction MigrationInstructionImpl{sourceActivityId='approveInvoice', targetActivityId='assignApprover', updateEventTrigger='false'} is not valid:\n\t\tActivities have incompatible types (UserTaskActivityBehavior is not compatible with DmnBusinessRuleTaskActivityBehavior)\n",
  "code" : 0,
  "validationReport": {
    "instructionReports": [
      {
        "instruction": {
          "sourceActivityIds": [
            "approveInvoice"
          ],
          "targetActivityIds": [
            "assignApprover"
          ],
          "updateEventTrigger": false
        },
        "failures": [
          "Activities have incompatible types (UserTaskActivityBehavior is not compatible with DmnBusinessRuleTaskActivityBehavior)"
        ]
      }
    ]
  }
}

Исключения валидации мигрируемого экземпляра процесса

Тип

MigratingProcessInstanceValidationException

Тело ответа

JSON-объект со следующими свойствами:

Имя Тип Описание

type

String

Тип исключения, здесь MigratingProcessInstanceValidationException.

code

Number

По коду клиентское приложение может распознать ошибку автоматически. Значения встроенных кодов и способ добавить собственные коды описаны в Руководстве пользователя.

message

String

Сообщение об ошибке.

validationReport

Object

JSON-объект с подробностями обо всех найденных ошибках валидации. Его свойства описаны ниже.

Каждый объект отчёта о валидации содержит следующие свойства:

Имя Тип Описание

processInstanceId

String

Идентификатор экземпляра процесса, который нельзя мигрировать по этому плану миграции.

failures

Array

Массив общих сообщений об ошибках, не связанных с конкретным активити или переходом.

activityInstanceValidationReports

Array

Массив JSON-объектов, описывающих отдельные ошибки валидации экземпляров активностей. Каждый отчет о валидации экземпляра активности состоит из migrationInstruction (если ошибка связана с существующей инструкцией миграции), activityInstanceId и sourceScopeId активити, которое нельзя мигрировать, и массива failures со всеми сообщениями об ошибках валидации для этого отчета.

transitionInstanceValidationReports

Array

Массив JSON-объектов, описывающих отдельные ошибки валидации экземпляров переходов. Каждый отчёт о валидации экземпляра перехода состоит из migrationInstruction (если ошибка связана с существующей инструкцией миграции), transitionInstanceId и sourceScopeId перехода, который нельзя мигрировать, и массива failures со всеми сообщениями об ошибках валидации для этого отчета.

Пример

{
  "type": "MigratingProcessInstanceValidationException",
  "message": "ENGINE-23004 Cannot migrate process instance '96dc383f-23eb-11e6-8e4a-f6aefe19b687':\n\tCannot migrate activity instance 'approveInvoice:f59925bc-23eb-11e6-8e4a-f6aefe19b687':\n\t\tThere is no migration instruction for this instance's activity\n\tCannot migrate transition instance 'f598897a-23eb-11e6-8e4a-f6aefe19b687':\n\t\tThere is no migration instruction for this instance's activity\n",
  "code": 0,
  "validationReport": {
    "processInstanceId": "96dc383f-23eb-11e6-8e4a-f6aefe19b687",
    "failures": [],
    "activityInstanceValidationReports": [
      {
        "migrationInstruction": null,
        "activityInstanceId": "approveInvoice:f59925bc-23eb-11e6-8e4a-f6aefe19b687",
        "sourceScopeId": "approveInvoice",
        "failures": [
          "There is no migration instruction for this instance's activity"
        ]
      }
    ],
    "transitionInstanceValidationReports": [
      {
        "migrationInstruction": null,
        "transitionInstanceId": "f598897a-23eb-11e6-8e4a-f6aefe19b687",
        "sourceScopeId": "ServiceTask_1",
        "failures": [
          "There is no migration instruction for this instance's activity"
        ]
      }
    ]
  }
}

Исключения разбора (Parse Exceptions)

Если ресурс BPMN не удается разобрать при развертывании, развертывание завершается ошибкой и возвращается код статуса 400 Bad Request. Подробности о проблемах разбора приводятся в теле ответа.

Тип

ParseException

Тело ответа

{
	"type": "ParseException",
	"message": "ENGINE-09005 Could not parse BPMN process. Errors: Exclusive Gateway 'ExclusiveGateway_1' has outgoing sequence flow 'SequenceFlow_0' without condition which is not the default flow.",
	"code" : 0,
	"details": {
		"invoice.bpmn": {
			"errors": [
				{
					"message": "Exclusive Gateway 'ExclusiveGateway_1' has outgoing sequence flow 'SequenceFlow_0' without condition which is not the default flow.",
					"line": 77,
					"column": 15,
					"mainBpmnElementId": "ExclusiveGateway_1",
					"bpmnElementIds": [
						"ExclusiveGateway_1",
						"SequenceFlow_0"
					]
				}
			],
			"warnings": [
				{
					"message": "It is not recommended to use a cancelling boundary timer event with a time cycle.",
					"line": 87,
					"column": 20,
					"mainBpmnElementId": "BoundaryEvent_1",
					"bpmnElementIds": [
						"BoundaryEvent_1"
					]
				}
			]
		}
	}
}

Исключения превышения лимита максимального числа результатов запроса

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

Коды исключений

При ошибке REST API возвращает в теле ответа свойство "code" с числовым кодом. По нему клиентское приложение может надежно и автоматически обработать ошибку. Свойство type для этого слишком общее, а текст message может меняться от версии к версии.

Значения встроенных кодов и способ добавить собственные коды описаны в Руководстве пользователя.

Аутентификация

REST API поставляется с реализацией HTTP Basic Authentication. По умолчанию она отключена в веб-приложении REST API и, соответственно, в готовых дистрибутивах OpenBPM Engine. Чтобы ее включить, добавьте сервлет-фильтр, как описано в разделе Аутентификация.

Документация создана на основе Camunda 7 Docs (Camunda, docs.camunda.org) и распространяется по лицензии Creative Commons Attribution-ShareAlike 3.0 Unported.