Обзор

Этот раздел перенесён из документации Camunda 7 и в дальнейшем будет доработан с учётом особенностей OpenBPM Engine

Цель 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 http://en.wikipedia.org/wiki/Basic_access_authentication. По умолчанию она отключена (в веб-приложении rest-api, а следовательно, и в готовых дистрибутивах Camunda 7). Вы можете активировать её, добавив сервлет-фильтр, как описано в разделе Аутентификация.

Лицензия и атрибуция

Эта документация была создана на базе материала "Camunda 7 Docs" от Camunda, находится под лицензией Creative Commons Attribution-ShareAlike 3.0 Unported License .

Оригинал документации: https://docs.camunda.org