How to Create a Custom Field in a Smart Process
Scope:
crm, userfieldconfigWho can execute the method: users with permission to modify the smart process
If you are developing integrations for Bitrix24 using AI tools (Codex, Claude Code, Cursor), connect to the MCP server so the assistant can utilize the official REST documentation.
Custom fields extend the functionality of CRM to meet your business needs:
-
You can create fields to store information in various formats: string, money, number, address, file, and more.
-
You can configure field characteristics: names for different languages, multi-field flag, rounding settings for numeric fields, and others.
To create a custom field in a smart process, we will sequentially execute two methods:
-
crm.type.list — retrieve the ID of the smart process.
-
userfieldconfig.add — create a custom field in the smart process.
1. Retrieve the Smart Process ID
To obtain the ID of the smart process, we use the crm.type.list method with the filter:
title— specify the name of the smart process.
How to Use Examples in Documentation
BX24.callMethod(
'crm.type.list',
{
filter: { // array of fields for filtering
"title": "Equipment Purchase" // name of the smart process
}
}
);
require_once('crest.php');
$result = CRest::call(
'crm.type.list',
[
'filter' => [
'title' => 'Equipment Purchase' // name of the smart process
]
]
);
As a result, we will receive the id — this is the ordinal number of the smart process in Bitrix24. In the example, id: 7.
{
"result": {
"types": [
{
"id": 7,
"title": "Equipment Purchase",
"code": "",
"createdBy": 1,
"entityTypeId": 177,
"customSectionId": null,
"isCategoriesEnabled": "Y",
"isStagesEnabled": "Y",
"isBeginCloseDatesEnabled": "Y",
"isClientEnabled": "Y",
"isUseInUserfieldEnabled": "Y",
"isLinkWithProductsEnabled": "Y",
"isMycompanyEnabled": "Y",
"isDocumentsEnabled": "Y",
"isSourceEnabled": "Y",
"isObserversEnabled": "Y",
"isRecyclebinEnabled": "Y",
"isAutomationEnabled": "Y",
"isBizProcEnabled": "Y",
"isSetOpenPermissions": "Y",
"isPaymentsEnabled": "N",
"isCountersEnabled": "N",
"createdTime": "2021-11-26T10:52:17+03:00",
"updatedTime": "2024-11-12T15:32:39+03:00",
"updatedBy": 1
}
]
}
}
2. Create a Custom Field in the Smart Process
To create a custom field, we use the userfieldconfig.add method with the following parameters:
-
moduleId— the identifier of the module in which the method will create the field, a required parameter. The module for smart processes iscrm. -
field[entityId]— the identifier of the object in the formatCRM_ + {ID}, where ID is the ordinal number of the smart process in Bitrix24 from the result of crm.type.list, a required parameter. In the example, we will specifyCRM_7. -
field[fieldName]— the field code in the formatUF_ + {object identifier} + _ + {arbitrary string in UPPERCASE}. The length limit for the code is 50 characters, a required parameter. In the example, we will specifyUF_CRM_7_NEW_REST_LIST. -
field[userTypeId]— the identifier of the field type, a required parameter. In the example, we will specifyenumerationto create a list-type field, and we will pass the list values in a separateenumarray. -
field[multiple]— the multi-field flag, an optional parameter. The multiplicity flag cannot be changed after the field is created. -
field[editFormLabel]— an array of names for displaying the field in Bitrix24 in different languages. An optional parameter; if no name is provided, the field code will be displayed in Bitrix24.
BX24.callMethod(
'userfieldconfig.add',
{
moduleId: 'crm', // Module identifier
field: {
entityId: 'CRM_7', // Object identifier
fieldName: 'UF_CRM_7_NEW_REST_LIST', // Field code
userTypeId: 'enumeration', // Field type identifier
multiple: 'Y', // Multi-field flag
editFormLabel: {
'de': 'Merkmal Liste', // Field name in German
'en': 'List of characteristics' // Field name in English
},
enum: [ // List field values
{
value: 'Characteristic 1', // Option value
def: 'N', // Default value flag
sort: 100, // Sort index
},
{
value: 'Characteristic 2',
def: 'Y', // This option will be the default value
sort: 200,
}
]
}
},
);
require_once('crest.php');
$result = CRest::call(
'userfieldconfig.add',
[
'moduleId' => 'crm', // Module identifier
'field' => [
'entityId' => 'CRM_7', // Object identifier
'fieldName' => 'UF_CRM_7_NEW_REST_LIST', // Field code
'userTypeId' => 'enumeration', // Field type identifier
'multiple' => 'Y', // Multi-field flag
'editFormLabel' => [
'de' => 'Merkmal Liste', // Field name in German
'en' => 'List of characteristics' // Field name in English
],
'enum' => [ // List field values
[
'value' => 'Characteristic 1', // Option value
'def' => 'N', // Default value flag
'sort' => 100, // Sort index
],
[
'value' => 'Characteristic 2',
'def' => 'Y', // This option will be the default value
'sort' => 200,
]
]
]
]
);
As a result, we will receive the data of the created field.
{
"result": {
"field": {
"id": "6953",
"entityId": "CRM_7",
"fieldName": "UF_CRM_7_NEW_REST_LIST",
"userTypeId": "enumeration",
"xmlId": null,
"sort": "100",
"multiple": "Y",
"mandatory": "N",
"showFilter": "N",
"showInList": "Y",
"editInList": "Y",
"isSearchable": "N",
"settings": {
"DISPLAY": "LIST",
"LIST_HEIGHT": 1,
"CAPTION_NO_VALUE": "",
"SHOW_NO_VALUE": "Y"
},
"languageId": {
"en": "en",
"de": "de"
},
"editFormLabel": {
"en": "List of characteristics",
"de": "Merkmal Liste"
},
"listColumnLabel": {
"en": null,
"de": null
},
"listFilterLabel": {
"en": null,
"de": null
},
"errorMessage": {
"en": null,
"de": null
},
"helpMessage": {
"en": null,
"de": null
},
"enum": [
{
"id": "3363",
"userFieldId": "6953",
"value": "Characteristic 1",
"def": "N",
"sort": "100",
"xmlId": "56dff18efcfe25f3bae0117a6b372567"
},
{
"id": "3365",
"userFieldId": "6953",
"value": "Characteristic 2",
"def": "Y",
"sort": "200",
"xmlId": "42e3ebcf5506a65283bf3bf510d8f05a"
}
]
}
},
}
Code Example
// Function to retrieve the smart process and create a custom field
function getCrmTypeAndAddUserField() {
// Variable for user input of the smart process name
var processTitle = prompt("Enter the name of the smart process to search:", "Your_Process_Name");
// Call the crm.type.list method to retrieve the smart process
BX24.callMethod(
'crm.type.list',
{
filter: {
"title": processTitle // Use the name entered by the user
}
},
function(result) {
if (result.error()) {
console.error('Error retrieving smart process:', result.error());
} else {
console.log('Smart process successfully retrieved:', result.data());
var spaId = result.data().types[0].id; // Use the id from the result
addUserField(spaId);
}
}
);
}
// Function to create a custom field
function addUserField(spaId) {
// Call the userfieldconfig.add method to create a custom field
BX24.callMethod(
'userfieldconfig.add',
{
moduleId: 'crm',
field: {
entityId: 'CRM_' + spaId, // Use the id from the previous result
fieldName: 'UF_CRM_' + spaId + '_NEW_REST_LIST', // Use the id
userTypeId: 'enumeration',
multiple: 'Y',
editFormLabel: {
'de': 'Merkmal Liste',
'en': 'List of characteristics'
},
enum: [
{
value: 'Characteristic 1',
def: 'N',
sort: 100
},
{
value: 'Characteristic 2',
def: 'Y',
sort: 200
}
]
}
},
function(result) {
if (result.error()) {
console.error('Error creating custom field:', result.error());
} else {
console.log('Custom field successfully created:', result.data());
}
}
);
}
// Call the function to retrieve smart process data and create a custom field
getCrmTypeAndAddUserField();
require_once('crest.php');
// Function to retrieve the smart process and create a custom field
function getCrmTypeAndAddUserField($processTitle) {
// Call the crm.type.list method to retrieve the smart process
$result = CRest::call('crm.type.list', [
'filter' => [
'title' => $processTitle // Use the name entered by the user
]
]);
if (isset($result['error'])) {
echo 'Error retrieving smart process: ' . $result['error_description'];
} else {
echo 'Smart process successfully retrieved: ';
print_r($result['result']);
if (!empty($result['result']['types'])) {
$spaId = $result['result']['types'][0]['id']; // Use the id from the result
addUserField($spaId);
} else {
echo 'Smart process not found.';
}
}
}
// Function to create a custom field
function addUserField($spaId) {
// Call the userfieldconfig.add method to create a custom field
$result = CRest::call('userfieldconfig.add', [
'moduleId' => 'crm',
'field' => [
'entityId' => 'CRM_' . $spaId, // Use the id from the previous result
'fieldName' => 'UF_CRM_' . $spaId . '_NEW_REST_LIST', // Use the id
'userTypeId' => 'enumeration',
'multiple' => 'Y',
'editFormLabel' => [
'de' => 'Merkmal Liste',
'en' => 'List of characteristics'
],
'enum' => [
[
'value' => 'Characteristic 1',
'def' => 'N',
'sort' => 100
],
[
'value' => 'Characteristic 2',
'def' => 'Y',
'sort' => 200
]
]
]
]);
if (isset($result['error'])) {
echo 'Error creating custom field: ' . $result['error_description'];
} else {
echo 'Custom field successfully created: ';
print_r($result['result']);
}
}
// Call the function to retrieve smart process data and create a custom field
$processTitle = readline("Enter the name of the smart process to search: ");
getCrmTypeAndAddUserField($processTitle);