1. Create a publication (the "General" screen): set the survey title and its future web address (Slug).
2. Build the questions (the "Builder" screen): assemble the field structure, configure requiredness, hints and display logic.
3. Branding and localization (the "Design" and "Translations" screens): configure the company header, footer and add Kazakh/English translations.
4. Preview and verify (the "Preview" screen): fill in a test survey, make sure calculations and validation behave correctly.
5. Activate and collect responses: turn on the "Status: Active" toggle and analyze the results on the "Reporting" screen or via Webhooks/API.

Controls

• "New publication" button: clears the creation form and switches the manager into registration mode for a new address.
• Search (live filter): instantly filters the publication list by title or slug.
• "Publication title" field: the name shown to users in the browser tab title and in the survey header.
• "URL (Address)" field / Slug: a unique Latin-alphabet string (for example, anketa-2026). The final link to the form: https://domain/f/anketa-2026.
• "Status: Active" toggle: when off, users attempting to fill in the form see the "acceptance closed" screen (Inactive Screen).
• Revision history and Rollback: the lower part of the card shows a timeline of all saved versions with date and author. Clicking a revision instantly loads the historical version of the form into the builder.

Administrative Publication List

Administrators get a cross-platform "Publications" list covering every survey on the platform, including those created by other users:

• Search: by publication title, slug or form title.
• Filters: status (active/inactive), access type (public, private, role-based) and owner.
• Actions: open any publication for editing, activate/deactivate; the table shows the response count and the acceptance end date.
• Creators without the administrator role see only their own publications in the "General" section.

Workspace Layout

• Left component palette: contains basic fields (Text, Number, Checkbox, Files) and layout elements (Panels, Columns). Drag them with the mouse into the work area on the right. A full reference of all components is available in the builder guide.
• Working canvas: displays an interactive mock-up of the future form. Hovering over any component opens a quick actions panel:
  • Settings: opens a dialog with validation, API key and hint parameters.
  • Copy: clones the field together with all of its nested rules.
  • Paste below: inserts a previously copied component.
  • JSON: direct editing of the field schema (available in Advanced Mode).
  • Move: manually reposition the component elsewhere on the canvas.
  • Delete: removes the component from the schema.

Customization Options

• Ready-made templates (assets): quickly attach a corporate header, footer or inactivity screen from the centralized asset catalog.
• Code editor (Ace Editor): a built-in editor with HTML/CSS syntax highlighting for writing your own markup.
• Live preview panel (Preview Box): renders the markup in real time as you type.
• Theme styling: supports the light theme (Corporate Light) and the high-contrast dark theme (Dark Enterprise).

Embedding a form on another website

A publication can be embedded as a frame on an external website — for example, a corporate portal — so respondents fill in the form without leaving the site they already use.

1. On the "Design" tab, enable the "Allow embedding this form on external websites" switch in the "Embedding" card.
2. Specify the allowed origins — one per line, in the format https://www.ktz.kz. The form can only be embedded on a site whose origin is on this list (protection against embedding on arbitrary resources via CSP frame-ancestors), up to 10 origins.
3. Click "Save design" — the setting takes effect within a few seconds.
4. Copy the ready-made embed code with the "Copy code" button and hand it to the site owner. The code contains the frame and an automatic height-resize script.

Nothing else is required on the host side: the developer simply pastes the received code into the page — no keys, tokens or registration. A hand-written iframe pointing at the form URL will also work, but without the snippet's script the height has to be fixed. Keep the order in mind: the site's origin must be added to the list before the code goes live on their side, otherwise the browser will block the frame.

Limitations:

• Role-based forms can be embedded too: a "Sign in" button appears inside the frame; sign-in opens in a separate window (the branded single sign-on page), and the form loads automatically afterwards — the host page is not reloaded.
• Forms with mandatory signing (NCALayer) may not reach the signing application from a frame due to browser restrictions (Private Network Access). In that case the form itself offers to "Open in a new tab" — signing works in a separate tab. Test on the target site.
• If the switch is on but the origin list is empty, embedding is denied — the form remains protected from being framed.

How Localization Works

1. When you open the tab, the system automatically parses the current form schema and finds all text strings: field labels, placeholders, descriptions and error texts.
2. An interactive table shows columns per language: Russian (RU), Kazakh (KK) and English (EN).
3. CSV export: you can export the table to a file to hand over to professional translators.
4. When filling in the survey, the respondent picks a language in the switcher and every question of the form is translated instantly without a page reload.

Registry and Editor

• Dictionary registry: a table of all dictionaries with status, production version and last update date. A new dictionary is registered with the create button.
• Built-in editor: spreadsheet-style record editing — add rows, live table search, double-click cell editing.
• Import and export: bulk-load values from Excel/CSV, export the current draft to Excel, paste rows from the clipboard (Ctrl+C in Excel → click the table → Ctrl+V).
• Draft and publishing: changes are stored with "Save draft"; "Publish" turns the draft into the production version that forms read their values from.
• External dictionaries: rows with the cloud icon show the latest sync status; the lightning button triggers a manual sync.

External dictionaries (auto-sync)

A dictionary can receive its values from an external source automatically: the platform fetches the data server-to-server, maps it onto the dictionary contract and publishes a new production version — only if the data actually changed. A typical case is transport reference data maintained by an external ontology API (stations, train categories).

• Configuration: the cloud button opens the source card — resource URL, transformer (field mapping), environment variable with credentials (Basic), update interval in minutes, on/off switch.
• Manual sync: the lightning button in the registry row (or in the source card) runs an out-of-band update without waiting for the interval.
• Sync log: the source card shows the log of recent attempts — time, status, HTTP code, records fetched and changed, published revision.
• Revisions and consistency: every source change is recorded as a new immutable dictionary revision tagged with the external dataset version. Forms keep reading values even when the external source is unavailable — the last published revision is used. Manual editing of an external dictionary's draft is blocked: the next sync would overwrite it.
• Rollback: instantly revert to any previous revision via the publication history, exactly like regular dictionaries.

Auto-fill fields by user (prefill)

Form fields can be filled automatically from the profile of the user who opened the form: the full name comes from the account (Keycloak), objects (sections, stations) come from personal assignments managed in the "Assignments" tab.

• How it works: a form field carries the prefill property — when the form opens, the value is filled from the profile (the name is locked from editing), and dropdown options are filtered down to the objects assigned to the user.
• Server-side guarantee: on submission the server validates the data independently of the browser — the name is always replaced with the account value, and the object choice is checked against the assignments. Tampering via DevTools is impossible.
• If nothing is assigned: the object list stays full (fallback mode) and the user's choice is flagged as manual. Such values appear in the "Assignments" tab as candidates — once an administrator approves them, the fields fill automatically from the next submission on.
• "Assignments" tab: manual grants (user lookup by email), the list of active assignments and candidates, approval and removal. Candidates are created automatically from submissions where the user picked an object manually.

The screen renders an exact copy of the live respondent interface with all connected styles, fonts, header and footer. It lets you test form submission, required fields, phone masks, file attachments and the question branching logic.

Analytics Features

• Real-time counters: the total number of submitted surveys (submissions) and the date of the last response.
• "Response dynamics" chart: a timeline of survey completion by day.
• Geographic response map: an interactive map of Kazakhstan with clustering of survey submission points (for forms that collect geolocation).
• Per-field breakdown: select one or more questions from the dropdown — the system automatically builds pie and bar charts of the answer distribution.
• Asynchronous Excel export (XLSX): when you press "Download Excel", the job is handed to RabbitMQ workers. The finished report downloads instantly without blocking the interface.

System Parameters

• Maximum upload size: the size limit (in MB) for files allowed to be attached in forms.
• Platform time zone: defines correct timestamp calculation in analytics and Excel exports.
• Form translation languages: controls the languages available on the "Translations" tab and in published forms. Russian remains the primary language; Kazakh, Kyrgyz, English and Uzbek can be switched on and off.
• Antivirus scanner (ClamAV): enables file scanning for viruses and defines the service address.
• Keycloak roles mapping: maps platform system roles (Admin, Creator, Viewer) to Keycloak tokens.
• Diagnostics bundle: builds a single archive with microservice logs, RabbitMQ queue states and the DLQ error queue for fast technical support.

"System Health" Panel

The "Maintenance" section shows live infrastructure metrics. The panel refreshes via the "Refresh" button and every time the tab is opened. How to read the metrics:

API Token Security

• whsec_ prefix: the token is generated by a cryptographically secure generator and shown only once at creation.
• SHA-256 hashing: only the token hash is stored in the platform database. Even if the database is compromised, the original key cannot be recovered.
• Visibility scope: a key can be global or restricted to selected publications only.

Sample GraphQL Request via cURL

curl -X POST https://suraqhub.domain.com/graphql \
  -H "Content-Type: application/json" \
  -H "X-API-Key: whsec_your_secret_api_key_here" \
  -d '{
    "query": "query GetPubStats($id: UUID!) { publicationStats(publicationId: $id) { totalSubmissions lastSubmissionDate } }",
    "variables": { "id": "16a5ff0e-f1ff-4b8a-9887-c5f907912ea1" }
  }'

Event Types:

• submission.created — a user has filled in and successfully submitted the form.
• form.saved — the question structure of the form has been changed or saved.
• publication.saved — the publication has been changed or activated.

JSON Payload Specification:

{
  "event": "submission.created",
  "event_id": "9f1c2d3e-4b5a-6c7d-8e9f-0a1b2c3d4e5f",
  "timestamp": "2026-09-02T15:30:00.000Z",
  "publication_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "form_id": "f5e4d3c2-b1a0-9876-5432-10fedcba9876",
  "submission_id": "77aa88bb-99cc-00dd-11ee-22ff33aa44bb",
  "data": {
    "fullName": "Alexey Smirnov",
    "phoneNumber": "+77015554433",
    "score": 5,
    "comment": "Great performance!"
  }
}

Verifying the HMAC-SHA256 Signature (the X-SuraqHub-Signature Header)

Every request is signed with your subscription secret. The receiving server must verify the signature before processing:

Python Example (FastAPI / Flask):

import hmac, hashlib
from fastapi import FastAPI, Request, HTTPException, Header

app = FastAPI()
WEBHOOK_SECRET = "whsec_your_secret_key"

@app.post("/webhook")
async def receive_webhook(request: Request, x_suraqhub_signature: str = Header(None)):
    raw_body = await request.body()
    expected = hmac.new(WEBHOOK_SECRET.encode("utf-8"), raw_body, hashlib.sha256).hexdigest()

    if not x_suraqhub_signature or not hmac.compare_digest(expected, x_suraqhub_signature):
        raise HTTPException(status_code=403, detail="Invalid HMAC signature")

    payload = await request.json()
    print(f"✅ Event received successfully: {payload['event']}")
    return {"status": "ok"}

Reliability Guarantees (SRE Retry Policy):

• Manual ACK: the message is acknowledged in RabbitMQ only after your server returns HTTP 200 OK.
• Exponential Retry: on a network error or a 5xx code, the platform retries delivery up to 5 times with a growing interval.
• Dead Letter Queue (DLQ): on fatal errors (404, 403) the message is safely stored in the suraqhub.webhooks.failed dead-letter queue for manual analysis.

How This Channel Differs from Webhooks and API Keys:

• Webhooks — instant push notifications for automation systems (reaction to an event within seconds).
• API keys — synchronous queries to the GraphQL API for external services (data of a specific survey, business logic).
• The analytics schema — history for humans: dashboards, funnels and aggregated reports in Power BI refreshed on a schedule.

Data Model:

• vw_submissions — survey headers: when, which publication, language, signature presence. No response content.
• vw_submission_answers — responses in a "long" format (one row = one answer). Universal for any form: in Power BI it is unfolded into a wide table with a Pivot.
• vw_submission_geo — device coordinates (latitude, longitude, accuracy) for forms that collect geolocation.
• vw_publications — publication directory: titles, submission policies, signature and geolocation, activity periods.

Security and Privacy:

• Connection uses the dedicated read-only powerbi_reader role, which has access only to the analytics schema. Platform service tables (API keys, subscriptions, audit) are not accessible to the role.
• No personal data is exposed: IIN, cryptographic signatures and raw metadata are not included in the views.
• Writing is impossible by design — the role has read-only rights.

Connection:

In Power BI Desktop: Get Data → PostgreSQL, enter the server address and the suraqhub database, authorize under the powerbi_reader account (issued by the platform administrator). For published dashboards, add the same source to an on-premises Data Gateway.

For high-load deployments the platform provides a read-only database replica: an administrator can point analytical reports and BI connections at the database copy (DATABASE_RO_URL), leaving the primary database for survey intake only. See suraqhub-docs/analytics_powerbi.md for details.