1C:Enterprise 8.3. Developer Guide. Contents

WEB SERVICE MECHANISM

The Web services mechanism in the 1C:Enterprise system supports the Service-Oriented Architecture (SOA).

SOA is an application architecture in which all functions are defined as independent services with callable interfaces. Calling these services in a specific order allows certain business processes to be implemented.

The service-oriented architecture offers a new approach to the creation of distributed information systems where software resources are considered as services delivered over the network. This approach provides for fast consolidation of distributed components – services – into a unified solution for supporting certain business processes.

The Web service mechanism allows to use 1C:Enterprise as a set of services in complex distributed and heterogeneous systems as well as integrate it with other industrial systems using the service-oriented architecture.

The functionality of the 1C:Enterprise configuration can be exported through Web services. Web services are defined in the configuration tree and become available to other information systems via publication on a Web server.

1C:Enterprise can also address third-party Web services both through static references defined in the configuration tree and by using dynamic references created using the 1C:Enterprise script (see fig. 309).

The 1C:Enterprise service architecture is based on a Service Manager. The Service Manager offers the following:

management of the pool of connections with infobases;

support of WSDL service descriptions;

implementation of an SOAP protocol, message serialization, call of the corresponding service.

Fig. 309. Web Services

The Service Manager is executed in the procedure of the service host which receives/sends messages from/to the Service Manager. An IIS or Apache Web server can be used as the service host.

The Service Manager contains the pool of connections providing interaction with 1C:Enterprise databases.

The Web service mechanism that is implemented in 1C:Enterprise supports the following standards:

SOAP 1.1

SOAP 1.2

WSDL 1.1

WS-I Basic Profile 1.1

HTTP 1.1

SSL 3.0/TLS 1.0

17.1. PROVISION OF FUNCTIONALITY THROUGH WEB SERVICES

To make 1C:Enterprise functionality available to external Web service users, do the following:

Create the required number of Web services in the configuration.

Publish Web services using a special Designer tool.

Web service publication is described in detail in "1C:Enterprise 8.3. Administrator Guide".

Creation of a Web service involves:

adding the Web service configuration object to the Metadata Tree;

describing operations provided by the Web service;

describing the operation parameters.

The Web service configuration object includes a module allowing created 1C:Enterprise script procedures to be executed when certain Web service operations are called. The parameter types of Web service operations are described using XDTO types and can represent either XDTO values or XDTO objects.

To call a Web service:

Select an appropriate infobase connection from the connection pool or create a connection if it does not exist.

Create a new session and call SessionParametersSetting event for the session (in the session module).

Call the required Web service method; please note that the SessionParametersSetting() handler is invoked (in the session module) every time a non-initialized session parameter is called.

TIP

It is not recommended to run resource-intensive operation in the SessionParametersSetting event handler.

SessionParametersSetting event of the session module is called in the privileged mode at the server. The invoked service module runs in the ordinary mode at the server.

The session module (see page 1-172) is used for initialization of session parameters and execution of a certain set of commands when any 1C:Enterprise Web service is called.

17.2. EXAMPLE OF WEB SERVICE IMPLEMENTATION

For example, assume that you need to create a 1C:Enterprise Web service that will use an invoice number to return its tabular section contents.

For the purposes of description of the return value, create an InvoiceData XDTO package with the http://www.MyCompany.ru/shipment namespace containing three types of XDTO objects:

Nomenclature – to transfer data of Nomenclature catalog items. This XDTO object type will have the following properties:

○ Description – string data type from the http://www.w3.org/2001/XMLSchema namespace;

○ FullDescr – string type from the http://www.w3.org/2001/XMLSchema namespace;

○ Barcode – string type from the http://www.w3.org/2001/XMLSchema namespace;

○ PurchasePrice – int type from the http://www.w3.org/2001/XMLSchema namespace.

InvoiceLine – to transfer data of a single invoice line. This XDTO object type will have the following properties:

○ Nomenclature – Nomenclature type from the http://www.MyCompany.ru/ shipment namespace. It is a reference to the XDTO object defined above;

○ Count – int type from the http://www.w3.org/2001/XMLSchema namespace;

○ Price – int type from the http://www.w3.org/2001/XMLSchema namespace; ○ Sum – int type from the http://www.w3.org/2001/XMLSchema namespace.

Invoice – to transfer data of all the invoice lines. This XDTO object type will have a single property:

○ Content – InvoiceLine type from the http://www.MyCompany.ru/shipment namespace. It is a reference to the XDTO object defined above. In order for this property to contain an unlimited number of values, its Upper Bound value should be set to -1.

After the required XDTO types are created, a new InvoiceData Web service needs to be added to the configuration with the following property settings:

Namespace URI – http://www.MyCompany.ru/shipment;

XDTO packages – InvoiceData;

Publication file name – shipment.1cws.

Get operation has to be defined for the created Web service with the following property settings:

Return value type – Invoice from http://www.MyCompany.ru/shipment namespace;

Value can be blank – checked; Procedure Name – Get.

The DocumentNumber parameter must be defined for the Get operation with the following property settings:

Value type – string type from the http://www.w3.org/2001/XMLSchema namespace;

Transfer direction – Input.

Now, open the Web service module and set the Get() function in it. This function will be executed when this Web service is called.

Function  Get(DocumentNumber) Export

// Get an invoice object using the passed number
DocumentRef = Documents.Invoice.FindByNumber(DocumentNumber,  CurrentDate());

If DocumentRef.IsEmpty() Then
Return Undefined;
EndIf;

Document = DocumentRef.GetObject();
// Get XDTO object types
NomenclatureType = XDTOFactory.Type(
"http://www.MyCompany.ru/shipment",
"Nomenclature");
InvoiceType = XDTOFactory.Type(
"http://www.MyCompany.ru/shipment",
"Invoice");
InvoiceLineType = XDTOFactory.Type(
"http://www.MyCompany.ru/shipment",
"InvoiceLine");

// Create XDTO object for the invoice
Invoice = XDTOFactory.Create(InvoiceType);

For Each DocumentString From Document.Content Do

// Create XDTO objects for the invoice line
// and nomenclature
InvoiceLine = XDTOFactory.Create(InvoiceLineType);
Nomenclature = XDTOFactory.Create(NomenclatureType);

// Fill in nomenclature properties
Nomenclature.Description =  DocumentString.Nomenclature.Description;
Nomenclature.FullDescr = DocumentString.Nomenclature.FullDescr;
Nomenclature.Barcode = DocumentString.Nomenclature.Barcode;
Nomenclature.PurchasePrice =  DocumentString.Nomenclature.PurchasePrice;

// Fill in invoice line properties
InvoiceLine.Nomenclature = Nomenclature;
InvoiceLine.Count = DocumentString.Count;
InvoiceLine.Price = DocumentString.Price;
InvoiceLine.Sum = DocumentString.Sum;

// Add an invoice line
Invoice.Content.Add(InvoiceLine);
EndDo;

// Return the invoice
Return Invoice;
EndFunction

Finally, publish the created Web service on the Web server, e.g., http://www.MyCompany.ru in the shipment catalog.

17.3. USING THIRD-PARTY VENDOR WEB SERVICES

The 1C:Enterprise system can use Web services supplied by third-party vendors in two ways:

through static references created in the configuration tree;

through dynamic references created using the 1C:Enterprise script.

Static references have a higher operation speed because the description of the supplier’s Web service is obtained once, on creation of the reference. When this Web service is called at a later time, the existing description of the Web service is used.

With dynamic references, the description of the supplier’s Web service is obtained by the 1C:Enterprise system every time this Web service is called, thereby slowing down the operation of this Web service. However, the advantage of this approach is that an up-to-date description of the supplier’s Web service is received. In order to obtain a current description of the Web service when using static references, the Designer has to import the WSDL description. The modified configuration then has to be saved.

17.3.1. Example of Using Static Web Service References

A call to the Web service (WS) created in the example above (see page 2-821) can be considered as an example of using third-party vendor Web services.

First of all, a new InvoiceData WS reference configuration object referring to the published service must be added to the configuration tree. For this purpose, the WSDL description of the published service has to be imported, with http://www.MyCompany.ru/shipment/ws/Shipment.1cws?wsdl specified as the URL. For a description of WSDL description import see page 1-244.

Then the following procedure can be created, for example, in the receipt module. It populates the tabular section of the document with the supplier’s invoice data obtained through the supplier’s Web service.

Procedure  GetInvoiceData(SupplierInvoiceNumber)
// Create WS proxy based on reference
// and run Get() operation
Proxy =  WSReferences.InvoiceData.CreateWSProxy("http://www.MyCompany.ru/shipment",
"InvoiceData",  "InvoiceDataSoap");
InvoiceData= Proxy.Get();
If InvoiceData = Undefined Then
Return;
EndIf;
// Fill in the receipt with obtained data
For Each InvLine From InvoiceData.Content Do
NewRow = DocumentObject.Content.Add();
NewRow.Count = InvLine.Count;
NewRow.Price = InvLine.Price;
NewRow.Sum = InvLine.Sum;
// Find nomenclature item using passed data
// (e.g., barcode)

NewRow.Nomenclature = Catalogs.Nomenclature.FindByAttribute("Barcode", InvLine.Nomenclature.Barcode);

EndDo;
EndProcedure

17.3.2. Example of Using Dynamic WS References

The only difference between the use of dynamic and static references is the WS proxy creation method and the fact that there is no need to create a WS reference in the configuration tree.

If we make a comparison with the example from the previous section, then unlike creation of a proxy based on a static reference, when using a dynamic reference the WS proxy is created with the help of a wizard in the following way:

//  Create WS proxy based on WS definition
//  and run Get() operation
Definition  = New WSDefinitions(
"http://www.MyCompany.ru/shipment/Shipment.1cws?wsdl");

Proxy  = New WSProxy(
Definition,
"http://www.MyCompany.ru/shipment",
"InvoiceData",
"InvoiceDataSoap");

InvoiceData=  Proxy.Get();

Compare this with creating WS proxy based on a static reference:

//  Create WS proxy based on reference
//  and run Get() operation
Proxy  = WSReferences.InvoiceData.
CreateWSProxy("http://www.MyCompany.ru/shipment",  "InvoiceData", "InvoiceDataSoap");

InvoiceData=  Proxy.Get();

17.4. EDITING WEB SERVICE PROPERTIES

The Main tab can be used to enter object name, synonym and comment.

The Operations tab is used to create subordinate Operations objects that can in turn have subordinate Parameters objects required for working with operations. Subordinate objects are described using the properties palette.

17.4.1. Operation Properties

Besides the common object configuration properties, Web service operation contains the following properties:

Return value type – a value type returned by the Web service operation. It can be XDTO value type or XDTO object type.

Value can be blank – indicates whether the returned value can have an undefined value.

In transaction – indicates whether or not the code of the Web service module is executed in the transaction. If the property is set, the transaction starts automatically when the Web service is called and upon completion the transaction is either submitted or rolled back (depending on the results of execution). If the property is not set, the transaction is not started when Web service module execution starts.

Method name – name of the Web service module export procedure that is executed when this property is called.

17.4.2. Parameter Properties

Besides the common object configuration properties, the Web service operation parameter contains the following properties:

Value type – a value type of the Web service operation parameter. It can be XDTO value type or XDTO object type.

Value can be blank – indicates whether the operation parameter value can take an undefined value.

Transfer direction – defines the direction of data transfer using this parameter. Available values:

○ Input – means that the parameter is used for data transmission to the Web service;

○ Output – means that the parameter is used for data transmission from the Web service;

○ Input – Output – means that the parameter can be used for both transmission and retrieval of data to/from the Web service.

The Subsystems tab shows the subsystems to which the objects of this type belong.

On the Other tab, you can set the following properties:

Namespace URI – contains URI of the Web service namespace. Each Web service can be uniquely identified by its name and the URI of the namespace it belongs to.

XDTO packages – a list of XDTO packages with the types that can be used as return value types for operations and parameter types of Web service operations.

Publishing file name – name of the Web service description file located on the Web server.

The Module button opens the Web service module editor.

1C:Enterprise 8.3. Developer Guide. Chapter 17. Web Service Mechanism