Appendix 6.  Internet services for retrieving shared infobase list and client distribution package

<< Prev   Next >>

6.1. Retrieving the shared infobase list

6.1.1. General information

When working remotely (for example, via a web server) you need to retrieve the shared infobase list. However you cannot use the CommonInfoBases parameter of configuration file 1cestart.cfg to retrieve the list. You can get the shared infobase list if it was published using the Internet service. To get the list, you can use either HTTP requests or web services.

If the shared infobase list is retrieved using HTTP connection, the certificate of the server used to retrieve the list is checked using the certificates of the root certificate authority obtained from the corresponding OS system storage.

6.1.2. Using web services

To get the shared infobase list through a web service, you need to publish a specific web service that will return the list. This web service is described below in more detail.

6.1.2.1. Overview

The interactive launcher (1cv8s) can get the shared infobase list either from a local network or from the Internet. To retrieve the shared bases list from the Internet, you need to start the interactive launcher and specify the address of the list (the InternetService or WebCommonInfoBases parameter in file 1cestart.cfg).

The shared infobase list retrieval procedure must meet the following requirements:

• The WebCommonInfoBases.CheckInfoBases() method is called anonymously
• The WebCommonInfoBases.GetInfoBases() method is called with authentication
• The infobase that returns the shared infobase lists must contain a list of users allowed to request these lists.

First, the WebCommonInfoBases.CheckInfoBases() method is called (anonymously). If the launcher is started manually for the first time for this computer and this user, the ClientID and InfoBasesCheckCode parameters take the value 00000000-0000-0000-0000-000000000000. If the launcher is not started for the first time, the client code and the code of the current shared infobases list are passed as parameters. The web service method determines whether the shared infobase list for the client needs to be updated. If the update is needed, ‑the  InfoBasesChanged output parameter must be set to True and the URL parameter must contain the address of the web service that implements the WebCommonInfoBases.GetInfoBases() method (requires authentication). Otherwise, InfoBasesChanged must be set to False and URL must contain an empty string.

The algorithm of checking for the changes in the shared infobase list is not regulated and can be arbitrary. Please note that the launcher does not calculate the code value identifying the shared infobase list but simply stores the value that was passed during the previous call of the web service.

If results of the call of WebCommonInfoBases.CheckInfoBases() method indicate that the list needs to be updated, the launcher calls the WebCommonInfoBases.GetInfoBases() method of the web service. The web service is located at the address returned by the WebCommonInfoBases.CheckInfoBases() function in its URL parameter. The GetInfoBases() method must match the user on whose behalf the web service is authenticated with a client code. The mapping can be “personal” ‑when the user identifies himself or herself with personal username and password and receives the personal shared infobase list. In addition, the mapping can be a “role-based” ‑when user identifies his or her belonging to a certain role, such as Operator, Storekeeper, etc., and obtains the shared infobase list common to all users with the same role. You should note that in the first case, the infobase implementing the GetInfoBases() method needs to contain the list of all users who can run the 1cv8s launcher connected to this web service. In the second case, the list of users can contain the role names only.

The GetInfoBases() method must return three values:

• Client code (if not specified)
• The list of shared infobases in v8i format
• The code value identifying the passed infobase list This value will be passed to  the WebCommonInfoBases.CheckInfoBases() method at the next check for whether the shared infobase list needs to be updated.

If the shared infobase list is retrieved for the first time, the client code (the ClientID parameter) is 00000000-0000-0000-0000-000000000000.

Please also consider the following:

• The infobase implementing the WebCommonInfoBases web service needs to be published in two different publications.‑ This is because calling the CheckInfoBases() and GetInfoBases() methods requires different levels of authentication.
• The anonymous access is organized by explicitly specifying the user on whose behalf the access is performed in the default.vrd file.
• The user on whose behalf the anonymous access is organized should not be able to call the method for retrieving the infobase list. The user should only indicate whether the list has changed for the passed ClientID value.
• All publications serving the WebCommonInfoBases web service must prohibit the web client.
• If the shared infobase list is used by the mobile client, this file must contain the correct values of the MobilePublicKey parameter for the infobases to be displayed in the mobile client.

6.1.2.2. Web service description

Web service name: WebCommonInfoBases. The timeout for execution of any web service method is 3 seconds.

The web service methods are listed below.

CheckInfoBases

Description:

This method is used by the 1cv8s launcher to determine whether the shared infobase list needs to be retrieved.

Parameters:

Type: String. Contains the client ID used to check whether the shared infobase list needs to be updated.

Type: String. Identifies the shared infobase list. The code must uniquely identify the current shared infobase list. If the list is modified in any way, the code needs to be assigned a new value that was not previously used for this client ID.

Type: Boolean. Indicates that the shared infobase list must be retrieved again.

Type: String. The URL to be requested if the shared infobase list has changed since the last call.

Returns:

Arbitrary type, the value is ignored.

getInfoBases

Description:

Parameters:

Type: String. Contains the client ID for which the shared infobase list is retrieved. If the client ID is not specified (or equal to 00000000-0000-0000-0000-000000000000), the method assigns the client ID and returns it in this parameter.

Type: String. Value of the code identifying the shared infobase list returned by this method in the InfoBases parameter.

Type: String. The shared infobase list in the v8i format.

Returns:

Arbitrary type, the value is ignored.

6.1.2.3. Implementation example

This section reviews an example of web service used to retrieve the shared infobase list.

A simple configuration including one catalog and one web service is used as a web service.

The catalog is organized as follows:

• Name SaredInfoBasesList.
• Code type String, length is 36 characters.
• Attributes:
  • Name ListCode, type UniqueIdentifier.
  • Name IBList, type String, unlimited length.
• The remaining parameters have default values.

This catalog will store the list of customer IDs (standard attribute Code), the shared infobase list (attribute IBList) and the current version of the infobase list (attribute ListCode) determined when the list was last retrieved for this client. The version of the list is a unique identifier and it is changed each time a directory item is saved. For this purpose in the object module, the handler BeforeWrite is defined:

Procedure BeforeWrite(Cancel)
 ListCode = New UniqueIdentifier;
EndProcedure

In addition in the configuration the WebCommonInfoBases web service must be created with the following operations defined:

• CheckInfoBases, the Return Value Type property is set to string, the Possibly Empty Value checkbox is set. The remaining properties are set to default values.
• GetInfoBases, the Return Value Type property is set to string, the Possibly Empty Value checkbox is set. The remaining properties are set to default values.

Text of the web service operations:

Function CheckInfoBases(ClientID, InfoBasesCheckCode, InfoBaseChanged, URL)

 If ClientID = "00000000-0000-0000-0000-000000000000"
   And InfoBasesCheckCode = "00000000-0000-0000-0000-000000000000" Then
   // the first request of the client
   InfoBaseChanged = True;
   URL = "/listservice2/ws/WebCommonInfoBases";
   Return "";
 EndIf;         
 Client = Catalogs.SharedBaseList.FindByCode(ClientID);
 If Client.Empty() Then
   // no such client
   InfoBaseChanged = False;
 Else
   // check that the list on the client side and our list are the same
   If InfoBasesCheckCode = Client.ListCode Then
    // the list is not changed
    InfoBaseChanged = False;
    URL = "";
   Else
    // the list is changed
    InfoBaseChanged = True;
    URL = "/listservice2/ws/WebCommonInfoBases";
   EndIf;         
 EndIf;         
 Return "";
 EndFunction
 
Function GetInfoBases(ClientID, InfoBasesCheckCode, InfoBases)

 If ClientID = "00000000-0000-0000-0000-000000000000" Then
   CurUser = InfoBaseUser.CurrentUser();
   // need to add new client
   // as a code of the catalog element the unique identifier 
   // of the infobase user will be used
   Object = Catalogs.SharedBaseList.NewElement();
   Object.Code = String (CurUser.UniqueIdentifier);
   // the client name will be equal to the user name 
   Object.Name = CurUser.Name;
   // the IB list is empty at the first call
   Object.IBList = "";
   Object.Write();
   // to form the returned values of the web service
   InfoBasesCheckCode = Object.CodeList;
   InfoBases = Object.IBList;
   ClientID = Object.Code;
 Else
   // here we get the data for the existing client code
   Client = Catalogs.SharedBaseList.FindByCode(ClientID);
   If Client.Empty() Then
    // no such client
    InfoBasesCheckCode = "";
    InfoBases = "";
   Else
    InfoBasesCheckCode = Client.CodeList;
    InfoBases = Client.IBList;
   EndIf;         
 EndIf;         
 Return "";

EndFunction

After creating the configuration, the web service should be published to the web server twice. Then the addresses of published web services should be stored. Suppose that web services are published at the addresses:

• http://localhost/listservice ‑ anonimous web service;
• http://localhost/listservice2 ‑ the web service requiring authentication;

The infobase should contain users: Anonymous, and, for example, users Operator, Storekeeper, Accountant.

The default.vrd file, which describes the publication at http://localhost/listservice, is as follows:

<?xml version="1.0" encoding="UTF-8"?>
<point xmlns="http://v8.1c.ru/8.2/virtual-resource-system"
   xmlns:xs="http://www.w3.org/2001/XMLSchema"
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   base="/listservice"
   ib="File=X:\DB\ListBase;Usr=Anonimous"
   enable="false">
 <ws>
   <point name="WebCommonInfoBases"
     enable="true"/>
 </ws>
</point>

The default.vrd file, which describes the publication at http://localhost/listservice2, is as follows:

<?xml version="1.0" encoding="UTF-8"?>
<point xmlns="http://v8.1c.ru/8.2/virtual-resource-system"
   xmlns:xs="http://www.w3.org/2001/XMLSchema"
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   base="/listservice2"
   ib="File= X:\DB\ListBase;"
  enable="false">
 <ws>
   <point name="WebCommonInfoBases"
     enable="true"/>
 </ws>
</point>

In the settings of the web server where you published the web service for retrieving the shared infobase list, the HTTP HEAD request should be disabled (at least for virtual catalogs to access the web service). Otherwise, the web service will not be used.

In the launch window setup form, you need to add a web service with the address  shown above including the suffix ws: http://localhost/listservice/ws/.

After completing the configuration you should run the launcher. When prompted to enter a username and password to access the 1C:Enterprise web service, you should enter the names Operator, Storekeeper, Accountant. The corresponding entries are added to the SharedBaseList catalog. If you place into the IBList attribute of each catalog element your list in the v8i format, this list will be added to the list of infobases of the launcher after authentication.

6.2. Getting the client application distribution package

6.2.1. General information

When operating remotely (using web server), it is necessary to automatically get the distribution package of the client application when the system version is changed on the 1C:Enterprise server (or on the web server). In this case the search for a new version using the DistributiveLocation parameter of the configuration files may not give the result. To get the distribution package, you can use the option to publish the client application distribution package using the web service. To get the list, you can use either HTTP requests or web services.

If you get the client application distribution package using the HTTPS connection, then the server certificate (from which the distribution package is requested) is verified using the certificates of the root certification authorities, obtained from the system storage of the corresponding OS.

6.2.2. Using web services

To get the client application distribution package using web service you need to publish a special web service that return this distribution package. This web service is described below in more detail.

6.2.2.1. Overview

If the thin client (1cv8c) is launched with command /AppAutoCheckVersion, then it attempts to select the version of the thin client if it does not match the version of the 1C:Enterprise server or the web server extension. For this purpose the following three mechanisms are used (in order of use):

• Search for the distribution package in the local network ‑ using the parameters of configuration files (1cestart.cfg and 1cescmn.cfg) DistributiveLocation.
• Getting the client application distribution package at the URL specified in the default.vrd (attribute of the point element) or conf.cfg configuration files (PublishDistributiveLocation * parameters). The priority value is the value specified in the default.vrd file.
• Get the file using the web service for obtaining the client application distribution package. The web service address must be specified in the 1cestart.cfg configuration file (parameters InternetService or WebDistributiveLocation) or in the launch window settings dialog box.

  The thin client analyzes the result of the request to the web service. If the web service returns 0 in the Size parameter, then it is considered that the required client application distribution package does not exist, and the error is generated that the versions of the client application and the server do not match. Otherwise, the user is prompted to download and install the client application, and the size of the distribution package received is shown. If the answer is positive, the new version is downloaded and installed. Then the necessary version of the client application is restarted. When you import the distribution package file, the timeout for the operation is 600 seconds. When executing distribution package import, redirect on the web server side is not supported.

6.2.2.2. Web service description

Web service name: WebDistributiveLocation. The timeout for execution of any web service method is 3 seconds.

The web service methods are listed below.

GetDistributiveInfo

Description:

This method is used by the thin client (1cv8c) to get the required version of the client application distribution package in the following cases:

• When connecting via a web server in the client-server variant the version of the client application doesn't match the server version.
• When connecting via a web server in the file variant the version of the client application doesn't match the server extension version.

Parameters:

Type: String. The type of operating system for which you need to get the client application distribution package.

Values: Windows, MacOS.

Type: String. The architecture of operating system for which you need to get the client application distribution package.

Values: x86, x86_64.

Type: String. The version number of the client application for which you need to get the client application distribution package.

Type: Number. The size of the client application distribution package (in bytes). If the requested distribution package is missing, you must return the value 0.

Type: String. URL for downloading the client application distribution package. When generating the URL you should remember that the distribution package file should be accessible to the web server. In addition, the user getting the distribution package should also have permissions to download this file.

The client application distribution package is a zip archive of distribution files.

Returns:

Arbitrary type, the value is ignored.

6.2.2.3. Implementation example

Let us consider an example of web service to get the client application distribution package.

A simple configuration is used as the web service. It implements the web service only and does not contain any other configuration objects. The client application distribution packages are located in a special directory to which the web server should have access. In this configuration the WebDistributiveLocation web service must be created, for which: the operation GetDistributiveInfo is defined, the Return Value Type property is set to string, the Possibly Empty Value checkbox is set. The remaining properties are set to default values.

Text of the web service operations:

Function GetDistributiveInfo(OS, Arch, Version, Size, URL)

 DistributiveDirectory = "C:\inetpub\Distribs\";
 DistributiveURL = "http://host/site/distribs/";
 // make the zip file name
 FileName = "tc-" + Lower(OS) + "-" + Arch + "-" + Version + ".zip";
 Archive = New File(DistributiveDirectory + FileName);
 If Archive.Exists() Then
   Size = Archive.Size();
   URL = DistributiveURL + FileName;
 Else
   Size = 0;
   URL = "";
 EndIf;         
 Return "";
EndFunction

You need to specify the correct values in the DistributionPackageDirectory and DistributionPackageURL variables that correspond to the real name of the distribution package directory of the client application (when accessing it from the Web-service, ‑ the DistributionPackageDirectory variable and when accessing it through the web service, the ‑ DistributionPackageURL variable).

The name of the file with the distribution package should be tc-windows-x86-8.3.3.100.zip or similar (depending on the OS type and the requested client application architecture). The name of the archive file is determined by the program code of the demonstration web service shown above.

After creating the configuration, the web service should be published to the web server. Then the address of published web services should be stored. Suppose the web service is published at http://localhost/getdistr.

In the launch window setup form, you need to add a web service with the address shown above including the suffix ws: http://localhost/getdistr/ws. Now, to get the distribution package, this web service is requested. If the directory DistributionDirectory (on the computer with the web service) contains the zip archive with correct distribution package, ‑ this file is transferred to the computer that requested the distribution package.

<< Prev   Next >>