Show Access Permission Selection Dialog BX24.selectAccess

BX24.selectAccess(value: array, callback: callable): void;
        BX24.selectAccess(callback: callable): void;
        BX24.selectAccess(title: string, value: array, callback: callable): void;
        

The method BX24.selectAccess displays a standard access permission selection dialog. In the dialog, the user selects employees, departments, workgroups, and other recipient categories, and the application receives their access codes.

Bitrix24 itself renders the dialog on top of the application frame. The application does not have to assemble the list of recipients or check the permissions to view it: in the dialog, the user sees only the objects they have access to. The dialog requires no scope of its own — it opens the Bitrix24 interface instead of calling the REST API.

The method can be called only from an application embedded in the Bitrix24 frame. If the page is opened outside Bitrix24, the library does not initialize and throws an exception when it is included.

Call the method inside the BX24.init handler. The library does not defer the dialog itself until the initialization, but the functions that are usually called from the callback do not work before it — BX24.userOption.set, for example.

Method ParametersMethod Parameters

Required parameters are marked with *

Code ExamplesCode Examples

How to Use Examples in Documentation

Show the dialog without restrictions and output the selected codes:

BX24.init(() => {
            BX24.selectAccess((selected) => {
                selected.forEach((item) => {
                    console.log(item.provider, item.id, item.name);
                });
            });
        });
        

Block part of the codes and retain the selection in the user configurations, so that the dialog is not shown every time the application is opened:

BX24.init(() => {
            // AU and U1 are already retained, so they cannot be selected again
            BX24.selectAccess(['AU', 'U1'], (selected) => {
                const codes = selected.map((item) => item.id);
        
                // an empty selection does not overwrite the retained codes
                if (codes.length === 0)
                {
                    return;
                }
        
                BX24.userOption.set('recipients', codes.join(','));
            });
        });
        

Response HandlingResponse Handling

The dialog does not return the data directly: the result of the selection arrives in the callback function as an array of objects. The objects are grouped by the provider value, and within a group the order matches the order of selection. Do not rely on the position of an element in the array — identify an object by the provider and id fields.

If the user closes the dialog — with the cross, the close button, or the Esc key — the callback function is not invoked. If the user confirms the selection without checking anything, the callback receives an empty array, so check the length of the array before you retain the result.

[
            {
                "provider": "intranet",
                "id": "IU1",
                "name": "Klaus Weber"
            },
            {
                "provider": "socnetgroup",
                "id": "SG4_K",
                "name": "Sales Department: All group members"
            }
        ]
        

The user confirmed an empty selection:

[]
        

Returned DataReturned Data

Access CodesAccess Codes

A workgroup cannot be selected as a whole: in the dialog, the user selects a role in the group, so the code always arrives with the _A, _E, or _K suffix.

The numeric part of a code is the identifier of the object in Bitrix24. From IU1 and U1 you get ID = 1 for the methods that work with a user, for example for user.get.

The whole code is passed to the parameters of the REST API methods that accept access permissions. In the ACCESS parameter of the entity.rights method, for example, the code becomes the key of an object, and the value is the permission level: {"U1": "W", "AU": "R"}.

The set of available codes depends on the particular Bitrix24 account: the application dialog has no tab with user groups, and the content of the other tabs is defined by the installed modules and by the permissions of the current user. The names of the codes are returned by the access.name method — it queries the Bitrix24 access permission providers and recognizes the IU, D, DR, and SG codes among others.

Error HandlingError Handling

The dialog returns no error codes. The cases when there is no result are covered in the Response Handling section.

Continue LearningContinue Learning

• System Dialogs: Overview of Methods
• Show User Single Selection Dialog BX24.selectUser
• Show Multiple User Selection Dialog BX24.selectUsers
• Call the CRM Object Selection Dialog BX24.selectCRM
• Get Access Permission Names access.name
• Set Configurations for a User BX24.userOption.set