unibpm-integration-feedback

Purpose

unibpm-integration-feedback is a Cabinee integration module for receiving and processing external feedback forms, primarily from landing pages and public websites.

The main usage scenario:

• receive form data;
• verify SmartCaptcha (Yandex);
• validate input data;
• create a ticket in Cabinee via the API.

Use cases

• Forms on Cabinee landing pages
• Demo / consultation requests
• Lead generation
• Public forms without authentication

API

Endpoint

POST /public/feedback

The endpoint is available without authentication.

Request format

Envelope structure

{
  "formId": "landing-demo",
  "smartToken": "string",
  "data": {
    "name": "John",
    "email": "john@example.com",
    "company": "ACME"
  }
}

Fields

Validation

General rules

• formId must exist in the configuration
• data must be a JSON object
• The number and depth of fields are limited
• String fields have a maximum length

Limits

SmartCaptcha

Purpose

Yandex SmartCaptcha is used to protect public forms from bots.

Behavior

• On a SmartCaptcha error, a fail-open strategy is used
• If the token is missing, the request is rejected

Configuration

application.yml example

unibpm:
  integration:
    feedback:
      enabled: true
      smart-captcha:
        validate-url: "https://smartcaptcha.yandexcloud.net/validate"
        secret-key: "${SMART_CAPTCHA_SECRET}"
        connect-timeout-ms: 3000
        read-timeout-ms: 3000
      unibpm-api:
        base-url: "http://unibpm-app:8080"
        token: "${UNIBPM_TOKEN}"
      forms:
        landing-demo:
          ticket-type-id: "ceedf30e-fdc4-11f0-8f6b-1b80298e4fe7"
          queue-key: "d6318e46-fdc4-11f0-9c1f-d30a1a0f4bd6"
          title-template: "Lead: ${data.name} / ${data.company}"
          description-template: |
            Name: ${data.name}
            Email: ${data.email}
            Company: ${data.company}
          allowed-fields: [name, email, company]
          max-fields: 30
          max-string-len: 2000
          max-depth: 3

Templates

title-template and description-template support substitution of:

• ${data.<field>} — form data
• ${meta.clientIp} — client IP (if available)

Integration with Cabinee

Purpose

At this stage, the module creates a ticket in Cabinee via the REST API.

Behavior

• The queue and ticket type are determined by the form configuration
• Cabinee errors are logged and returned as INTERNAL_ERROR

Error handling

Possible errors

Error response example

{
  "status": 400,
  "reason": "VALIDATION",
  "message": "Invalid formId"
}

Extending

To add a new form:

1. Add configuration to application.yml
2. Specify formId
3. Configure fields and templates

A runtime restart is required.

Notes

• The /public/feedback endpoint is intended only for public forms
• The module is not recommended for internal integrations