How to Complete Business Processes of a Terminated Employee

Scope: user_brief, user_basic, user, bizproc

Who can execute methods: administrator

If you are developing integrations for Bitrix24 using AI tools (Codex, Claude Code, Cursor), connect to the MCP server so that the assistant can utilize the official REST documentation.

When an employee is terminated in Bitrix24, there may be unfinished business processes for which they were responsible.

To complete the active business processes of a terminated employee, we will sequentially execute three methods:

  1. user.get — retrieve the ID of the terminated employee

  2. bizproc.task.list — obtain a list of process tasks for which the terminated employee is responsible

  3. bizproc.workflow.kill — complete the business processes while deleting data. If you need to retain the fact that the business process was initiated, use the method bizproc.workflow.terminate. Both methods are called in the same way.

1. Retrieve the ID of the Terminated Employee

We will use the method user.get with the following filter:

  • NAME — specify the employee's first name

  • LAST_NAME — specify the employee's last name

  • ACTIVE — this parameter controls the search for active or terminated employees. If this parameter is not provided, the search will include all employees regardless of their status. We will set it to 0 to search only among terminated employees.

How to Use Examples in Documentation

BX24.callMethod(
            "user.get",
            {
                filter: {
                    "NAME": "employee's name",
                    "LAST_NAME": "employee's last name",
                    "ACTIVE": 0
                }
            },
        );
        
require_once('crest.php');
        
        $result = CRest::call(
            'user.get',
            [
                'filter' => [
                    'NAME' => "employee's name",
                    'LAST_NAME' => "employee's last name",
                    'ACTIVE' => 0
                ]
            ]
        );
        
from b24pysdk import BitrixWebhook, Client
        
        client = Client(
            BitrixWebhook(
                domain="your-domain.bitrix24.com",
                auth_token="your-webhook-token",
            )
        )
        
        result = client.user.get(
            filter={
                "NAME": "employee's name",
                "LAST_NAME": "employee's last name",
                "ACTIVE": 0,
            }
        ).response.result
        

As a result, we will obtain the ID of the terminated employee.

{
            "result": [
                {
                    "ID": "29",
                    "XML_ID": "28936832",
                    "ACTIVE": false,
                    "NAME": "employee's name",
                    "LAST_NAME": "employee's last name",
                    "SECOND_NAME": "",
                    "TITLE": "",
                    "EMAIL": "employee_email@gmail.com",
                    "LAST_LOGIN": "2025-03-27T13:49:36+01:00",
                    "DATE_REGISTER": "2020-04-23T03:00:00+01:00",
                    "TIME_ZONE": "Europe/Berlin",
                    "IS_ONLINE": "N",
                    "TIMESTAMP_X": {},
                    "LAST_ACTIVITY_DATE": {},
                    "PERSONAL_GENDER": "",
                    "PERSONAL_PROFESSION": "",
                    "PERSONAL_WWW": "",
                    "PERSONAL_BIRTHDAY": "",
                    "PERSONAL_PHOTO": "https://cdn.com.bitrix24.com/b13743910/main/3f2/3f212fkdjf8c3627cfe51633f959de/avatar.png",
                    "PERSONAL_ICQ": "",
                    "PERSONAL_PHONE": "",
                    "PERSONAL_FAX": "",
                    "PERSONAL_MOBILE": "",
                    "PERSONAL_PAGER": "",
                    "PERSONAL_STREET": "",
                    "PERSONAL_CITY": "",
                    "PERSONAL_STATE": "",
                    "PERSONAL_ZIP": "",
                    "PERSONAL_COUNTRY": "0",
                    "PERSONAL_MAILBOX": "",
                    "PERSONAL_NOTES": "",
                    "WORK_PHONE": "",
                    "WORK_COMPANY": "",
                    "WORK_POSITION": "Manager",
                    "WORK_DEPARTMENT": "",
                    "WORK_WWW": "",
                    "WORK_FAX": "",
                    "WORK_PAGER": "",
                    "WORK_STREET": "",
                    "WORK_MAILBOX": "",
                    "WORK_CITY": "",
                    "WORK_STATE": "",
                    "WORK_ZIP": "",
                    "WORK_COUNTRY": "0",
                    "WORK_PROFILE": "",
                    "WORK_NOTES": "",
                    "UF_EMPLOYMENT_DATE": "",
                    "UF_DEPARTMENT": [
                        7,
                        1
                    ],
                    "UF_PHONE_INNER": "555",
                    "UF_USR_1619099890455": "12132132123",
                    "USER_TYPE": "employee"
                }
            ],
            "total": 1,
        }
        

2. Retrieve the List of Process Tasks for Which the Terminated Employee is Responsible

We will use the method bizproc.task.list with the following filter:

  • USER_ID — the identifier of the employee, we will pass the ID obtained in step 1

  • STATUS — this parameter indicates the status of the tasks; we will set it to 0 to filter only incomplete tasks.

BX24.callMethod(
            'bizproc.task.list',
            {
                filter: {
                    'USER_ID': 29,
                    'STATUS': 0,
                }
            },
        );
        
require_once('crest.php');
        
        $result = CRest::call(
            'bizproc.task.list',
            [
                'filter' => [
                    'USER_ID' => 29,
                    'STATUS' => 0
                ]
            ]
        );
        
result = client.bizproc.task.list(
            filter={
                "USER_ID": 29,
                "STATUS": 0,
            }
        ).response.result
        

As a result, we will obtain a list of incomplete tasks. Each task has a WORKFLOW_ID parameter — this is the ID of the business process that we will complete in the next step.

{
            "result": [
                {
                    "ENTITY": "CCrmDocumentContact",
                    "DOCUMENT_ID": "CONTACT_2437",
                    "ID": "879",
                    "WORKFLOW_ID": "67e3db8e581121.72266518",
                    "DOCUMENT_NAME": "widget contact",
                    "NAME": "Address",
                    "DOCUMENT_URL": "/crm/contact/details/2437/"
                },
                {
                    "ENTITY": "CCrmDocumentContact",
                    "DOCUMENT_ID": "CONTACT_2435",
                    "ID": "877",
                    "WORKFLOW_ID": "67c5b492d0b426.74280093",
                    "DOCUMENT_NAME": "Contact #2435",
                    "NAME": "Address",
                    "DOCUMENT_URL": "/crm/contact/details/2435/"
                },
                {
                    "ENTITY": "CCrmDocumentContact",
                    "DOCUMENT_ID": "CONTACT_2433",
                    "ID": "875",
                    "WORKFLOW_ID": "67c598a987d387.85575151",
                    "DOCUMENT_NAME": "Contact #2433",
                    "NAME": "Address",
                    "DOCUMENT_URL": "/crm/contact/details/2433/"
                },
                {
                    "ENTITY": "CCrmDocumentContact",
                    "DOCUMENT_ID": "CONTACT_2429",
                    "ID": "871",
                    "WORKFLOW_ID": "67091df4b13dd2.83077613",
                    "DOCUMENT_NAME": "Petrov Vasily",
                    "NAME": "Address",
                    "DOCUMENT_URL": "/crm/contact/details/2429/"
                },
                {
                    "ENTITY": "CCrmDocumentContact",
                    "DOCUMENT_ID": "CONTACT_2427",
                    "ID": "859",
                    "WORKFLOW_ID": "66e2d5d5c64f82.28057011",
                    "DOCUMENT_NAME": "Ivanovich",
                    "NAME": "Address",
                    "DOCUMENT_URL": "/crm/contact/details/2427/"
                },
                {
                    "ENTITY": "CCrmDocumentContact",
                    "DOCUMENT_ID": "CONTACT_2425",
                    "ID": "857",
                    "WORKFLOW_ID": "66e0242399d303.52288141",
                    "DOCUMENT_NAME": "Petrovna",
                    "NAME": "Address",
                    "DOCUMENT_URL": "/crm/contact/details/2425/"
                },
                {
                    "ENTITY": "CCrmDocumentContact",
                    "DOCUMENT_ID": "CONTACT_2423",
                    "ID": "855",
                    "WORKFLOW_ID": "66d870dfbb9542.91956540",
                    "DOCUMENT_NAME": "Smirnov",
                    "NAME": "Address",
                    "DOCUMENT_URL": "/crm/contact/details/2423/"
                },
                {
                    "ENTITY": "CCrmDocumentContact",
                    "DOCUMENT_ID": "CONTACT_2421",
                    "ID": "853",
                    "WORKFLOW_ID": "66d7fb6f86c0c2.49741539",
                    "DOCUMENT_NAME": "Kalashnikov",
                    "NAME": "Address",
                    "DOCUMENT_URL": "/crm/contact/details/2421/"
                },
                {
                    "ENTITY": "CCrmDocumentContact",
                    "DOCUMENT_ID": "CONTACT_2419",
                    "ID": "851",
                    "WORKFLOW_ID": "66d073d9c9fc08.23457428",
                    "DOCUMENT_NAME": "Unnamed",
                    "NAME": "Address",
                    "DOCUMENT_URL": "/crm/contact/details/2419/"
                }
            ],
            "total": 9,
        }
        

3. Complete the Business Processes

We will use the method bizproc.workflow.kill with the following parameter:

  • ID — the identifier of the process, we will pass the WORKFLOW_ID obtained in step 2
BX24.callMethod(
            'bizproc.workflow.kill',
            {
                ID: '67e3db8e581121.72266518',
            },
        );
        
require_once('crest.php');
        
        $result = CRest::call(
            'bizproc.workflow.kill',
            [
                'ID' => '67e3db8e581121.72266518'
            ]
        );
        
result = client.bizproc.workflow.kill(
            bitrix_id="67e3db8e581121.72266518",
        ).response.result
        

As a result, we will receive true, indicating that the process has been successfully deleted. If you receive an error, review the possible error descriptions in the documentation for the method bizproc.workflow.kill.

{
            "result": true,
        }
        

Code Example

In the example, all found processes are deleted in a loop. If you need to delete a large volume of data, you may encounter limits on request execution. To optimize the code for your workload, refer to the recommendations in the Performance section.

// Function to get the employee ID by first and last name
        function getUserId(firstName, lastName, callback) {
            BX24.callMethod(
                "user.get",
                {
                    "NAME": firstName,
                    "LAST_NAME": lastName,
                    "ACTIVE": 0,
                },
                function(result) {
                    if (result.error()) {
                        console.error(result.error());
                    } else {
                        // Assuming only one user is found
                        const userId = result.data()[0].ID;
                        callback(userId);
                    }
                }
            );
        }
        
        // Function to get the list of incomplete tasks for the employee
        function getUserTasks(userId, callback) {
            BX24.callMethod(
                'bizproc.task.list',
                {
                    filter: {
                        'USER_ID': userId,
                        'STATUS': 0,
                    }
                },
                function(result) {
                    if (result.error()) {
                        console.error(result.error());
                    } else {
                        // Extract WORKFLOW_ID from each task
                        const workflowIds = result.data().map(task => task.WORKFLOW_ID);
                        callback(workflowIds);
                    }
                }
            );
        }
        
        // Function to complete business processes by the list of WORKFLOW_ID
        function killWorkflows(workflowIds) {
            workflowIds.forEach(workflowId => {
                BX24.callMethod(
                    'bizproc.workflow.kill',
                    {
                        ID: workflowId,
                    },
                    function(result) {
                        if (result.error()) {
                            console.error(result.error());
                        } else {
                            console.log(`Workflow ${workflowId} completed successfully.`);
                        }
                    }
                );
            });
        }
        
        // Main function that combines all steps
        function processEmployeeTasks(firstName, lastName) {
            getUserId(firstName, lastName, function(userId) {
                getUserTasks(userId, function(workflowIds) {
                    killWorkflows(workflowIds);
                });
            });
        }
        
        // Prompt the user for the employee's first and last name
        const firstName = prompt("Enter the employee's first name:");
        const lastName = prompt("Enter the employee's last name:");
        
        // Start the process
        processEmployeeTasks(firstName, lastName);
        
require_once('crest.php');
        
        // Function to get the employee ID by first and last name
        function getUserId($firstName, $lastName) {
            $result = CRest::call(
                'user.get',
                [
                    'filter' => [
                        'NAME' => $firstName,
                        'LAST_NAME' => $lastName,
                        'ACTIVE' => 0
                    ]
                ]
            );
        
            if (!empty($result['error'])) {
                echo "Error: " . $result['error_description'];
                return null;
            }
        
            // Assuming only one user is found
            return $result['result'][0]['ID'] ?? null;
        }
        
        // Function to get the list of incomplete tasks for the employee
        function getUserTasks($userId) {
            $result = CRest::call(
                'bizproc.task.list',
                [
                    'filter' => [
                        'USER_ID' => $userId,
                        'STATUS' => 0
                    ]
                ]
            );
        
            if (!empty($result['error'])) {
                echo "Error: " . $result['error_description'];
                return [];
            }
        
            // Extract WORKFLOW_ID from each task
            return array_map(function($task) {
                return $task['WORKFLOW_ID'];
            }, $result['result']);
        }
        
        // Function to complete business processes by the list of WORKFLOW_ID
        function killWorkflows($workflowIds) {
            foreach ($workflowIds as $workflowId) {
                $result = CRest::call(
                    'bizproc.workflow.kill',
                    [
                        'ID' => $workflowId
                    ]
                );
        
                if (!empty($result['error'])) {
                    echo "Error: " . $result['error_description'];
                } else {
                    echo "Workflow $workflowId completed successfully.\n";
                }
            }
        }
        
        // Main function that combines all steps
        function processEmployeeTasks($firstName, $lastName) {
            $userId = getUserId($firstName, $lastName);
            if ($userId) {
                $workflowIds = getUserTasks($userId);
                killWorkflows($workflowIds);
            }
        }
        
        // Prompt the user for the employee's first and last name
        $firstName = readline("Enter the employee's first name: ");
        $lastName = readline("Enter the employee's last name: ");
        
        // Start the process
        processEmployeeTasks($firstName, $lastName);
        
from typing import Optional
        
        from b24pysdk import BitrixWebhook, Client
        from b24pysdk.errors import BitrixAPIError
        
        
        def get_user_id(client, first_name: str, last_name: str) -> Optional[int]:
            try:
                users = client.user.get(
                    filter={
                        "NAME": first_name,
                        "LAST_NAME": last_name,
                        "ACTIVE": 0,
                    },
                ).response.result
            except BitrixAPIError as error:
                print(f"Error: {error}")
                return None
        
            if not users:
                return None
            return int(users[0]["ID"])
        
        
        def get_user_tasks(client, user_id: int) -> list[str]:
            tasks = client.bizproc.task.list(
                filter={
                    "USER_ID": user_id,
                    "STATUS": 0,
                },
            ).response.result
        
            return [task["WORKFLOW_ID"] for task in tasks]
        
        
        def kill_workflows(client, workflow_ids: list[str]) -> None:
            for workflow_id in workflow_ids:
                try:
                    client.bizproc.workflow.kill(bitrix_id=workflow_id).response
                except BitrixAPIError as error:
                    print(f"Error: {error}")
        
        
        def process_employee_tasks(client, first_name: str, last_name: str) -> None:
            user_id = get_user_id(client, first_name, last_name)
            if user_id is None:
                return
            workflow_ids = get_user_tasks(client, user_id)
            kill_workflows(client, workflow_ids)
        
        
        client = Client(
            BitrixWebhook(
                domain="your-domain.bitrix24.com",
                auth_token="your-webhook-token",
            )
        )
        
        first_name = input("Enter the employee's first name: ")
        last_name = input("Enter the employee's last name: ")
        
        process_employee_tasks(client, first_name, last_name)