Connector: Overview of Methods

The connector is a tool for integrating Bitrix24 with external data systems. It is responsible for connecting to third-party APIs and databases, importing data for analytics and reporting.

Each connector contains settings for working with a specific source:

• endpoints — URLs for sending HTTP requests,
• authorization parameters.

Quick navigation: all methods

Connector's Relationship with Sources and DatasetsConnector's Relationship with Sources and Datasets

The connector is the top level in the data hierarchy within the BIconnector module:

• Connector establishes a connection with an external data source.
• Source defines which specific data is available from the connected service.
• Dataset forms the final set of data that can be used in reports and analytics.

Description of Connector FieldsDescription of Connector Fields

Settings FieldSettings Field

The settings field contains an array of parameters necessary for configuring data sources. Each parameter is an object with the following structure:

• code — parameter code, used as the identifier for the parameter, this is how parameters are passed to the external source.
• name — parameter name, which will be displayed in the interface, in the "Analyst's workspace" section.
• type — parameter type, currently only STRING is supported.

{
            "code": "code_value",
            "name": "name_value",
            "type": "type_value"
        }
        

Connector EndpointsConnector Endpoints

urlCheckurlCheck

The urlCheck endpoint performs two key functions:

1. Checks the availability of the connection to the external source.
2. Authenticates the user.

The endpoint is called:

• when creating a new connection,
• when editing an existing connection,
• when creating a dataset.

A POST request is sent to the endpoint with the following parameters:

• setting_code_n — code of the connector's settings parameter.
• settings_value_n — value of this parameter related to the specific source.

{
          "connection": {
            "setting_code_1": "settings_value_1",
            ...,
            "setting_code_n": "settings_value_n"
          }
        }
        

Depending on availability, the endpoint returns information about the status of the source. Requirements for the response format from the endpoint to the request from Bitrix24: the response must not be empty, HTTP status: 200. The response format is flexible.
A request to the endpoint for connection verification can be sent from the interface, in the "Analyst's workspace" section.

urlTableListurlTableList

The urlTableList endpoint returns a list of available tables in JSON format. The endpoint will return tables that match the search query. The endpoint is called when creating a dataset through the interface.

A POST request is sent to the endpoint with the following parameters:

• searchString — value of the search string, searches tables by externalCode.
• setting_code_n — code of the connector's settings parameter.
• settings_value_n — value of this parameter related to the specific source.

{
          "searchString": "search_value",
          "connection": {
            "setting_code_1": "settings_value_1",
            ...,
            "setting_code_n": "settings_value_n"
          }
        }
        

The response returns an array of objects corresponding to the request, with the structure:

• code — name of the dataset that will be used in Bitrix24.
• title — name of the dataset in the external source. The search is performed based on this field.

{
            'code' => 'dataset_name',
            'title' => 'externalName'
        }
        

urlTableDescriptionurlTableDescription

The urlTableDescription endpoint returns a list of fields for a specific table in JSON format. The endpoint is called when creating a dataset through the interface.

A POST request is sent to the endpoint with the following parameters:

• table — externalCode of the dataset for which the description is requested.
• setting_code_n — code of the connector's settings parameter.
• settings_value_n — value of this parameter related to the specific source.

{
          "name": "entityName",
          "connection": {
            "setting_code_1": "settings_value_1",
            ...,
            "setting_code_n": "settings_value_n"
          }
        }
        

The response returns an array of fields with the structure:

• code — code of the dataset field.
• name — name of the dataset field.
• type — field type, supported values: int, string, double, date, datetime.

{
            'code' => "code_value",
            'name' => "title_value",
            'type' => "type_value"
        }
        

urlDataurlData

The urlData endpoint returns data from a specific table in JSON format.

The endpoint is called:

• when creating a dataset through the interface,
• when synchronizing dataset fields through the interface,
• when executing requests to retrieve data for the BI Builder.

A POST request is sent to the endpoint with the following parameters:

• select — selection of dataset fields.
• filter — filter by dataset fields.
• limit — limit of dataset selection.
• table — externalCode of the dataset for which data is requested.
• setting_code_n — code of the connector's settings parameter.
• settings_value_n — value of this parameter related to the specific source.

{
          "select": **array**,
          "filter": **object**,
          "limit": **int**,
          "table": "entityName",
          "connection": {
            "setting_code_1": "settings_value_1",
            ...,
            "setting_code_n": "settings_value_n"
          }
        }
        

The response returns an array of fields with the structure:

• FIELD_N — field code.
• VALUE_ROW_M_N — values of field N in row M.

[
        ["FIELD_1","FIELD_2",...,"FIELD_N"],
        [VALUE_ROW_1_1,VALUE_ROW_1_2,...,VALUE_ROW_1_N,],
        [VALUE_ROW_2_1,VALUE_ROW_2_2,...,VALUE_ROW_2_N,]
        ...
        ,[VALUE_ROW_M_1,VALUE_ROW_M_2,...,VALUE_ROW_M_N,]
        ]
        

Field ParametersField Parameters

Overview of MethodsOverview of Methods

Scope: biconnector

Who can execute methods: user with access to the "Analyst's workspace" section

Continue LearningContinue Learning

• Example of creating a connector based on B24PHPSDK
• Meetup about creating a connector