1C:Enterprise 8. Practical Developer’s Guide. Lesson 6. Accumulation Registers.

Lesson 6. Accumulation Registers

Estimated duration of the lesson is 50 minutes.

CONTENT:

At this lesson we will familiarize ourselves with the Accumulation Register configuration object. You will learn what this object is used for, how it is structured, and what its main properties are.

Next we will create one of the accumulation registers that will be used in our configuration and display modifications of data in the process of working with the earlier created documents.

Why We Need an Accumulation Register

We have now come to one of the key points in development of any configuration - creating a mechanism to account for the accumulation of data.

It would seem that we have already created everything we need. We know what we receive and expend (catalogs), and we have a means of receiving and expending (documents). All we need to do now is build several reports and automation of Jack of All Trades will be completed.

However, this is not the case.

First of all, we could certainly obtain all the required output data by analyzing documents. But imagine that tomorrow Jack of All Trades decides to slightly modify its business processes and we will need to introduce a new document (or multiple documents!) to our configuration.

For instance, now we assume that Jack of All Trades receives goods and then expends them. Then the management wanted to strengthen its resource management and decided to receive goods at the company's main warehouse and then issue them to accountable officers. In this case, we will need to add another document to the configuration in order to report the movement of resources between the main warehouse and the accountable officers. Obviously, that will force us to revise all the reports that we have created up to that point in order to account for the changes introduced in the new document. And imagine what that would mean if our configuration had twenty documents instead of two!

Second, reports that rely on the analysis of documents will operate pretty slowly, which will irritate users and dissatisfy management.

Therefore, 1C:Enterprise has some configuration objects that allow developers to create database structures that support accumulation of information in a format that facilitates subsequent analysis. Using these data repositories lets us accumulate data provided by various documents (or other database objects), while at the same time allowing us to easily create the reports we need or use the data in the configuration's functions (fig. 6.1).

1C:Enterprise 8. Practical Developer's Guide. Lesson 6. Accumulation Registers

Fig. 6.1. Functioning of the Configuration

A configuration contains several objects that are referred to as registers. These objects are used to generate these repositories. Now, we will discuss one of them.

Definition of an Accumulation Register

A configuration object named accumulation register is intended to describe the structure of data accumulation. The platform uses the Accumulation Register configuration object as the basis to create database tables that will accumulate data provided by various database objects.

This data will be stored in the tables as individual records where all the records have an identical structure, as specified in the Designer (fig. 6.2).

Based on the accumulation register table of register records, the system calculates the table of register totals that stores the totals at the moment of last register record in the database (current totals).

The accumulation register's distinctive feature is that it is not designed to be edited directly by the user.

The developer may allow users to edit the accumulation register if required. However, the intent of the accumulation register is to be modified based on performance of other database objects, rather than through direct user intervention.

The main purpose of an accumulation register is to accumulate numerical information in multidimensional arrays, which are declared by the developer in a corresponding Accumulation Register object and exist as subordinate configuration objects.

1C:Enterprise 8. Practical Developer's Guide. Lesson 6. Accumulation Registers

Fig. 6.2. The Balance of Goods accumulation register in the Designer and in the Database

The types of numerical information stored in an accumulation register are referred to as resources and are likewise subordinate objects and are declared in the Designer.

For example, an accumulation register might accumulate information on the quantity and total number of products in the warehouses. In that case it will have the dimensions Product and Warehouse and the resources Quantity and Total (see fig. 6.2).

Changes to the accumulation register generally occur when a document is posted, and result in addition of a certain number of records. Each record contains the dimension values, incremented values for the resources, a link to the document that caused the change (the recorder) and the "direction" of the increment (receipt or expense). This set of records is referred to as register records of an accumulation register. A recorder is an infobase object (normally a document) that causes a register record. Such an object should always correspond to a register record.

An accumulation register can also contain additional information to describe every register record. The structure of this additional information is specified by the developer using the attributes of an Accumulation Register configuration object.

LEARN MORE!

For details on the structure of the 1C:Enterprise script objects intended to work with the accumulation registers, see "Developer's Quick Reference. Accumulation Registers".

Adding an Accumulation Register

Now that we know what an accumulation register is intended for, we will discuss how to use it in our example.

We are mostly concerned in the information about the quantity and type of materials available in our warehouses. To accumulate this information we will create a register named BalanceOfMaterials.

In the Designer Mode

Open our practice configuration in the Designer and add a new Accumulation Register configuration object.

To do so, highlight the Accumulation Registers branch in the configuration object tree and click Add in the configuration window command bar.

In the configuration object editor that opens use the Main tab to enter a name for the register - BalanceOfMaterials.

We will also enter Register Records of Balance of Materials for the Extended list presentation. This title will be displayed in the window of the register records list.

Click Next and navigate to the Subsystems tab.

The logics of our configuration suggest that this register should be available in the sections Goods Management, Rendering Services, and Accounting.

So we will check these subsystems in the list (fig. 6.3).

1C:Enterprise 8. Practical Developer's Guide. Lesson 6. Accumulation Registers

Fig. 6.3. Defining a list of subsystems where a register will be displayed

Select the Data tab and proceed to creating the register's structure. We will create the dimensions of the register:

  • Material, type CatalogRef.Products;
  • Warehouse, type CatalogRef.Warehouses.

To do so, select the Dimensions branch and click Add in the command bar of the window (fig. 6.4).

1C:Enterprise 8. Practical Developer's Guide. Lesson 6. Accumulation Registers

Fig. 6.4. Creating dimensions of a register

Next we will create a resource named Quantity with the length of 15 and 3 decimal places. To do so, highlight the Resources branch and click Add in the command bar of the window (fig. 6.5).

1C:Enterprise 8. Practical Developer's Guide. Lesson 6. Accumulation Registers

Once we are done with these steps, the BalanceOfMaterials register should look as shown on the figure 6.6.

1C:Enterprise 8. Practical Developer's Guide. Lesson 6. Accumulation Registers

At this point, if you were to try to launch 1C:Enterprise in the debugging mode, an error message would be displayed: "AccumulationRegister.

BalanceOfMaterials: No document is configured as a recorder for this register." This message confirms the fact that the purpose of an accumulation register is to accumulate data provided by various documents.

So we will generate register records of the BalanceOfMaterials accumulation register in the process of posting two documents we have created: ReceiptOfGoods and ServicesRendered.

Register Records of a Document

A register record of a document is a record in a register that is created when a document is posted and reflects the changes produced by that document.

Open the configuration object editor for the ReceiptOfGoods Document. Navigate to the Register Records tab, expand the list Accumulation Registers and check the accumulation register named BalanceOfMaterials (fig. 6.7).

1C:Enterprise 8. Practical Developer's Guide. Lesson 6. Accumulation Registers

Fig. 6.7. Creating a register records of the ReceiptOfGoods document  in the BalanceOfMaterials register

Note that as soon as the selected register is checked, the Register Records Wizard button becomes active. Click this button and use the wizard.

The wizard is straightforward. The Registers list displays the registers where the document can create register records. In our case, the only register available so far is BalanceOfMaterials.

The list named Document Attributes should contain the initial data used to create register records, i.e. the attribute of the ReceiptOfGoods document.

In the table Field - Expression specify the formulas used to calculate the values for the dimensions and resources of the register when a register record is created (fig. 6.8).

1C:Enterprise 8. Practical Developer's Guide. Lesson 6. Accumulation Registers

Note that by default the wizard prompts you to create a receipt register record (Register Record Type - Receipt, the + symbol next to the name of the register) for the BalanceOfMaterials register. This is fine with us since the document is ReceiptOfGoods and is intended to record received materials.

In the Tabular Section selection field, we will select the tabular section of our document - Materials.

The list of document attributes that is already populated by the attributes of the document header, will have the attributes of the tabular section added.

Now click the Fill Expressions button.

In the lower window, the relationships between register fields (dimensions and resources) will be generated along with the expressions to calculate them (fig. 6.9).

As you can see, the register records wizard has defined the relationships appropriately: for material, it took material from the document's tabular section, for warehouse - the warehouse indicated in the document header, and for quantity - the quantity from the document's tabular section.

Click OK and see the text generated by the wizard in the module of the ReceiptOfGoods document (listing 6.1).

1C:Enterprise 8. Practical Developer's Guide. Lesson 6. Accumulation Registers

Fig. 6.9. Selection of a document tabular section and filling  in expressions to calculate the register records

Listing 6.1. Procedure Posting()

Procedure Posting(Cancel, Mode)
	//{{__REGISTER_REGISTERRECORDS_WIZARD
	//This fragment was built by the wizard.
	//Warning! All manually made changes will be lost next time you use the wizard.

	RegisterRecords.BalanceOfMaterials.Write = True;
	
	For Each CurRowMaterials In Materials Do
		//register BalanceOfMaterials ReceiptOfGoods
		Record = RegisterRecords.BalanceOfMaterials.Add();
		Record.RecordType = AccumulationRecordType.ReceiptOfGoods;
		Record.Period = Date;
		Record.Material = CurRowMaterials.Material;
		Record.Warehouse = Warehouse;
		Record.Quantity = CurRowMaterials.Quantity;
	EndDo;
	//}}__REGISTER_REGISTERRECORDS_WIZARD
EndProcedure

The wizard has created an event handler named Posting for the configuration object ReceiptOfGoods Document, placed it in the object's module and opened the module code.

The Posting event is one of the most important events connected to a document. This event occurs when a document is posted. The main purpose of this event handler is to generate register records for the document. Execution of various operations on data in the handler procedure influences state of accounts. So the developer should use the procedure to host their own data conversion algorithms that are executed when a document is posted.

Now lets us clarify the code of the handler procedure.

The 1C:Enterprise script entity DocumentObject has the property RegisterRecords. It returns the RegisterRecordsCollection object that contains a collection of register record sets that can be used by this document to generate register records.

You can address a specific record set of this collection by entering the name of the register this record set belongs to after a dot. For example, RegisterRecords.BalanceOfMaterials. Next after a dot you can use various methods of register record sets, e.g. RegisterRecords.BalanceOfMaterials.Add(). The Add() method adds a new record into the record set.

In the first line of the procedure we select the value True for the Record property of the register record set. So we explicitly specify that after posting is completed the platform will need to record this record set into the database.

The handler hosts the loop For Each ... In ... Do. This loop is intended to search through the rows in the document's tabular section.

In the loop the tabular section of the document is called for using its name (Materials). The CurRowMaterials variable contains an object with the data in the current row of the document tabular section. This variable is created in the beginning of the loop and is modified along the loop.

In the first line of the loop body we use the Add() method to add a new record to the record set that our document creates in the register. In doing so, we create an object named AccumulationRegisterRecord and save it in the RegisterRecord variable.

Using this object, we can call for the fields of this record by entering the field name separated by a dot from the variable itself (e.g., RegisterRecord. Quantity).

Note that Record.Material, Record.Warehouse are the dimensions of the register while Record.Quantity is the register resource and Record. RecordType and Record.Period are default attributes of the register that are created automatically.

In order to assign respective values of the document fields to the fields of the new register record, we address the tabular section fields by entering the field name after a dot following the CurRowMaterials variable (e.g., CurRowMaterials.Material).

Note that Warehouse is an attribute of the document header while Date is a default document attribute that is created automatically. Note that only the values of the document tabular section are changed within the loop (CurRowMaterials.Material and CurRowMaterials.Quantity). Other fields do not change because they relate to the entire document and do not depend on the current row of the document tabular section.

AccumulationRecordType.Receipt is the value of system enumeration that defines the type of the accumulation register record as Receipt.

So we specify the required values to all the fields of the new record. After searching in all the rows of the document (when the loop is completed), this record set (RegisterRecords.BalanceOfMaterials) will contain the number of records that is equal to the number of rows in the tabular section of the posted document.

If we now open the configuration object editor for the BalanceOfMaterials accumulation register and navigate to the Recorders tab, the list of the documents created in the configuration will include a checked ReceiptOfGoods document because in the module of this document we have defined generation of register records in the BalanceOfMaterials register (fig. 6.10).

1C:Enterprise 8. Practical Developer's Guide. Lesson 6. Accumulation Registers

Fig. 6.10. Recorders of the BalanceOfMaterials Register

Finally, we will edit the command interface so that the link to view records of our accumulation register is available in the subsystems Accounting, Rendering Services, and Goods Management.

The thing is that the commands to open registers are also added to the navigation panel of subsystems but by default they are not visible unlike the commands to open catalogs and documents.

Highlight the Subsystems branch in the configuration object tree, open its context menu and select All subsystems.

In the window that opens highlight GoodsManagement in the Subsystems list on the left.

The right-hand Command Interface list will display all the commands of the selected subsystem.

In the Navigation Panel.Normal group enable visibility for the Balance of Materials command and drag it to the group Navigation Panel.See also

1C:Enterprise 8. Practical Developer's Guide. Lesson 6. Accumulation Registers

Fig. 6.11. Subsystem Command Interface Setup

True, the commands to open accumulation registers are used less frequently so it is more convenient to move them to the See also group of the navigation panel of the interface sections.

In a similar manner highlight the subsystems RenderingServices and Accounting and enable visibility for the Balance of Materials group in the Normal group of the navigation panel and drag it to See also.

In the 1C:Enterprise Mode

Now launch 1C:Enterprise in the debugging mode and test the changes we have just made.

In the 1C:Enterprise window that opens you can see that See also group of the navigation panels in the sections Accounting, Rendering Services, and

Goods Management now includes the command to open the list of Balance Of Materials register (fig. 6.12).

1C:Enterprise 8. Practical Developer's Guide. Lesson 6. Accumulation Registers

Fig. 6.12. List of the BalanceOfMaterials accumulation register

In order to track the connection between document posting and accumulation of information in the register, open the list of receipts using Receipts of goods command of the Accounting section.

Open ReceiptOfGoods No. 1 and click Post and Close, i.e. repost the document. Now do the same for the ReceiptOfGoods No. 2.

You can repost documents without opening them. To do so, highlight the required document in the list (or select multiple documents by clicking them while holding Ctrl down), click All Actions in the command bar of the list form and select Post from the menu (fig. 6.13).

1C:Enterprise 8. Practical Developer's Guide. Lesson 6. Accumulation Registers

Now use the Balance of Materials command and open the list of our accumulation register (fig. 6.14).

1C:Enterprise 8. Practical Developer's Guide. Lesson 6. Accumulation Registers

Fig. 6.14. List of the BalanceOfMaterials accumulation register

We see that when we post receipt of goods, respective records emerge in the Balance Of Materials accumulation register. Note that five records have been added: three records after posting the first document (this number corresponds to the number of rows in its tabular section) and two records after posting the second document.

All the register fields are filled with the data from the documents exactly as specified in the handler for ReceiptOfGoods document posting. The + icon to the left from each record demonstrates the type of the register record as ReceiptOfGoods.

As you can see, the title of the register records list form corresponds to the one we have entered in the Extended list presentation property for this register.

The Command of Going to Register Records in a Document Form

In the Designer Mode

In real-life work the number of records in the BalanceOfMaterials register will be high so it will be difficult to understand the relations between records and specific documents.

This is why in addition to the general list of a register, it is convenient to be able to open a register list from a form that will display the register records performed by this specific document.

In order to make it possible, return to the Designer and open the form of the ReceiptOfGoods document.

In the upper left window navigate to the Command Interface tab.

In the Navigation Panel section expand Go To group and locate the command that opens the list of accumulation register named Balance Of Materials. This command has been automatically included in the navigation panel of the document form because this document is a recorder, i.e. it creates register records in our register.

Check the property Visibility for this command (fig. 6.15).

In the 1C:Enterprise Mode

Now let us launch 1C:Enterprise in the debugging mode and open the ReceiptOfGoods No. 2 (fig. 6.16).

1C:Enterprise 8. Practical Developer's Guide. Lesson 6. Accumulation Registers

Fig. 6.15. Document form command interface setup

1C:Enterprise 8. Practical Developer's Guide. Lesson 6. Accumulation Registers

Fig. 6.16. Navigation panel of the ReceiptOfGoods document

The document form now has a navigation panel that we can use to navigate to the list of records in the Balance Of Materials register that is related to this document (fig. 6.17) and then navigate back to the document content.

1C:Enterprise 8. Practical Developer's Guide. Lesson 6. Accumulation Registers

Fig. 6.17. Navigating to an accumulation register from a document form

Note that the navigation panel was not visible in the receipt of goods form before because no commands were displayed in this panel.

Creating Register Records of the Services Rendered Document

Now we will follow the same procedures to create register records for the ServicesRendered document. To do so, you will need to use the already familiar steps.

In the Designer Mode

Open the configuration object editor for the ServicesRendered Document.

Go to the Register Records tab and check BalanceOfMaterials in the list of accumulation registers for the configuration.

Click Register Records Wizard.

In the wizard window that opens change the type of register records in the register to use Expense because the ServicesRendered document is intended to record expenses of materials. The icon to the left of the register name will change to represent the minus sign (-).

In the Tabular Section selection field, we will select the tabular section of our document-ProductList.

The list of document attributes that is already populated by the attributes of the document header, will have the attributes of the tabular section added.

Now click the Fill Expressions button.

In the lower window, the relationships between register fields (dimensions and resources) will be generated along with the expressions to calculate them. But the field Material will not be filled in automatically.

This is due to the fact that the name of the tabular section field (Product) does not match the name of the register dimension (Material). If we leave it as is, product will not be recorded in the accumulation register in the row of the type Register Record - Expenditure.

In order to avoid it, highlight the Material field of the register and in the Document Attributes double-click the row CurRowProductList.Product.

If we do so, the products for the accumulation register records will be selected from the tabular section of the document (fig. 6.18).

1C:Enterprise 8. Practical Developer's Guide. Lesson 6. Accumulation Registers

Fig. 6.18. Selection of the document tabular section and filling  in expressions to calculate the register records

Click OK.

The wizard has created an event handler named Posting for the ServicesRendered Document configuration object and placed it in the object's module (listing 6.2).

Listing 6.2. Procedure Posting()

Procedure Posting(Cancel, Mode)
	//{{__REGISTER_REGISTERRECORDS_WIZARD
	//This fragment was built by the wizard.
	//Warning! All manually made changes will be lost next time you use the wizard.
	
	RegisterRecords.BalanceOfMaterials.Write = True;
	
	For Each CurRowProductList In ProductList Do
		//register BalanceOfMaterials Expense
		Record = RegisterRecords.BalanceOfMaterials.Add();
		Record.RecordType = AccumulationRecordType.Expense;
		Record.Period = Date;
		Record.Material = CurRowProductList.Product;
		Record.Warehouse = Warehouse;
		Record.Quantity = CurRowProductList.Quantity;
	EndDo;
	//}}__REGISTER_REGISTERRECORDS_WIZARD
	
EndProcedure

Note that the field Record.RecordType = AccumulationRecordType.Expense defines the type of the accumulation register record implemented by this document as Expense while in everything else the procedure of the ServicesRendered document handler is similar to the handler of the ReceiptOfGoods document (see listing 6.1) that we have discussed in detail above.

Finally, we will edit the command interface of the document form so that the navigation panel made it possible to go to the list of Balance Of Materials register records related to the document.

To do so, open the form of the ServicesRendered document.

In the upper left window navigate to the Command Interface tab.

In the Navigation Panel section expand Go To group and enable visibility for the command that opens the list of accumulation register named Balance Of Materials.

In the 1C:Enterprise Mode

Run 1C:Enterprise in the debugging mode and in the Rendering Services section open the document Rendering Services No. 1 and click Post and Close, i.e. repost this document.

Now use the Balance Of Materials command and open the list of our accumulation register (fig. 6.19).

1C:Enterprise 8. Practical Developer's Guide. Lesson 6. Accumulation Registers

Fig. 6.19. List of the BalanceOfMaterials accumulation register

We see that the Balance Of Materials accumulation register now has a new record (one record because the tabular section of the posted document has one row).

All the register fields are filled with the data from the document exactly as specified in the handler for Services Rendered document posting.

The icon with the minus sign to the left of the record demonstrates that the type of the register record is Expense (see fig. 6.19).

Now we see the entire list of register records. If you open this list from the document form, you can filter the register records by their recorder document.

To do so, open the document named Rendering Services No. 1 again.

The document form now has a navigation panel that we can use to navigate to the list of records in the Balance Of Materials register that is related to this document and back to the document content (fig. 6.20).

1C:Enterprise 8. Practical Developer's Guide. Lesson 6. Accumulation Registers

Fig. 6.20. Navigating to the accumulation register from the document form

The register records for this document that are generated in this manner will be a little off.

The thing is that, in contrast to the ReceiptOfGoods document, the Services Rendered document can contain not only the materials used but the services as well. Therefore, records of expended services could end up in the Balance Of Materials register, which is not what we want.

For now, we will do nothing with the register records generated by the wizard, but as soon as we get to enumerations, we will make the necessary modifications to the posting handler.

Theory. Ways of Working with Collections

In the process of generating register records for documents, we have encountered one of the 1C:Enterprise script entities that is referred to as a collection. We encountered it when we searched in the tabular sections of the spreadsheet documents ReceiptOfGoods and ServicesRendered within the loop.

Many of the 1C:Enterprise script entities are collections. A collection is a set of objects or entities. There are some general principles used to work with any collection.

One option is to access each object in a collection by searching through the collection's items in a loop. To do so, we use the construction of the script For Each ... In ... Do ... (listing 6.3).

Listing 6.3. Searching within Collection Items in a Loop

For Each TabularSectionRow In TabularSection Do 
	Message(TabularSectionRow.Service);
EndDo;

In this example TabularSection is a collection of rows in tabular section of the configuration object. In each iteration of the loop, the variable TabularSectionRow will contain the next row of the collection.

The second option is to access collection items directly without using a search loop. The two methods of referencing can be combined.

1. Named collections exist in the 1C:Enterprise script. These are the collections where every item has a specific unique name. In this case a collection item can be referenced using its name (listing 6.4).

Listing 6.4. Addressing a Collection Item

Catalogs.Employees; 
Catalogs["Employees"];

In this example Catalogs is a collection of managers of all the catalogs available in the configuration. Since every catalog in a configuration has a unique name, a specific item of this collection (a manager of a specific catalog) can be addressed by entering the name of the catalog:

Catalogs["Employees"].

2. If it does not make sense to "get personal" with the items in the collection (when the collection is not a named one), you can generally refer to a collection item by its index (the index for the first item in a collection is zero), (listing 6.5).

Listing 6.5. Addressing a Collection Item by its Index

TabularSections[0];

In this example TabularSections is a collection of rows in tabular section of a configuration object. And we address the first item in the collection by entering its index, i.e. 0.

Note that there are collections where both reference methods are combined. For example we can reference a collection of columns in a values table, by either column name or by index.

Quiz

  • What are the uses of the Accumulation Register configuration object?
  • Why should one use registers while the information required is available in other objects?
  • What are the uses of register dimensions, resources, and attributes?
  • What is a register record? What is a recorder?
  • How does one create a new accumulation register and declare its structure?
  • How does one create register records of a document using the register records wizard?
  • How does one search within a document's tabular section and refer to its data using the 1C:Enterprise script?
  • How does one display the commands to open the register list in the configuration interface and in the form interface?

Leave a Reply

Your email address will not be published.

 

1C:Enterprise Developer's Community