# New developers features in vtenext 26.07

# Worker

The Worker is a background daemon that runs alongside the CRM. When a task takes a long time (such as chatting with an AI, running a process, uploading documents for a vector search, etc..), the Worker handles it asynchronously so the browser does not freeze and the user can keep working. Also it allows the processing to be detached from the browser request, allowing the user to close the tab.

[See the dedicated chapter here](https://usermanual.vtenext.com/books/developers/chapter/worker).

# Agent orchestrator

Python service providing AI agent chat, MCP tools integration, and RAG on CRM documents, based on FastAPI and LangChain. Called by the Worker's Consumer processes via HTTP/SSE.

[See the dedicated chapter here](https://usermanual.vtenext.com/books/developers/chapter/agent-orchestrator).

# SDK uitypes in ProcessMaker actions

SDK uitype fields will all be shown as uitype 1 (text) in ProcessMaker actions

# New properties for processes

If you don't want to attach external dynamic form emails to the record you can set to `false` this prop:  
`modules.processes.dfe.save_cache_link`

If you assign a dynaform to email or portal, you can force the assigned user of the record Processes with these props:  
`modules.processes.assigned_user_id.email`  
`modules.processes.assigned_user_id.portal`  
With the value `related_to`, the process will be assigned to the owner of the linked record. Alternatively, you can enter the ID (int) of a user/group.

# Stronger hashing algorithm for user password

Replaced the password hashing algorithm from md5 to argon2id.

# REST Webservice Methods

Below are all the SDK functions for registering REST methods and all the properties for describing them according to the OpenAPI standard.

## Registering custom Webservice methods

```
SDK::setRestOperation($name, $handlerFilePath, $handlerMethodName, $params, $permission, $mcpSupport, $info)
```

- `$name`: method name called by REST webservice;
- `$handlerFilePath`: file path where the function is defined;
- `$handlerMethodName`: name of the function to use from the specified handler file;
- `$params`: if provided, the associative array of parameter names with their definition (see [Parameter Definition (`$params`)](#bkmrk-parameter-definition))
- `$permission` (since vtenext 23.08): one of “read”, “write” or “readwrite”, describing the kind of operation of this webservice. Used with additional accesskey for the users;
- `$mcpSupport` (since vtenext 26.XX): default to 0 ("disabled"), it can be set to 1 to allow the registration of this method to MCP servers;
- `$info` (since vtenext 26.XX): additional information used to display this method, for documentation purposes (see [`$info` Parameter](#bkmrk-%24info-parameter))

This function returns the id of the new Webservice if created successfully, and `false` otherwise.

```
SDK::setRestOperationInfo(string $name, array $operation = [], array $parameters = [], array $requestExamples = [], array $responses = [])
```

This function takes `name` as the name of the operation, and the arrays described in the [`$info` Parameter](#bkmrk-%24info-parameter) section.

This function returns `true` if the webservice information was set up successfully, and `false` otherwise.

### Parameter Definition (`$params`)

The `$params` function parameter is an associative array that has the name of the parameter as the key, and the type of the parameter.

The types currently registered are `string`, `encoded`, `datetime`, `double`, and `boolean`.

### `$info` Parameter

The `$info` parameter of the function `SDK::setRestOperation` is an optional associative array that has the keys **`operation`**, **`parameters`**, **`examples`**, and **`responses`**.

This parameter is passed accordingly to `SDK::setRestOperationInfo`, which is the method responsible for filling the information for the Webservice method that is needed for the OpenAPI specification and the MCP servers.

#### `operation` Key

The `operation` key is an associative array with two optional keys:

- `description`: `string`, human-readable description of the Webservice method;
- `tags`: `string`, comma-separated list of tags to group the Webservice method with;
- `tool_description`: `string`, specific description for MCP tool, if not provided the MCP server will default the generic description.

#### `parameters` Key

The `parameters` key is an associative array with the name of the parameter as the key, and an associative array that contains additional information, used for documentation purposes.

This information is used to further document the parameters of the webservice method, while still adhereing to the conventions already established with the use of this SDK.

The associative array for the parameter has the following, optional, attributes:

- `required`: `bool`, whether the parameter is mandatory;
- `default_value`: `mixed`, the default value of the parameter;
- `description`: `string`, informative description of the parameter;
- `example`: `mixed`, an example value of the parameter;
- `extra`: associative `array`, complementary information that can't be documented otherwise.

The `extra` attribute has the following, optional, attributes, that are of type `string` except when noted:

- `type`: used, for example, when the parameter is registered as `encoded`, allowing it to "cast" it as `object` or `array`;
- `schema`: the name of the schema definition that describes the structure of the parameter, used when `type` is `object`;
- `items`: required when `type` is `array`, specifies the typing of the values contained in the array; it can be a simple type such as `string`, `int`, `float`, `double`, `bool`, or the name of a schema definition;
- `enum`: `array` of values that are supported by the parameter.

#### `examples` Key

The `examples` key is a list of associative arrays that showcase a full usage of the webservice method. This key is optional.

The associative array of a single example has the following attributes:

- `name`: `string`, the name chosen for the example;
- `summary`: `string`, brief description of the example;
- `data`: associative `array`, the payload passed by the request.

#### `responses` Key

The `responses` key is an associative array with the status code of the response as the key, and an associative array that contains the information of the response.

The associative array of a response has the following optional attributes:

- `description`: `string`, brief description of the response;
- `fields`: associative `array`, the payload of the response, see [`fields` Attribute](#bkmrk-fields-attribute)
- `examples`: associative `array`, example representations of the response, see [`examples` Key](#examples-key);
- `ref`: `string`, predefined information of the response; if provided

##### `fields` Attribute

The `fields` attribute is an associative array with the name of the field as the key, and an associative array that contains the information of the field.

The associative array of a field has the following optional attributes:

- `type`: the type of the field, can be `string`, `int`, `float`, `double`, `bool`, `object`, or `array`; if omitted, the field can be of "any" type;
- `schema`: if `type` is `object`, the name of the schema definition that describes the structure of the field;
- `items`: required when `type` is `array`, specifies the typing of the values contained in the array; it can be a simple type such as `string`, `int`, `float`, `double`, `bool`, or the name of a schema definition;
- `required`: `bool` whether the field is mandatory;
- `default`: `mixed`, the default value of the field;
- `description`: `string`, informative description of the field;
- `example`: `mixed`, an example value of the field;
- `enum`: `array` of values that are supported by the field.

## Deregistering custom Webservice methods

```
SDK::unsetRestOperation(string $name)
```

- `$name`: name of the webservice method to delete.

This function returns `true` on success and `false` on failure.

```
SDK::unsetRestOperationInfo(string $name, string $type = 'all')
```

- `$name`: name of the webservice method whose information need to be deleted;
- `$type`: the type of information to delete, can be `all`, `operation`, `parameters`, `requestExamples`, `responses`, and `responseExamples`.

This function returns `true` on success and `false` on failure.

## Registering custom Webservice schemas

```
SDK::setRestOperationSchema(string $name, array $fields)
```

- `$name`: name of the schema;
- `$fields`: see [`fields` Attribute](#bkmrk-fields-attribute).

This function returns the id of the new webservice schema if created successfully, and `false` otherwise.

## Deregistering custom Webservice schemas

```
SDK::unsetRestOperationSchema(string $name)
```

`$name` is the method name of the webservice schema to delete.

This function returns `true` on success and `false` on failure.

# MCP Server

The [Model Context Protocol (MCP)](https://modelcontextprotocol.io) is a standard that enables AI applications to connect to external systems.  
In VTENEXT, this standard is used to expose REST APIs, custom methods and processes to AI applications, to enable them to interact with the CRM itself.

Currently VTENEXT has set up a basic MCP server with the main webservices (referred here as *tools*) that ensure a wide extent of interoperability with the CRM; the user can choose to extend this server by registering other webservices to it, or even create *custom tools* to be used with the servers. Be mindful that, with roughly more than 30 tools registered to a MCP server, the accuracy of the server might degrade.

In VTENEXT, the MCP servers are fundamentally handled like any other webservice, but they have their own SDK methods to work with them.

## Tools registered in the base MCP server (REST name: `mcp`)

- `create`
- `delete`
- `describe`
- `listtypes`
- `query`
- `relate`
- `retrieve`
- `retrieveInventory`
- `get_currencies`
- `updateRecord`
- `convert_lead`
- `get_current_context`
- `process_text`
- `summarize`
- `tools_manual`
- `translate`

## SDK methods for working with MCP servers

### Setting up a MCP server

```
SDK::setMcpServer(string $name, ?string $description = null, bool $isActive = true, ?string $operationName = null)
```

- `$name`: the name of the MCP server;
- `$description`: human-readable description of the MCP server;
- `$isActive`: set it to `false` to prevent the Server from accepting requests;
- `$operationName`: the name to give to the corresponding REST Webservice method; defaults to the name of the MCP server prefixed with `mcp.`.

This function returns the id of the MCP server if created successfully, and `false` otherwise.

### Registering a tool to a MCP server

```
SDK::registerMcpTool(string $mcp, string $name, string $type, ?string $tool_name = null, ?string $description = null)
```

- `$mcp`: the name of the MCP server;
- `$name`: the name of the webservice method or the custom MCP tool;
- `$type`: the type of the tool to register, can be `operation` for the webservice method or `custom` for the custom tool;
- `$tool_name`: the name to give to the registered tool, defaults to `$name`;
- `$description`: MCP-specific information to give to the registered tool, will take precedence over any information provided by the webservice method/custom tool.

If successful, this function returns an array with the id of the MCP server and the id of the webservice method/custom tool; this function returns `false` on failure.

### Defining a custom tool for MCP servers

```
SDK::setMcpTool(string $name, string $handlerFilePath, ?string $handlerMethodName = null, ?string $description = null, ?array $inputSchema = null, ?array $outputSchema = null)
```

- `$name`: the name of the custom tool;
- `$handlerFilePath`: file path where the function is defined;
- `$handlerMethodName`: name of the function to use from the specified handler file;
- `$description`: informative description of the custom tool;
- `$inputSchema`: the definition of the function input;
- `$outputSchema`: the definition of the function output.

`$inputSchema` and `$outputSchema` follow the [JSON Schema 2020-12 Specification](https://json-schema.org/draft/2020-12).

**N.B.**: the function should always return an array and, if possible, the array should be associative.

### Removing a MCP server

```
SDK::unsetMcpServer(string $mcp, bool $force = false)
```

- `$mcp`: the name of the MCP server to delete;
- `$force`: if `true`, force the deletion of the MCP server, even if it has tools registered to it.

This function returns `true` on success and `false` on failure.

### Deregistering a tool from a MCP server

```
SDK::unregisterMcpTool(string $mcp, string $name, string $type)
```

- `$mcp`: the name of the MCP server;
- `$name`: the name of the tool to deregister;
- `$type`: the type of the tool to deregister, can be `operation` or `custom`.

This function returns `true` on success and `false` on failure.

### Deregistering a custom tool

```
SDK::unsetMcpTool(string $name)
```

- `$name`: name of the custom tool to delete.

This function returns `true` on success and `false` on failure.