Skip to main content

Architecture diagrams and elements

About 3 min

Diagrams and Architecture Elements

REST API methods for working with diagrams and architecture elements. General rules (authentication via X-Api-Key, limits) — see the REST API overview.

Loading Diagrams

Main method

Path: POST /public-api/v1/upload-diagrams

Request Structure

[
    {
        "id": "Meeting Scheduling:1:1123",
        "xml": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>...",
        "name": "Meetings",
        "source": "CamundaMeetingsBackend"
    }
]

Request parameters

FieldTypeRequiredDescription
idstring✅External process identifier
xmlstring✅XML diagram body (escaped)
namestring✅Process name (important for updates)
sourcestring✅Version source for history

Response Structure

{
    "errors": {
        "emptyName": [],
        "emptyDefinition": [],
        "notXml": []
    },
    "createdDiagrams": [],
    "updatedDiagrams": [
        {
            "stormDiagramId": "94d2e63f-f84a-40d4-b4a3-592b0cc7c7d9",
            "sourceDiagramId": "rhsrthsrth"
        }
    ]
}

Key features

  • Maximum of 20 diagrams per request
  • The name field is critical - do not modify it in Storm for updates
  • Versioning - diagrams with the same ID are updated sequentially
  • Version history - different versions can be uploaded in a single request

Shell script example for Camunda

Automation for Camunda

Use this script to automatically update diagrams after deployment:

#!/bin/bash
# Сбор BPMN файлов и отправка в StormBPMN
files=($(ls ./src/main/resources/bpmn/*.bpmn))
size=${#files[@]}
echo '[' > temp.json
counter=1

echo "Начинаем обработку файлов..."
for file in ${files[*]}; do
  id="$(grep -Po '(?<=<bpmn:process\sid=")[^"]+' $file)"
  content="$(cat $file | sed 's/"/\\"/g;')"
  name="$(basename $file .bpmn)"
  echo '{"id":"'$id'","xml":"'$content'", "name": "'$name'", "source": "app"}' >> temp.json

  # Запятые между объектами (не в конце списка)
  if ((counter % 20)) && ((size != counter)) ; then
    echo ',' >> temp.json
  fi

  # Отправка пакета по 20 диаграмм
  if ! ((counter % 20)); then
    echo ']' >> temp.json
    curl -X POST -H "X-Api-Key: API-KEY" -H "Content-Type: application/json" \
         -d @temp.json stormbpmn.com/public-api/v1/upload-diagrams -i
    rm temp.json
    echo '[' > temp.json
  fi

  ((counter=counter+1))

  # Соблюдение лимита скорости
  if ((counter > 100)); then
    sleep 60
  fi
done

# Отправка оставшихся диаграмм
echo ']' >> temp.json
curl -X POST -H "X-Api-Key: API_KEY" -H "Content-Type: application/json" \
     -d @temp.json stormbpmn.com/public-api/v1/upload-diagrams -i
rm temp.json

Managing Architecture Elements

Loading and Updating

Path: POST /public-api/v1/assets

Request Structure

[
    {
        "id": null,
        "externalId": null,
        "name": "B2C USER",
        "description": "",
        "externalUrl": null,
        "type": "CLIENT",
        "status": "NEW"
    }
]

Request parameters

FieldTypeRequiredDescription
idnumber📎Element ID in the system
externalIdstring📎Element ID in the external system
namestring✅Element name
descriptionstring📄HTML description (unescaped)
externalUrlstring📄Link with placeholders
typeenum📄Architecture element type
statusenum📄Element status

Architecture Element Types

Architecture element types

ValueDescription
UNSPECIFIEDNot specified
DOCUMENTDocument
SYSTEMSystem
DATAData
CUSTOMCustom types

Type changes

Built-in types, except for DOCUMENT and SYSTEM, have become custom types. When importing data (including Excel) and working via the API, only the values listed above are supported. Attempting to use deprecated types (for example, CLIENT, ENTITY) will result in a validation error.

Element statuses

ValueDescription
NEWNew
TRIALTesting
PRODUCTIONProduction
DECOMMISSIONINGDecommissioned
ARCHIVEArchive

Update Logic

ConditionAction
externalId onlyUpdate by external ID
id onlyUpdate by internal ID
Both id and externalIdUpdate by internal ID
Neither id nor externalIdCreate a new element

Getting the list of diagrams

Main method

Path: GET /public-api/v1/get-diagram-list

Query parameters

ParameterTypeRequiredDescription
pagenumber✅Page number (starting from 0)

Response Structure

{
    "totalElements": 223,
    "page": 0,
    "size": 20,
    "returnDiagrams": [
        {
            "id": "6b547a8f-a78f-4375-b39e-59c4afd9388e",
            "name": "Draft",
            "status": "NEW",
            "versionNumber": 3,
            "updatedBy": "kotov@bpmn2.ru",
            "teamName": "Мои кредиты",
            "type": "BCM",
            "public": true,
            "createdOn": "2024-05-02T17:19:41.459888",
            "updatedOn": "2024-05-02T17:28:07.695362"
        }
    ]
}

Access Rights

The list of diagrams depends on the team administrator's permissions for the diagrams.

Getting a diagram by ID

Main method

Path: GET /public-api/v1/get-diagram-by-id

Query parameters

ParameterTypeRequiredDescription
diagramIdUUID✅Unique identifier of the diagram

Key response fields

FieldTypeDescription
idUUIDDiagram identifier
namestringDiagram name
bodystringXML content of the diagram
versionNumbernumberVersion number
statusstringDiagram status
typestringDiagram type

Contract changes

The API contract may change. Use a tolerant reader to retrieve the required fields (usually the body field).

Updating the element description

Main method

Path: POST /public-api/v1/element-description/{diagramId}/{elementId}

Path Parameters

ParameterTypeDescription
diagramIdUUIDDiagram identifier
elementIdstringElement identifier

Request Structure

{
    "description": "Подробное описание элемента",
    "duration": 3600,
    "externalLink": "https://wiki.company.com/process"
}

Request parameters

FieldTypeDescription
descriptionstringHTML description (escaped)
durationnumberDuration in seconds
externalLinkstringExternal link

Obtaining approvals

Main method

Path: GET /public-api/v1/approvals

Query parameters

ParameterTypeRequiredDescription
userEmailstring✅Team member email
statusenum📄Approval status
isApproverboolean📄Approver flag

Approval statuses

ValueDescription
PENDINGPending approval
ACCEPTEDApproved
DECLINEDRejected
COMPLETEDCompleted

Response Structure

{
    "content": [
        {
            "id": "867bc39c-9145-4eb5-b59f-00545a6a9a3f",
            "approverEmail": "user@company.com",
            "diagramId": "fbeb4c64-e172-4e09-9fa1-6e509a11ffde",
            "diagramName": "Работа с подрядчиком",
            "status": "PENDING",
            "createdOn": "2025-01-23T17:44:27.323817",
            "diagramVersion": "11"
        }
    ],
    "totalElements": 1,
    "totalPages": 1,
    "size": 20,
    "number": 0
}