Peculiarities of mass-market applications

As previously discussed in our lesson on REST events, in a full-fledged mass-market application, it is essential to secure and renew the authorization tokens obtained during installation on Bitrix24.

Given that a mass-market application released on Bitrix24.Market can be utilized simultaneously across numerous portals, it is imperative that the application indicate the specific portal being addressed in subsequent REST request calls.

This particularity is prominently displayed in event handlers, thus, in this tutorial, we will demonstrate how to utilize our SDK CRest in the instance of an application being installed on multiple portals while retaining its business logic - which will automatically format names in CRM contacts to always start with capital letters.

To start, click the “New Application” button and select the primary region for future solution publication. In the solution form, click the "Create" button, specify the type as "Use REST API," and confirm that the CRM has been added to the list of scopes.

Download the attached example and upload it to your server as previously instructed in our lessons on local integrations. Insert the application path in the version form, as previously done. Copy the values from the client_id and client_secret fields and paste them into the corresponding constants in the settings.php file.

Let us examine the example code, beginning with the cextrest.php file. In this file, we will write a descendant of the standard CRest class, equipped to handle authorization tokens from various portals.

To commence, we will add an internal variable to the class, responsible for indicating the specific portal to which REST requests will be directed. As the value of this variable, we will utilize the Bitrix24 member_id portal identifier. While it may seem more suitable to use portal addresses, in practice, the portal address can be altered by the user, including both Bitrix24 cloud and on-premise. The member_id, in terms of uniqueness, is a much more dependable alternative. Next, we will inherit several basic methods from the existing class, instructing it to save and read authorization data for each Bitrix24 portal individually.

The base class, as you are aware, previously stored authorization tokens in a file named settings.json. However, tokens are now stored in separate files within the settings folder, with each file bearing a name derived from the member_id value.

In practical terms, it would likely be more efficient to store tokens and other portal parameters through a database, rather than relying on individual files.

The install.php file closely mirrors the example demonstrated in the lesson regarding REST events. Instead of utilizing the CRest class, however, access was granted to the CExtRest inheritor class.

Returning to the Developer area, this page provides the capability to install the application within your Bitrix24 and test its functionality before publishing it on the Bitrix24.Market.

Simply specify the address of the Bitrix24 portal where you possess administrator privileges and click Install. This will direct you to the portal and initiate the application installation process. Upon publishing the application on the Bitrix24.Market, and with the addition of descriptive information and screenshots, the installation process will appear more professional. Currently, however, our goal is simply to ensure the technical functionality of the application.

Upon successful installation, Bitrix24 will automatically open the application due to the presence of a user interface.

Let us proceed to the CRM contacts and add a new contact, inputting name values in a variety of formats. Refreshing the list will reveal that the handler from our app has transformed the entered name into a standardized format.

Let us examine the inner workings of this process.

First, let us ensure that the authorization tokens of the current portal have been properly saved, as anticipated, in individual files, containing the correct data including the address of the portal in question.

Second, let us examine the exact data that Bitrix24 transmits to our handler through its POST request.

Though we have already observed this array, now let us pay heed to the parameters within the auth key that are delivered in the POST request. This is where we need to obtain the portal ID, communicating it to the CExtRest class, specifying which portal it should work with.

This is accomplished by invoking the setCurrentBitrix24 method in the handler's event handler. Now, our class is informed of the specific file from which it must retrieve the saved authorization tokens. This is the only alteration we had to make to the existing event handler example in terms of business logic.

We still call the crm.contact.get method to obtain the complete information regarding the newly added or altered contact, taking its identifier from the POST request, transforming the first, middle and last names into the desired format, and updating the contact in the current Bitrix24.

Let us verify that the process will function properly if we install the application on another Bitrix24. We shall return to the developer area, input the address of another Bitrix24, and install the application there.

We shall then verify that a new file containing the requisite authorization parameters has been created on the application side. Next, we shall navigate to the contact list in this new Bitrix24 and add a new contact, knowing that its first and last names are incorrect. After refreshing the contact list, we shall confirm that the application's handler has successfully executed its task.