Synapsea BP Agent — editing business processes via an AI agent

What this solution does

The module connects an AI agent to the portal, enabling it to analyze business processes and apply corrections. The system does not merely suggest where to click; it identifies the root cause of an issue and executes the necessary changes.

In a typical workflow, a specialist sends a natural language request to Claude Code, such as: "In the contract approval process, the approver is sometimes not assigned, causing the request to hang. Investigate the cause."

The agent opens the template via the module, traverses the tree structure, identifies the cause of the failure, and explains it. For instance, it may find a link to an action deleted two years ago, which prevents the executor from being assigned. The system displays the exact location of the error within the tree, proposes a fix, and, upon user confirmation, writes the correction back to the portal. Before saving, a snapshot of the state is preserved, allowing a return to that point with a single command.

The solution comprises two components. The module serves as the server-side component, providing an HTTP interface for template operations, managing access keys, handling versions, and maintaining an event log. The skill for Claude Code acts as the client-side component. It is a model of the template format and a set of tools distributed freely with open source code at the GitHub repository: ShyDamn/bitrix-bizproc-skill.

Without the module, the skill can only operate on files downloaded manually. Together, they grant the agent direct access to the portal.

The visual editor stores the business process structure as a tree, compressed with zlib after serialization. In real-world companies, approval processes can contain up to a thousand nodes. Finding a specific branch in such a large structure through the standard interface requires expanding dozens of blocks, making it impossible for anyone to hold the entire picture in mind.

The problem is compounded because the Bitrix system does not validate links within the template. When a link points to a deleted action or an undeclared constant, the system silently substitutes an empty string. The process continues execution, the email is sent with missing data, the approver is not assigned, and the event log shows no errors. Such defects can persist in working processes for years and surface at the most inconvenient moment.

A separate issue involves disabled blocks. The standard Bitrix validation completely ignores branches with disabled actions, so errors within them are never displayed. If such a branch is enabled a year later, it fails to function. The module locates these problematic areas and marks them separately, without mixing them with current errors.

Module capabilities:

- Returns the template as JSON, either in full or as a specific branch by path.

- Searches for actions by type, title, or property content.

The Synapsea BP Agent module checks the structure of business processes in Bitrix24, identifying broken action links, undeclared constants and variables, duplicate names, and variables that are written to but never read. Changes are saved via the standard Bitrix24 loader. A snapshot is preserved before each save, allowing users to revert changes. The tool runs a process on a specific entity and displays its current position. It also maps executors with identifiers in the user_271 format to actual employees.

The solution is intended for integrators and internal teams managing a boxed Bitrix24 version with dozens of approval processes. This is particularly relevant when processes were created by different people over different years and must be analyzed based on user complaints.

Access keys are issued with separate permissions: read, write, create, run, and access to the employee directory. Modifying Execute Code blocks is a separate permission, disabled by default because it allows uploading arbitrary PHP to the server. The key's scope is limited to document types or specific template IDs. A key issued for three templates in one sales funnel has no access to other portal processes. A request to an unauthorized template returns the same response as a request to a non-existent object.

The record is protected by a multi-layered security system. Mandatory version checking prevents accidental overwriting of changes made by a human via the visual editor. The transformation process includes self-verification: the generated template is expanded back and compared with the original; any discrepancy causes the record to be rejected. Structural errors block the save operation; they can be bypassed only by explicit instruction, and the bypass event along with the list of ignored items is logged. Every operation is recorded with details on the key, template, nature of changes, and whether executable code was affected. The functionality has been verified on live production data. The transformation was tested on 2584 portal workflow templates: the full read-and-build cycle resulted in zero data loss across all templates, including one with 1106 nodes. Verification can be run locally with a single command that scans all portal templates without making changes and displays the results. Requirements: Boxed Bitrix24 with the Business Process module, PHP 8.2 or higher, MySQL or PostgreSQL database, zlib library. The client-side component requires Claude Code.

If “Synapsea BP Agent — editing business processes via an AI agent” fits the task, General iT can install the module, configure it and verify the result in the project.