REST API Reference

All modeler REST endpoints are mounted under the base path configured by cibseven.webclient.services.basePath (default: /services/v1), appended with /modeler.

Base URL: {basePath}/modeler

All endpoints require authentication unless cibsevenmodeler.authentication.enabled=false. See Authentication.

Diagrams (BPMN / DMN)

List Diagrams

GET /modeler/processes

Returns a paginated, reduced list of diagram metadata (excludes raw XML bytes).

Query Parameters:

Parameter Required Description
firstResult Yes Zero-based offset for pagination
maxResults Yes Maximum number of results to return
diagramType No Filter by type: bpmn-c7, dmn, etc.
keyword No Filter by name (case-insensitive substring)

Response: 200 OK — Array of ProcessDiagramReduce objects.

List Unified Diagrams

GET /modeler/unified-diagrams

Returns a combined list of BPMN diagrams and forms in a unified format.

Query Parameters:

Parameter Required Description
firstResult Yes Pagination offset
maxResults Yes Maximum results
keyword No Name filter
type No diagram or form

Get Diagram by ID

GET /modeler/process/{id}

Returns the full ProcessDiagramEntity including metadata.

Get Diagram XML by ID

GET /modeler/process/{id}/data

Returns the raw diagram bytes (BPMN or DMN XML) as application/octet-stream.

Create Diagram from File Upload

POST /modeler/process/create

Uploads a .bpmn or .dmn file and saves it as a new diagram.

Form Parameters:

Parameter Required Description
file Yes Multipart file upload (.bpmn or .dmn)
overwrite Yes true to overwrite an existing diagram with the same name

Save Diagram (form data)

POST /modeler/process/save

Creates or updates a diagram from form-encoded data.

Form Parameters: name, processkey, description, active, type, diagram (multipart file)

Save Diagram (JSON body)

POST /modeler/process/save/object

Creates or updates a diagram from a JSON body. If the entity’s id matches an existing record it is updated; otherwise a new record is created.

Request Body: ProcessDiagramEntity JSON object

Update Diagram

POST /modeler/process/update

Updates an existing diagram by ID with new metadata and XML.

Form Parameters: id, name, processkey, description, active, type, diagram (multipart file)

Find Diagram by Name

POST /modeler/process/find-by-name/data

Returns the raw diagram bytes for the diagram with the given name.

Query Parameters: name

Find Diagram by Process Key

POST /modeler/process/find-by-key/data

Returns the raw diagram bytes for the diagram with the given process key.

Query Parameters: key

Delete Diagram

DELETE /modeler/process/delete/{id}

Permanently deletes the diagram with the given ID.

Deployment

Deploy Diagram by File

POST /modeler/deployment/create

Deploys an uploaded diagram file directly to the CIB seven engine.

Form Parameters: deployment-name, deployment-source, deploy-changed-only, file (multipart)

Deploy Diagram by ID

POST /modeler/deployment/create/{id}

Retrieves a stored diagram by its database ID and deploys it to the engine.

Path Parameters: id (diagram database ID)

Deploy Diagram by Key (Reduce)

POST /modeler/deployment/create/reduce

Retrieves a stored diagram by process key and deploys it.

Form Parameters: deploymentName (process key), file

Check Deployment Connectivity

GET /modeler/deployment

Checks that the authenticated user has access to the deployment endpoint. Returns 200 OK if authorized.

Start Process

POST /modeler/deployment/start/{key}

Starts a new instance of the deployed process definition identified by key.

Path Parameters: key (process definition key)

Request Body: JSON map of process variables

Sessions

Open Session

POST /modeler/session/save

Records that the current user has opened a diagram or form for editing.

Form Parameters: type (diagram or form), id (diagram or form ID), diagram (current XML snapshot)

Close Session

POST /modeler/session/close

Closes one or more editing sessions for the current user.

Form Parameters: sessionId (comma-separated list), type (diagram or form)

Check Diagram Session

GET /modeler/process/session/check/{id}

Checks whether another user currently has the diagram open.

Path Parameters: id (diagram ID)

Response:

message value Meaning
NO_SESSION No one else has this diagram open
SAME_USER The current user already has it open
SESSION_FOUND Another user has it open — response includes userId and openedAt

Check Form Session

GET /modeler/form/session/check/{id}

Same as above but for forms.

Forms

List Forms

GET /modeler/forms

Returns a paginated list of saved forms.

Query Parameters: firstResult, maxResults, keyword

Get Form Schema by ID

GET /modeler/form/{id}/data

Returns the form JSON schema as application/json.

Save Form

POST /modeler/form/save

Creates a new form with the given ID and schema.

Form Parameters: formid, form_schema (multipart JSON file)

Update Form

POST /modeler/form/update

Updates an existing form.

Form Parameters: id, formid, form_schema (multipart JSON file)

Delete Form

DELETE /modeler/form/delete/{id}

Permanently deletes the form and its session records.

Chat (Enterprise Edition)

Enterprise Feature

Chat endpoints are only available in the enterprise edition when cibseven.webclient.modeler.enabled: true.

Chat endpoints are mounted under a separate base path: {basePath}/chat.

Base URL: {basePath}/chat

Get Message History

GET /chat/{roomId}/history

Returns chat messages for a room in reverse chronological order (newest first).

Path Parameters:

Parameter Description
roomId Composite room identifier — see Real-time Chat

Query Parameters:

Parameter Required Default Description
limit No 100 Maximum number of messages to return
before No — ISO-8601 datetime — return only messages created before this timestamp (for pagination)
elementId No — Filter messages by the BPMN element ID they are attached to

Response: 200 OK — Array of message objects including id, roomId, userId, displayName, content, createdAt, editedAt, and optionally elementId. Soft-deleted messages are excluded.

Send Message

POST /chat/{roomId}

Creates a new message in the room. This endpoint is the primary way to send messages in the long-polling transport. In WebSocket mode, messages can also be published over STOMP (see Real-time Chat).

Path Parameters:

Parameter Description
roomId Composite room identifier

Request Body:

Field Required Description
content Yes Message text (must not be blank)
elementId No BPMN element ID to attach the message to a specific element

Response: 200 OK — The created message object.

Get Room Presence

GET /chat/{roomId}/presence

Returns the set of users currently active in the room. In the long-polling transport, presence is backed by the database and reflects users who have polled within the last ~60 seconds. In the WebSocket transport, it reflects users currently subscribed to the room’s WebSocket topic.

Path Parameters:

Parameter Description
roomId Composite room identifier

Response: 200 OK — Array of presence objects:

Field Description
userId Authenticated user ID
displayName User’s display name

Long-Poll for Events

GET /chat/{roomId}/poll?since={cursor}

Long-polling endpoint used by the longpolling transport. The server holds the request for up to ~25 seconds and returns early when new events are available. The client immediately re-polls after each response.

Calling this endpoint also records a presence heartbeat for the authenticated user.

Path Parameters:

Parameter Description
roomId Composite room identifier

Query Parameters:

Parameter Required Description
since No Opaque cursor returned by the previous poll. Omit on the first poll to establish a baseline — the server returns an empty event list and the current cursor.

Response: 200 OK

Field Description
cursor Opaque server-owned timestamp. Pass back as since on the next poll.
events Array of change events since the cursor. Empty if nothing changed during the hold. Each event has an op field (create, update, or delete) and a message object.
presence Current presence snapshot for the room — same format as Get Room Presence.

On this Page: