1С:ENTERPRISE 8.

3
Developer Guide

Part 1

Developer Guide
Part 1

Moscow
1C Company
2013
 ENTIRE COPYRIGHT TO SOFTWARE
AND DOCUMENTATION BELONGS TO 1C Company
By purchasing 1С:Enterprise software system
you hereby agree to protect rights of 1C Company
and refrain from making copies of the software
and documentation without prior written permission from 1C Company.

© 1C, LLC, 1996–2013

1C Company, Moscow, 123056, P.O. 64
Sales Department: 21, Seleznevskaya st.,
Phone: +7 (495) 737-92-57,
Fax: +7 (495) 681-44-07,
E-mail: [email protected]
URL: www.1c-dn.com
Software development group: A. Alekseev, A. Bezborodov, D. Beskorovainov, P. Vasilets,
A. Vinogradov, A. Volkov, I. Golshtein, E. Gornostayev, G. Damie, A. Darovskikh, O. Derut,
N. Evgrafov, B. Evtifeev, D. Zaretsky, D. Ivashov, S. Kopienko, N. Korsakov, S. Kravtchenko,
V. Kudryavtsev, P. Kukushkin, A. Lakutin, M. Leybovitch, G. Leontyev, A. Lekhan,
A. Makeev, A. Medvedev, E. Mitroshkin, S. Murzin, S. Nuraliev, L. Onuchin, M. Otstavnov,
D. Pavlenko, A. Plyakin, A. Rukin, D. Rusanov, E. Silin, D. Sluzhbin, A. Smirnov, V. Sokolov,
P. Solodky, V. Sosnovsky, D. Sysoenkov, A. Toporkov, V. Tunegov, A. Trubkin, V. Philippov,
A. Tsylyabin, V. Cheremisinov, P. Chikov, A. Chicherin, A. Shevtchenko, A. Scherbinin.
Documentation: V. Baidakov, V. Dranishchev, E. Korolkova, A. Krayushkin, I. Kuznetsov, M. Lavrov,
A. Monichev, A. Plyakin, M. Radchenko.
Technical support group: O. Bagrova, M. Belokon, E. Garifullina, V. Davydova, O. Dmitrenko,
A. Evdokimova, L. Ermakova, Yu. Zhestkov, S. Zholudev, M. Zholudeva, O. Zavalskaya,
N. Zayavlina, G. Korobka, Yu. Lavrova, S. Lepeshkina, S. Mazurin, S. Markov, A. Markova,
Yu. Misan, V. Nikolaeva, A. Pavlikov, I. Panin, O. Pekhtereva, S. Postnova, A. Prokurovsky,
G. Stepanenko, N. Stepanov, V. Tantasheva, T. Tokareva, G. Yastrebova.
QA group: A. Galochkin, B. Ziatdinov, A. Lapin, E. Medvedev, S. Potapov, N. Shargunova.

Book Title: 1C:Enterprise 8.3. Developer Guide. Part 1

Publication Number: 83.102.02
Publication Date:
 TECHNICAL SUPPORT LINE
Registered users can receive technical support from 1C Company or authorized
1C partners.
To complete your registration, fill out the registration form and mail it to the
1C partner through which you have purchased the product. The address is printed
on the registration form.
Refer to the software registration card for the telephone number and e-mail
address of the technical support service.
When you dial the hot line, ensure that you are not far from your computer and
you have this guide and your registration card with you. Be prepared to provide
the support representative with the brand and technical specifications of your
computer and printer.
When you dial the hot line, you will be connected with a technical specialist.
Be ready to provide the name of your company, your software version number
(it can be found on the software distribution CD and on your registration card) and
other registration information. The information that you provide will be verified
against the registration form that you sent out.
The technical support specialist might attempt to reproduce your situation on their
computer. They might provide the solution immediately or consult software devel-
opers. The log of all support calls is maintained, so when calling about a previous
issue you can refer to the date and time of your previous call.

WE ARE ALWAYS HERE TO HELP YOU!

1-4 1C:Enterprise 8.3. Developer Guide
 CONTENTS

PART 1
Introduction.................................................................................................................................1-21
Structure of the Guide............................................................................................................1-21
What You Need To Know......................................................................................................1-23
The Books Included in  the Documentation...........................................................................1-23
Training Materials and Additional Opportunities...........................................................1-24
Text Files Included in  the 1C:Enterprise 8.3 Distribution Kit.......................................1-24
About 1C:Enterprise 8 Page...................................................................................................1-24
1C:Developer Network..........................................................................................................1-24
Agreed Notation.....................................................................................................................1-25
Chapter 1. Concept of the System.............................................................................................1-27
1.1. Configurability................................................................................................................1-27
1.2. Functioning of the System..............................................................................................1-27
1.3. Basic Concepts of the System.........................................................................................1-28
1.3.1. Configuration Concept..........................................................................................1-29
1.3.2. Configuration Object............................................................................................1-30
1.3.3. Command Interface...............................................................................................1-39
1.3.4. Form......................................................................................................................1-40
1.3.5. Module..................................................................................................................1-40
1.3.6. Template...............................................................................................................1-41
1.4. Operation Modes.............................................................................................................1-42
1.4.1. File Mode .............................................................................................................1-42
1.4.2. Client/Server Mode...............................................................................................1-42
1.5. Development Tools.........................................................................................................1-43
Chapter 2. Work with Configuration.......................................................................................1-47
2.1. Opening Configuration....................................................................................................1-47
2.2. Saving Configuration......................................................................................................1-48
2.3. Closing Configuration.....................................................................................................1-48
2.4. Saving Configuration to File...........................................................................................1-49
2.5. Loading Configuration from File....................................................................................1-49
2.6. Configuration Object Tree..............................................................................................1-49
1-6 1C:Enterprise 8.3. Developer Guide

2.7. Metadata Tree Sort Settings............................................................................................1-50

2.8. Creation and Deletion of Configuration Objects.............................................................1-50
2.8.1. Create Configuration Objects...............................................................................1-50
2.8.2. Deletion of Configuration Objects........................................................................1-52
2.8.3. References to Configuration Objects....................................................................1-52
2.9. Properties Palette.............................................................................................................1-53
2.10. More Window...............................................................................................................1-56
2.11. Object Editing Window.................................................................................................1-59
2.12. Create Help Content Section.........................................................................................1-63
2.13. Work with Database Configuration...............................................................................1-63
2.13.1. Database Configuration Object Tree..................................................................1-63
2.13.2. Update of Database Configuration.....................................................................1-64
2.13.3. Background Database Configuration Update.....................................................1-67
2.13.4. Saving Database Configuration to File...............................................................1-71
2.13.5. Comparison of Configuration and Database Configuration...............................1-72
2.13.6. Cancellation of Configuration Changes..............................................................1-72
2.14. 1C:Enterprise Launch....................................................................................................1-72
2.15. Download/Upload of Configuration Files.....................................................................1-72
2.16. Configuration Dump and Restoration...........................................................................1-74
2.17. Working with a  mobile application..............................................................................1-76
2.18. Configuration Report.....................................................................................................1-76
2.19. Global Search and Replacement...................................................................................1-77
2.20. Customization of Designer Work Space.......................................................................1-80
2.20.1. Panel Customization...........................................................................................1-81
2.20.2. Configuration Window.......................................................................................1-81
2.20.3. Use of Window Display Modes..........................................................................1-81
Chapter 3. Application Interface...............................................................................................1-83
3.1. Open Forms in  Separate Windows.................................................................................1-84
3.1.1. Main Application Window...................................................................................1-84
3.1.2. Auxiliary Window................................................................................................1-88
3.2. Open Forms in  Tabs.......................................................................................................1-90
3.2.1. The Main Application Window............................................................................1-90
3.2.2. The Auxiliary Window.........................................................................................1-98
3.3. Taxi Interface..................................................................................................................1-98
3.3.1. Main application window.....................................................................................1-98
3.3.2. The auxiliary window.........................................................................................1-110
Chapter 4. 1C:Enterprise Script.............................................................................................1-113
4.1. Brief Description and Purpose of 1C:Enterprise Script................................................1-113
4.2. Source Text Format in  Program Modules....................................................................1-114
4.2.1. What is  a Program Module?..............................................................................1-114
4.2.2. Program Module Execution Context..................................................................1-114
4.2.3. Types of Program Modules................................................................................1-115
4.2.4. Program Module Format.....................................................................................1-119
4.2.5. Special Characters Used in  Source Text............................................................1-121
4.3. Primitive Data Types.....................................................................................................1-122
4.4. Assignment Operator.....................................................................................................1-126
4.5. Script Expressions.........................................................................................................1-126
4.5.1. Arithmetic Operations.........................................................................................1-126
Contents 1-7

4.5.2. Concatenation Operation....................................................................................1-127

4.5.3. Logical Operations..............................................................................................1-127
4.6. Operators and Syntactic Constructs..............................................................................1-128
4.7. Major Techniques and Practices...................................................................................1-146
4.7.1. Calls to Object Properties...................................................................................1-146
4.7.2. Enhancement of Object and Form Context.........................................................1-147
4.7.3. Passing Procedure and Function Parameters......................................................1-148
4.7.4. Work with Collections of Values........................................................................1-154
4.7.5. Use of Numbers and Indices...............................................................................1-154
4.7.6. Work with System Enumerations.......................................................................1-154
4.7.7. Work with Predefined Values.............................................................................1-154
4.8. System Startup Versions...............................................................................................1-156
4.8.1. Execution of Procedures and Functions..............................................................1-157
4.8.2. Use of Objects, Their Properties and Methods...................................................1-163
Chapter 5. Configuration Objects...........................................................................................1-165
5.1. Configuration Properties...............................................................................................1-165
5.1.1. General Property Category.................................................................................1-165
5.1.2. Presentation Property Category..........................................................................1-167
5.1.3. Development Property Category........................................................................1-169
5.1.4. Help Content Property Category.........................................................................1-169
5.1.5. Compatibility Property Category........................................................................1-169
5.2. Managed Application Module.......................................................................................1-171
5.3. External Connection Module........................................................................................1-172
5.4. Session Module.............................................................................................................1-172
5.5. Common Configuration Branch....................................................................................1-172
5.5.1. Subsystems.........................................................................................................1-173
5.5.2. Common Modules..............................................................................................1-174
5.5.3. Session Parameters.............................................................................................1-179
5.5.4. Roles and Access Rights.....................................................................................1-180
5.5.5. Common Attributes............................................................................................1-204
5.5.6. Exchange Plans...................................................................................................1-207
5.5.7. Filter....................................................................................................................1-208
5.5.8. Event Subscription..............................................................................................1-209
5.5.9. Scheduled Jobs....................................................................................................1-210
5.5.10. Functional Options and Their Parameters........................................................1-211
5.5.11. Defined types....................................................................................................1-223
5.5.12. Settings Storages...............................................................................................1-223
5.5.13. Common Forms................................................................................................1-229
5.5.14. Common Commands........................................................................................1-230
5.5.15. Command Groups.............................................................................................1-230
5.5.16. Common Templates..........................................................................................1-230
5.5.17. Common Pictures..............................................................................................1-230
5.5.18. XDTO Packages...............................................................................................1-233
5.5.19. Web-services.....................................................................................................1-241
5.5.20. WS-references...................................................................................................1-244
5.5.21. Style Elements..................................................................................................1-246
5.5.22. Languages.........................................................................................................1-247
5.6. Common Properties of Configuration Objects..............................................................1-250
5.6.1. General Properties...............................................................................................1-250
5.6.2. Metadata Object Presentation.............................................................................1-250
1-8 1C:Enterprise 8.3. Developer Guide

5.6.3. Custom Presentation of Data..............................................................................1-251

5.6.4. Standard Attributes.............................................................................................1-253
5.6.5. Predefined data...................................................................................................1-254
5.6.6. Input by String....................................................................................................1-258
5.6.7. Forms..................................................................................................................1-263
5.6.8. Commands..........................................................................................................1-266
5.6.9. Attribute Fill-in Mechanism for New Objects....................................................1-266
5.6.10. Attribute Fill Check..........................................................................................1-268
5.6.11. Indexing Object Attributes................................................................................1-273
5.6.12. Rights................................................................................................................1-273
5.6.13. Quick Choice....................................................................................................1-274
5.6.14. Choice Parameter Links....................................................................................1-274
5.6.15. Choice Parameters............................................................................................1-277
5.6.16. Other.................................................................................................................1-278
5.7. Constants.......................................................................................................................1-279
5.7.1. Properties of a  Constant.....................................................................................1-279
5.8. Catalogs.........................................................................................................................1-280
5.8.1. Catalog Properties...............................................................................................1-281
5.8.2. Properties of Catalog Attributes.........................................................................1-285
5.8.3. Predefined Catalog Items....................................................................................1-285
5.9. Documents.....................................................................................................................1-285
5.9.1. Document Properties...........................................................................................1-286
5.9.2. Document Posting Mechanism...........................................................................1-290
5.9.3. Numerators.........................................................................................................1-293
5.9.4. Document Sequences..........................................................................................1-294
5.9.5. Entering Documents Based on Existing Objects................................................1-298
5.10. Document Journals......................................................................................................1-299
5.10.1. Journal Creation................................................................................................1-299
5.10.2. Journal Editing..................................................................................................1-299
5.10.3. Document Journal Columns.............................................................................1-300
5.11. Enumerations...............................................................................................................1-301
5.12. Reports and Data Processors.......................................................................................1-303
5.12.1. External Reports and Data Processors..............................................................1-304
5.13. Charts of Characteristic Types....................................................................................1-309
5.14. Registers......................................................................................................................1-316
5.14.1. Information Registers.......................................................................................1-317
5.14.2. Accumulation Registers....................................................................................1-323
Chapter 6. Command Interface...............................................................................................1-337
6.1. General Structure of Command Interface.....................................................................1-337
6.1.1. Sections and Subsections of Main Application Window....................................1-337
6.1.2. Types of Commands...........................................................................................1-338
6.1.3. Command Groups...............................................................................................1-342
6.2. Creation of Global Command Interface........................................................................1-343
6.2.1. Subsystems.........................................................................................................1-343
6.2.2. Commands..........................................................................................................1-344
6.2.3. Command Parameterization................................................................................1-345
6.2.4. Creation of Default Command Interface............................................................1-346
6.2.5. Command Interface Property..............................................................................1-347
6.2.6. Editing Sets of Commands.................................................................................1-347
6.2.7. Role-Based Setup of Default Command Visibility.............................................1-348
Contents 1-9

6.3. Service Navigation Features..........................................................................................1-349

6.3.1. Links...................................................................................................................1-349
6.3.2. User Notifications...............................................................................................1-350
6.3.3. Display Status of Lengthy Processes..................................................................1-351
6.3.4. Messages.............................................................................................................1-353
6.3.5. How Keyboard Shortcuts Work..........................................................................1-357
6.4. Command Interface Development Procedure...............................................................1-358
Chapter 7. Forms......................................................................................................................1-361
7.1. Form Attributes.............................................................................................................1-362
7.1.1. Form Data Types................................................................................................1-363
7.1.2. Conversions Between Application Object Data and Form Data........................1-368
7.1.3. Dynamic List......................................................................................................1-369
7.1.4. Attribute Properties.............................................................................................1-377
7.1.5. Form Conditional Appearance............................................................................1-378
7.1.6. Formatted Documents.........................................................................................1-381
7.2. Form Parameters...........................................................................................................1-384
7.2.1. Standard Form Parameters..................................................................................1-385
7.2.2. Form Parameters Handling: Example.................................................................1-386
7.3. Form Commands...........................................................................................................1-388
7.4. Form Module.................................................................................................................1-390
7.5. Form Elements..............................................................................................................1-391
7.5.1. Common Properties of Form Elements..............................................................1-392
7.5.2. Form....................................................................................................................1-396
7.5.3. Field....................................................................................................................1-400
7.5.4. Decoration...........................................................................................................1-402
7.5.5. Table...................................................................................................................1-402
7.5.6. Button.................................................................................................................1-405
7.5.7. Group..................................................................................................................1-405
7.5.8. Special Command Bars.......................................................................................1-407
7.5.9. Form Element Behavior......................................................................................1-408
7.5.10. Rules of Form Elements Placement..................................................................1-408
7.5.11. Form Element Boundaries Alignment..............................................................1-412
7.5.12. Drag-and-Drop Mechanism..............................................................................1-419
7.6. Form Command Interface.............................................................................................1-421
7.7. Different approaches to modality..................................................................................1-421
7.7.1. Overview.............................................................................................................1-421
7.7.2. Using blocking windows....................................................................................1-424
7.7.3. Method mapping.................................................................................................1-425
7.8. Work with Form from 1C:Enteprise Script...................................................................1-426
7.8.1. How to Open a  Form.........................................................................................1-426
7.8.2. Redefining an Opened Form...............................................................................1-427
7.8.3. Modification of Form Elements Properties........................................................1-428
7.8.4. Form Modification..............................................................................................1-429
7.8.5. Working with Dynamic Lists..............................................................................1-433
Chapter 8. Work with Queries................................................................................................1-441
8.1. Query Data Sources (Tables)........................................................................................1-441
8.2. Query Language............................................................................................................1-442
8.2.1. Syntax Diagram for Query Language Constructs...............................................1-442
8.2.2. Comments in  Query Language..........................................................................1-443
1-10 1C:Enterprise 8.3. Developer Guide

8.2.3. Use of Predefined Configuration Data................................................................1-443

8.2.4. Query language keywords..................................................................................1-445
8.2.5. Main Sections of Query Text..............................................................................1-446
8.2.6. Query Description...............................................................................................1-446
8.2.7. Selection Fields Description...............................................................................1-450
8.2.8. Query Sources Description.................................................................................1-453
8.2.9. Query Result Filtration.......................................................................................1-460
8.2.10. Query Result Groups........................................................................................1-461
8.2.11. Conditions for Aggregate Function Values......................................................1-462
8.2.12. Query Union.....................................................................................................1-463
8.2.13. Query Result Ordering......................................................................................1-464
8.2.14. Autoorder Results.............................................................................................1-467
8.2.15. Calculation of Query Totals..............................................................................1-468
8.2.16. Expressions in  the Query Language................................................................1-473
8.2.17. Conditions in  Query Language........................................................................1-488
8.3. Execution and Use of Queries in  the 1C:Enterprise Script..........................................1-496
8.3.1. Major Techniques and Practices.........................................................................1-496
8.3.2. Work with Temporary Tables.............................................................................1-504
8.3.3. Working with Batch Queries..............................................................................1-508
Chapter 9. Work with Data......................................................................................................1-509
9.1. Object Locks.................................................................................................................1-509
9.1.1. Pessimistic Lock.................................................................................................1-509
9.1.2. Pessimistic Lock and Transactions.....................................................................1-511
9.1.3. Optimistic Lock..................................................................................................1-511
9.2. Transactions..................................................................................................................1-511
9.2.1. Explicit Calls to Transactions.............................................................................1-512
9.2.2. Nested Transaction Call......................................................................................1-514
9.2.3. Impact of Transactions on Program Objects.......................................................1-515
9.3. Managed Locks.............................................................................................................1-515
9.3.1. General Information on Locks............................................................................1-515
9.3.2. Managed Locks...................................................................................................1-516
9.3.3. Setting Lock Mode in  Configuration.................................................................1-518
9.3.4. Work with Managed Locks Through 1C:Enterprise Script................................1-518
9.3.5. Automatic and Managed Mode: Features...........................................................1-522
9.3.6. Working with multiple managed locks...............................................................1-523
9.3.7. Configuration Modification When Switching to Managed Lock Mode.............1-524
9.4. Exclusive mode.............................................................................................................1-528
Chapter 10. Data Composition System...................................................................................1-531
10.1. General Information on Data Composition.................................................................1-531
10.2. Common Objects of Data Composition System.........................................................1-535
10.2.1. Use Property.....................................................................................................1-535
10.2.2. Data Composition System Field.......................................................................1-535
10.2.3. Data Composition System Parameters..............................................................1-536
10.3. Data Composition Schema..........................................................................................1-536
10.3.1. Data Composition Schema Components..........................................................1-537
10.3.2. Working with Multiple Data Sets.....................................................................1-542
10.3.3. Query Language Extension for Data Composition System..............................1-544
10.3.4. Data composition system expression language................................................1-547
10.3.5. Data Composition Schema Wizard...................................................................1-589
Contents 1-11

10.3.6. Data Composition Variant Settings..................................................................1-604

10.3.7. User Settings of Data Composition System......................................................1-610
10.4. Data Composition Template........................................................................................1-617
10.4.1. Data Composition Template Sections...............................................................1-617
10.4.2. Appearance Templates......................................................................................1-622
10.4.3. Generator of Template Areas............................................................................1-624
10.5. Data Composition Processor.......................................................................................1-632
10.6. Functional Options and Rights to View Fields in  Reports.........................................1-633
10.7. Data Composition Result............................................................................................1-634
10.7.1. Composition Result Output to Spreadsheet Document....................................1-636
10.7.2. Composition Result Output to Value Table and Value Tree............................1-637
10.8. Calculation of Totals by Balance Fields in  Data Composition System.....................1-638
10.8.1. Calculation of Totals by Balance Fields...........................................................1-638
10.8.2. Calculation of Totals by Accounting Balance Fields.......................................1-639
10.8.3. Template Composition......................................................................................1-640
10.9. Working with Hierarchy in  Data Composition System.............................................1-640
10.9.1. Hierarchical Groups..........................................................................................1-640
10.9.2. Hierarchical Detail Records..............................................................................1-641
10.9.3. Output of a  Single Item in  Multiple Parent Records......................................1-642
10.9.4. IN HIERARCHY Condition.............................................................................1-644
10.10. Use of Data Composition System in  Application Development..............................1-644
10.10.1. Input Parameters.............................................................................................1-647
10.10.2. Use of Metadata Object Properties in  Reports...............................................1-647
10.10.3. Background Report Execution........................................................................1-647
10.11. Specifics of Using of Data Composition System......................................................1-648
Chapter 11. Accounting............................................................................................................1-651
11.1. Overview.....................................................................................................................1-651
11.2. Charts of Accounts......................................................................................................1-652
11.3. Analytical Accounting.................................................................................................1-653
11.4. Types of Accounting...................................................................................................1-655
11.5. Accounting Register Records and Record Sets...........................................................1-655
11.6. Consolidated Accounting............................................................................................1-656
11.7. Creation of Chart of Accounts....................................................................................1-656
11.7.1. Chart Of Accounts Properties...........................................................................1-657
11.7.2. Setting up Various Accounting Types..............................................................1-658
11.7.3. Generation of Account List (Predefined Accounts).........................................1-658
11.8. Accounting Registers..................................................................................................1-660
11.8.1. Accounting Register Properties........................................................................1-660
11.8.2. Accounting Register Records...........................................................................1-660
Chapter 12. Periodical Calculations........................................................................................1-663
12.1. Major Concepts...........................................................................................................1-663
12.2. Charts of Calculation Types........................................................................................1-665
12.2.1. Calculation Property Category..........................................................................1-665
12.2.2. Predefined Calculation Types...........................................................................1-666
12.3. Calculation Registers...................................................................................................1-668
12.3.1. General Information on Calculation Registers.................................................1-668
12.3.2. Editing Calculation Register.............................................................................1-669
1-12 1C:Enterprise 8.3. Developer Guide

PART 2
Chapter 13. Business Processes and Tasks.............................................................................2-691
13.1. Major Concepts...........................................................................................................2-691
13.2. General Information....................................................................................................2-692
13.3. Routing........................................................................................................................2-693
13.4. Addressing System......................................................................................................2-693
13.5. Starting Business Processes........................................................................................2-696
13.6. Task Performance........................................................................................................2-697
13.7. Splitting and Joining...................................................................................................2-697
13.8. Manual Control...........................................................................................................2-698
13.8.1. Business Process Completion Attribute............................................................2-698
13.8.2. Task Performance Attribute..............................................................................2-698
13.8.3. Task Removal...................................................................................................2-699
13.8.4. Task Addition...................................................................................................2-699
13.9. Conditional Jump........................................................................................................2-699
13.10. Switch........................................................................................................................2-700
13.11. Task Generation........................................................................................................2-700
13.12. Performance Check...................................................................................................2-702
13.13. Nested Process Execution.........................................................................................2-703
13.14. Business Process Completion...................................................................................2-704
13.15. Standard Business Process and Task Attributes........................................................2-704
13.16. Business Processes with Several Starting Points......................................................2-705
13.17. Feedback....................................................................................................................2-705
13.18. Flowchart...................................................................................................................2-707
13.19. Business Process Editing...........................................................................................2-707
13.20. Task Editing..............................................................................................................2-708
Chapter 14. Data Analysis and Forecasting...........................................................................2-711
14.1. Overview.....................................................................................................................2-712
14.1.1. Main Mechanism Objects.................................................................................2-713
14.1.2. Types of Data Analysis.....................................................................................2-714
14.1.3. Forecasting Models...........................................................................................2-716
14.2. The Summary Statistics Analysis Type......................................................................2-716
14.3. The Association Rules Analysis Type........................................................................2-720
14.3.1. Rules Prune Types............................................................................................2-724
14.4. The Sequential Patterns Analysis Type.......................................................................2-725
14.5. The Decision Tree Analysis Type...............................................................................2-729
14.6. The Сlusterization Analysis Type...............................................................................2-734
14.6.1. Metrics used......................................................................................................2-739
14.6.2. Clusterization methods.....................................................................................2-741
Chapter 15. Data Exchange Mechanisms...............................................................................2-745
15.1. Goals and Objectives...................................................................................................2-745
15.1.1. Universal Data Exchange Mechanisms............................................................2-745
15.1.2. Distributed Infobases........................................................................................2-746
15.2. Universal Data Exchange Mechanisms.......................................................................2-746
15.2.1. XML Documents Read and Write Tools..........................................................2-746
15.2.2. XML Serialization............................................................................................2-746
15.2.3. Exchange Plans.................................................................................................2-759
Contents 1-13

15.3. Distributed Infobases...................................................................................................2-772

15.3.1. General Principles.............................................................................................2-772
15.3.2. Exchange Plans.................................................................................................2-773
15.3.3. Working with Distributed Infobase..................................................................2-778
15.3.4. Data Exchange Scenarios in  Distributed Infobase...........................................2-784
Chapter 16. XDTO Mechanism...............................................................................................2-789
16.1. XDTO Factory.............................................................................................................2-790
16.1.1. XDTO Factory Retrieval from XSD Schema File............................................2-792
16.2. XDTO Data Types......................................................................................................2-793
16.2.1. XDTO Value Type............................................................................................2-793
16.2.2. XDTO Object Type..........................................................................................2-795
16.2.3. XDTO Property................................................................................................2-796
16.3. XDTO Data Instances.................................................................................................2-798
16.3.1. XDTO Value.....................................................................................................2-798
16.3.2. XDTO Object....................................................................................................2-799
16.3.3. XDTO Sequence...............................................................................................2-801
16.3.4. XDTO List........................................................................................................2-802
16.3.5. XРath................................................................................................................2-803
16.4. XDTO-Based XML Serialization................................................................................2-805
16.5. XML Schema Layout Recommendations...................................................................2-806
16.6. XDTO Factory Check Rules.......................................................................................2-808
16.6.1. Check Rules for XDTO Factory Proper...........................................................2-808
16.6.2. XDTO Package Check Rules............................................................................2-808
16.6.3. XDTO Value Type Check Rules......................................................................2-809
16.6.4. XDTO Object Type Check Rules.....................................................................2-812
16.6.5. Facet Limitation Rules......................................................................................2-815
Chapter 17. Web Service Mechanism.....................................................................................2-819
17.1. Provision of Functionality through Web Services......................................................2-820
17.2. Example of Web Service Implementation..................................................................2-821
17.3. Using Third-Party Vendor Web Services....................................................................2-823
17.3.1. Example of Using Static Web Service References...........................................2-824
17.3.2. Example of Using Dynamic WS References....................................................2-825
17.4. Editing Web Service Properties..................................................................................2-825
17.4.1. Operation Properties.........................................................................................2-825
17.4.2. Parameter Properties.........................................................................................2-826
Chapter 18. Job Mechanism....................................................................................................2-827
18.1. Background Jobs.........................................................................................................2-828
18.2. Scheduled Jobs............................................................................................................2-829
18.3. Running Background Jobs in  File Mode and Client/Server Mode............................2-831
18.3.1. File Mode .........................................................................................................2-831
18.3.2. Client/Server Mode...........................................................................................2-832
18.4. Creation of Scheduled Job Metadata...........................................................................2-832
Chapter 19. Full-Text Data Search Mechanism.....................................................................2-835
19.1. General Information on Full-Text Indexing................................................................2-835
19.2. Use of Full-Text Search Mechanisms.........................................................................2-837
19.3. Use of Additional Dictionaries....................................................................................2-839
1-14 1C:Enterprise 8.3. Developer Guide

Chapter 20. Temporary Storage Mechanism, Working with Files and Pictures................2-841
20.1. Temporary Storage......................................................................................................2-841
20.2. Working with Files and Temporary Storage...............................................................2-842
20.2.1. Saving Data from File in  Temporary Storage..................................................2-842
20.2.2. Data Placement in  Temporary Storage............................................................2-843
20.2.3. Data Retrieval from Temporary Storage..........................................................2-843
20.2.4. Data Deletion from Temporary Storage...........................................................2-844
20.2.5. Address Check for Temporary Storage Membership.......................................2-844
20.2.6. Attribute Address Retrieval..............................................................................2-844
20.2.7. File Retrieval from Infobase.............................................................................2-844
20.2.8. Example of File Method Use............................................................................2-846
20.2.9. Enabling Bulk File Operations.........................................................................2-847
20.2.10. Working with Temporary Storage in  Background Job..................................2-849
20.2.11. Address Support in  Picture Box....................................................................2-849
20.2.12. Access to standard directories.........................................................................2-851
20.3. Specific Features of Using in  Web Client..................................................................2-851
Chapter 21. The Event Log......................................................................................................2-853
21.1. Details Management....................................................................................................2-853
21.2. Writing Events.............................................................................................................2-854
21.3. Event Logging Management.......................................................................................2-854
21.3.1. The Access Event Parameters Configuration...................................................2-854
21.3.2. Access Denied Event Parameters Configuration..............................................2-857
21.4. Getting Event Log Records.........................................................................................2-858
21.5. Additional Methods.....................................................................................................2-862
Chapter 22. The Cryptographic Mechanism..........................................................................2-863
22.1. General Mechanism Description.................................................................................2-863
22.2. Main Concepts.............................................................................................................2-864
22.3. General Principles of Using Cryptographic Mechanisms...........................................2-864
22.4. Working with Cryptographic Modules.......................................................................2-865
22.5. Usage Examples..........................................................................................................2-866
Chapter 23. External Data Sources.........................................................................................2-871
23.1. Working with relational external data sources............................................................2-871
23.1.1. Overview...........................................................................................................2-871
23.1.2. General Usage Principles..................................................................................2-873
23.1.3. Editing External Data Source Structure............................................................2-873
23.1.4. Example of External Data Source Table Creation ...........................................2-877
23.1.5. ODBC Connection String.................................................................................2-879
23.2. Working with an external OLAP data source.............................................................2-880
23.2.1. Overview...........................................................................................................2-880
23.2.2. The general principles of usage........................................................................2-882
23.2.3. Editing external data source structure...............................................................2-883
23.2.4. Query Language Limitations When Using
an Analytical External Data Source.................................................................2-886
23.2.5. An OLAP Server Connection String................................................................2-887
23.3. External Data Source Management.............................................................................2-888
23.4. Connecting to an External Data Source in  1С:Enterprise Mode................................2-890
23.5. Using External Data Sources.......................................................................................2-890
23.5.1. The Execution Location of External Data Source Queries...............................2-890
Contents 1-15

23.5.2. Using External Data Sources............................................................................2-891

23.5.3. Rules for Converting Values.............................................................................2-893
23.5.4. An external data source included in  a separator..............................................2-894
Chapter 24. The Data Separation Mechanism.......................................................................2-895
24.1. Overview.....................................................................................................................2-895
24.2. Common Attribute Properties.....................................................................................2-897
24.2.1. Using Separated Data........................................................................................2-897
24.2.2. The Separator Value and Usage Flag...............................................................2-898
24.2.3. Users Separation...............................................................................................2-899
24.2.4. Authentication Separation.................................................................................2-900
24.2.5. Conditional Separation.....................................................................................2-900
24.3. Determining an Ability to Perform an Action or a  Dataset........................................2-909
24.4. Setting Separator Values on Startup............................................................................2-910
24.4.1. The Client Application Command Line............................................................2-911
24.4.2. The Web Client or Thin Client Connected via a  Web Server.........................2-912
24.4.3. External Connection and Connection Strings...................................................2-913
24.5. Safe Data Separation Mode.........................................................................................2-913
24.6. Data Area Deletion......................................................................................................2-915
24.7. Specifics of System Objects Behavior........................................................................2-916
Chapter 25. Developing solutions for the mobile platform...................................................2-917
25.1. General Information....................................................................................................2-917
25.2. The Application Interface............................................................................................2-918
25.3. Usage Specifics...........................................................................................................2-919
25.3.1. The Global Command Interface.......................................................................2-919
25.3.2. User Messages..................................................................................................2-919
25.3.3. Form..................................................................................................................2-919
25.3.4. Working With Files..........................................................................................2-921
25.3.5. Special Features................................................................................................2-922
25.3.6. Text Input..........................................................................................................2-924
25.3.7. Reports..............................................................................................................2-924
25.3.8. Working With Images.......................................................................................2-925
25.4. Interaction with a  mobile device during mobile application development................2-926
25.4.1. Installation of the 1C:Enterprise Mobile Platform for Developers ..................2-927
25.4.2. Publishing a  Mobile Application on the Web Server......................................2-929
25.4.3. Starting and Restarting an Application on the Mobile Platform......................2-931
25.4.4. Managing Applications on the 1C:Enterprise
Mobile Platform for Developers.......................................................................2-931
25.4.5. Mobile Application Checkup Before Publishing in  an Application Store.......2-933
25.5. Preparing the Mobile Application for Publishing in  an Application Store................2-935
25.5.1. For iOS..............................................................................................................2-935
25.5.2. For Android......................................................................................................2-936
Chapter 26. Development Tools...............................................................................................2-937
26.1. Form Editor.................................................................................................................2-937
26.1.1. Background Information...................................................................................2-937
26.1.2. Role-Based Form Setup....................................................................................2-942
26.2. Text Editor...................................................................................................................2-943
26.2.1. Editing Modules................................................................................................2-943
26.2.2. Editing Text Templates.....................................................................................2-957
1-16 1C:Enterprise 8.3. Developer Guide

26.2.3. Editing Template Text......................................................................................2-965

26.2.4. Query Text Editor.............................................................................................2-966
26.3. Configuration Command Interface Editor...................................................................2-966
26.3.1. General Rules for Setting Visibility..................................................................2-966
26.3.2. Filter by Roles...................................................................................................2-967
26.4. Start Page Work Area Editor.......................................................................................2-967
26.5. Main Section Command Interface Editor....................................................................2-968
26.6. Command Interface Editor..........................................................................................2-970
26.7. All Subsystems Editor.................................................................................................2-971
26.7.1. Subsystem Contents Setup................................................................................2-972
26.7.2. Subsystem Command Interface Settings..........................................................2-972
26.8. Query Wizard..............................................................................................................2-972
26.9. Query Wizard with Result Processing........................................................................2-979
26.10. Register Record Wizard............................................................................................2-980
26.11. Print Wizard..............................................................................................................2-982
26.12. Generation settings wizard........................................................................................2-985
26.13. Configuration Object Form Wizard..........................................................................2-987
26.13.1. Constant Form Wizard Features.....................................................................2-989
26.14. Template Wizard.......................................................................................................2-990
26.15. Format String Wizard................................................................................................2-992
26.16. Wizard for Strings in  Different Languages..............................................................2-995
26.17. Spreadsheet Document Editor...................................................................................2-996
26.17.1. Spreadsheet Documents in  1C:Enterprise......................................................2-996
26.17.2. Template.........................................................................................................2-997
26.17.3. Spreadsheet Document in  Data Input Mode................................................2-1001
26.18. Flowchart Editor......................................................................................................2-1006
26.18.1. Flowchart Editing.........................................................................................2-1007
26.18.2. Flowchart Items............................................................................................2-1007
26.18.3. Flowchart Items............................................................................................2-1009
26.18.4. Module..........................................................................................................2-1012
26.19. Picture Editor...........................................................................................................2-1012
26.19.1. Picture Editing..............................................................................................2-1013
26.19.2. Picture Collections........................................................................................2-1016
26.20. HTML Document Editor.........................................................................................2-1017
26.20.1. Visual Editing...............................................................................................2-1017
26.20.2. Editing in  HTML Format.............................................................................2-1020
26.20.3. Viewing Results............................................................................................2-1021
26.21. Localization of Configurations................................................................................2-1021
26.22. Centralized Configuration Check............................................................................2-1025
26.23. Usability Analysis for Operation of Solutions Based
on 1C:Enterprise Platform......................................................................................2-1031
Chapter 27. Debugging and Testing of Application Solutions............................................2-1033
27.1. Debugger...................................................................................................................2-1033
27.1.1. Debugger Use.................................................................................................2-1034
27.1.2. Breakpoint.......................................................................................................2-1042
27.1.3. Step-by-Step Execution..................................................................................2-1044
27.1.4. Debugging External Data Processors (Reports).............................................2-1046
27.1.5. Debug Management........................................................................................2-1046
27.1.6. Expression Window........................................................................................2-1047
27.1.7. Immediate Window.........................................................................................2-1049
Contents 1-17

27.1.8. Call Stack........................................................................................................2-1050

27.1.9. Debugging Protected Modules........................................................................2-1051
27.1.10. Use Options..................................................................................................2-1051
27.2. Performance Meter....................................................................................................2-1052
27.2.1. Available Options...........................................................................................2-1052
27.2.2. Measurement Results......................................................................................2-1053
27.2.3. Sorting Measurement Results.........................................................................2-1056
27.2.4. Selective Summarization of Measurement Results........................................2-1056
27.2.5. Performance Meter in  Client/Server Base Operation....................................2-1056
27.2.6. Saving Results................................................................................................2-1056
27.3. Server Call Delay Imitation.......................................................................................2-1057
27.4. Display of Server Calls.............................................................................................2-1057
27.5. Automated testing of applied solutions.....................................................................2-1060
27.5.1. General Information........................................................................................2-1060
27.5.2. Running the Testing system............................................................................2-1061
27.5.3. Description of features....................................................................................2-1064
27.5.4. Sample Testing Scenario................................................................................2-1068
27.5.5. Service Options...............................................................................................2-1069
Chapter 28. Compare and Merge Configurations...............................................................2-1071
28.1. Configuration Comparison Conditions.....................................................................2-1071
28.2. Launch of Configuration Comparing and Merging Mode........................................2-1072
28.3. Compare Configurations...........................................................................................2-1073
28.4. Compare Predefined Data.........................................................................................2-1074
28.5. Compare and Merge Configurations Window..........................................................2-1074
28.6. Configuration Comparison Setting............................................................................2-1075
28.7. Object Editing...........................................................................................................2-1077
28.8. Distributed Development and Support – Editing......................................................2-1077
28.9. Object Mapping.........................................................................................................2-1077
28.10. Merging Mode.........................................................................................................2-1078
28.11. Setting Order of Subordinate Objects.....................................................................2-1082
28.12. Viewing Differences...............................................................................................2-1082
28.13. Module Comparison................................................................................................2-1083
28.14. Filtering Objects and Activating Merging..............................................................2-1085
28.15. Loading Configuration from File............................................................................2-1086
Chapter 29. Distributed Configuration Development.........................................................2-1087
29.1. Configuration Repository Administration.................................................................2-1088
29.1.1. Creation of Configuration Repository............................................................2-1088
29.1.2. Open Configuration Repository......................................................................2-1089
29.1.3. Maintaining the Configuration Repository Users List....................................2-1092
29.1.4. Configuration Repository Administration......................................................2-1093
29.1.5. Repository Backup Configuration..................................................................2-1096
29.2. Working with Configuration Repository...................................................................2-1096
29.2.1. Configuration Repository Filter......................................................................2-1097
29.2.2. Locking Configuration Repository Objects....................................................2-1098
29.2.3. Object Placement in  Configuration Repository.............................................2-1099
29.2.4. Object Retrieval from Configuration Repository...........................................2-1100
29.2.5. Release of Object Locks.................................................................................2-1100
29.2.6. Update of Configuration Repository Object Statuses.....................................2-1101
29.2.7. Comparison of Configuration Repository and Current Configuration...........2-1101
1-18 1C:Enterprise 8.3. Developer Guide

29.2.8. Comparison of Configuration Repository Objects

and Current Configuration Objects.................................................................2-1101
29.2.9. Save Configuration Repository as Configuration...........................................2-1102
29.2.10. Disconnection from Configuration Repository.............................................2-1102
29.2.11. Configuration Repository History................................................................2-1102
29.2.12. Object History...............................................................................................2-1106
29.2.13. Actions with Configuration Repository without Connection.......................2-1107
29.3. Remote Work with Configuration Repository..........................................................2-1108
29.3.1. Architecture Overview....................................................................................2-1108
29.3.2. Configuration Repository Server Installation.................................................2-1110
29.3.3. Web Server Setup for Work with Configuration Repository.........................2-1111
29.3.4. Launch of Configuration Repository Server...................................................2-1116
29.3.5. Connection to Configuration Repository Server............................................2-1118
29.3.6. Creation of Configuration Repository............................................................2-1119
29.3.7. Remote Work with Configuration Repository (Special Features)..................2-1119
29.4. Recommendations on How to Use Configuration Repository..................................2-1120
Chapter 30. Configuration Distribution and Support.........................................................2-1121
30.1. Distribute Configuration...........................................................................................2-1122
30.1.1. Distribution Set Options.................................................................................2-1122
30.1.2. Creation of Distribution Files.........................................................................2-1124
30.1.3. Preparing Distribution Kits for Standard Configurations...............................2-1125
30.2. Configuration Support...............................................................................................2-1131
30.2.1. Setting Configuration Support........................................................................2-1132
30.2.2. Support Setting...............................................................................................2-1132
30.2.3. Configuration Update.....................................................................................2-1136
30.2.4. Template Directory Description File..............................................................2-1141
Chapter 31. Service Features.................................................................................................2-1143
31.1. Window Management ..............................................................................................2-1143
31.1.1. State (Window Placement Mode)...................................................................2-1143
31.1.2. Window Settings Dialog Box.........................................................................2-1146
31.1.3. Use of New Window Mode............................................................................2-1147
31.1.4. Service Windows............................................................................................2-1147
31.1.5. Closing Windows............................................................................................2-1147
31.1.6. Window Navigation History...........................................................................2-1148
31.2. Setting Designer Parameters.....................................................................................2-1148
31.2.1. General............................................................................................................2-1148
31.2.2. Texts...............................................................................................................2-1149
31.2.3. Modules..........................................................................................................2-1150
31.2.4. 1C:Enterprise Startup......................................................................................2-1154
31.2.5. Help.................................................................................................................2-1159
31.3. Calculator..................................................................................................................2-1160
31.4. Calendar....................................................................................................................2-1160
31.5. Text Templates..........................................................................................................2-1160
31.5.1. Template List Maintenance............................................................................2-1161
31.5.2. Editing Templates...........................................................................................2-1162
31.6. Syntax Assistant........................................................................................................2-1170
31.6.1. Syntax Assistant Settings................................................................................2-1171
31.6.2. Content Tab of Syntax Assistant....................................................................2-1171
31.6.3. Copying 1C:Enterprise Script Items...............................................................2-1172
Contents 1-19

31.6.4. Search in  Syntax Assistant.............................................................................2-1172

31.7. File Comparison........................................................................................................2-1175
31.7.1. Comparison of External Data Processors.......................................................2-1176
31.8. Built-in System for Help Content Retrieval..............................................................2-1176
Chapter 32. Add-Ins...............................................................................................................2-1177
32.1. Work in  Thin and Thick Clients...............................................................................2-1178
32.2. Work in  Web Client.................................................................................................2-1178
32.3. Work on Server.........................................................................................................2-1179
32.4. Examples of Add-In Use...........................................................................................2-1180
32.4.1. Native API Technology..................................................................................2-1180
32.4.2. COM Technology...........................................................................................2-1182
Chapter 33. Specifics of Cross-platform Applied Solution Development..........................2-1183
33.1. File System Specifics................................................................................................2-1183
33.2. Working with External Devices................................................................................2-1184
33.3. Rights Limitations.....................................................................................................2-1185
33.4. Fonts..........................................................................................................................2-1185
33.5. HTMLDocumentField...............................................................................................2-1185
33.6. COM, OLE, and ActiveDocument Mechanisms.......................................................2-1186
Appendix 1. URL Formats.....................................................................................................2-1187
1.1. URL Format Overview................................................................................................2-1187
1.2. Host Address Format...................................................................................................2-1188
1.3. Internal Links..............................................................................................................2-1189
1.3.1. Infobase Object Link........................................................................................2-1189
1.3.2. Infobase Object Attribute Link.........................................................................2-1190
1.3.3. Infobase Object Tabular Section Attribute Link...............................................2-1190
1.3.4. Infobase Register Record Link.........................................................................2-1190
1.3.5. Infobase Register Record Attribute Link..........................................................2-1191
1.3.6. Report Link.......................................................................................................2-1191
1.3.7. Data Processor Link..........................................................................................2-1191
1.3.8. Section Link......................................................................................................2-1191
1.3.9. Link to the Navigation Point Created by the Standard Command...................2-1192
1.3.10. Temporary Storage Link.................................................................................2-1192
1.3.11. Link to an External Data Source Table Record..............................................2-1192
1.3.12. Links to Global Command Interface Commands...........................................2-1192
1.3.13. Links to Lists..................................................................................................2-1193
1.3.14. Link to the start page......................................................................................2-1193
Appendix 2. Rules for Generating Standard Commands
and Automatic Form Headers....................................................................................2-1195
Appendix 3. List of Auto-Saved Settings..............................................................................2-1199
Appendix 4. Full-Text Search Expressions...........................................................................2-1207
Appendix 5. Description of Access Rights............................................................................2-1209
Appendix 6. System Behavior in  Various Modes................................................................2-1213
6.1. Special Characteristics of Low Connection Speed Mode...........................................2-1213
6.2. Special Characteristics of Compatibility Mode..........................................................2-1214
6.3. Specific Characteristics of Web Client.......................................................................2-1220
6.4. Web Client Specifics for iPad.....................................................................................2-1228
1-20 1C:Enterprise 8.3. Developer Guide

6.5. Specifics of System Object Behavior with Enabled Data Separation Mode...............2-1229
6.5.1. Changing Separator Values..............................................................................2-1229
6.5.2. Object Numeration............................................................................................2-1230
6.5.3. Real-Time Timestamp......................................................................................2-1230
6.5.4. Predefined Data.................................................................................................2-1230
6.5.5. Access Rights....................................................................................................2-1231
6.5.6. Users.................................................................................................................2-1231
6.5.7. Exchange Plans.................................................................................................2-1232
6.5.8. Functional Options............................................................................................2-1233
6.5.9. Scheduled Jobs..................................................................................................2-1233
6.5.10. Background Jobs.............................................................................................2-1234
6.5.11. Web Services..................................................................................................2-1235
6.5.12. Constants.........................................................................................................2-1235
6.5.13. Registers.........................................................................................................2-1235
6.5.14. Document Sequence.......................................................................................2-1238
6.5.15. Infobase Options.............................................................................................2-1239
6.5.16. Session List.....................................................................................................2-1239
6.5.17. Connection List...............................................................................................2-1239
6.5.18. The Event Log................................................................................................2-1239
6.5.19. Settings and Favorites.....................................................................................2-1243
6.5.20. History............................................................................................................2-1243
6.5.21. Queries............................................................................................................2-1244
6.5.22. Managed Transaction Locks...........................................................................2-1244
6.5.23. Exclusive mode...............................................................................................2-1244
6.5.24. Deleting Marked Objects................................................................................2-1245
6.5.25. Full-text search...............................................................................................2-1245
6.6. Running the Client Application in  Linux...................................................................2-1246
6.7. Specifics of Mobile Application Operations...............................................................2-1247
Appendix 7. Operation of Various DBMS............................................................................2-1249
7.1. General Features..........................................................................................................2-1249
7.2. File Database...............................................................................................................2-1249
7.3. IBM DB2 Server.........................................................................................................2-1250
7.4. Microsoft SQL Server.................................................................................................2-1251
7.5. Oracle Database Server...............................................................................................2-1252
7.6. PostgreSQL Server......................................................................................................2-1253
Appendix 8. Work in  XBase..................................................................................................2-1255
8.1. Fields and Records......................................................................................................2-1255
8.2. Spreadsheet, Spreadsheet Structure and Database File...............................................2-1255
8.3. Indices, Index and Filter Expressions and Index File.................................................2-1256
8.4. Writing Changes to Database......................................................................................2-1256
8.5. Work with Index Files.................................................................................................2-1256
8.6. Record Deletion...........................................................................................................2-1256
8.7. Creation of Database, Index and Index File................................................................2-1257
8.8. Limitations..................................................................................................................2-1257
Appendix 9. Specifics of Using Separate Mechanisms........................................................2-1259
Appendix 10. Automatic Form Element Name Generation Rules.....................................2-1261
 INTRODUCTION

This book is  the guide for application development in  1C:Enterprise.
This document can be used by specialists developing, modifying and implementing
applications based on the 1C:Enterprise platform.

STRUCTURE OF THE GUIDE

The guide contains a  description of the overall concept of the 1C:Enterprise system
and explains techniques for working with system objects, creating forms and
command interfaces and using various service mechanisms.
Chapter 1 lays out the concept of the 1C:Enterprise system: its underlying princi-
ples, general operation and more.
Chapter 2 covers how to work with the entire configuration: edit configuration
attributes, copy configuration objects, save the configuration, merge configurations
and use additional operation modes.
Chapter 3 describes application interface and its operation.
Chapter 4 contains general information about the 1C:Enterprise script, describes
data types, operators and syntax and covers general methods for working with the
1C:Enterprise script.
Chapter 5 deals with the main configuration objects and their features.
Chapter 6 is  focused on the command interface and its development.
Chapter 7 describes forms, their components and methods of use in the
1C:Enterprise script.
Chapter 8 covers the query language and basic methods of using queries in  the
1C:Enterprise script.
Chapter 9 explains the general principles and specifics of working with data
in 1C:Enterprise.
Chapter 10 describes the data composition system.
1-22 1C:Enterprise 8.3. Developer Guide

Chapter 11 highlights the accounting procedures used in  1C:Enterprise.

Chapter 12 explains how to use periodic calculation tools in the 1C:Enterprise
system.
Chapter 13 contains a  description of business processes and tasks.
Chapter 14 covers data analysis and forecasting.
Chapter 15 is  focused on data exchange.
Chapter 16 describes the XDTO mechanism.
Chapter 17 highlights the Web services mechanism.
Chapter 18 outlines how jobs function.
Chapter 19 describes full-text database search tools.
Chapter 20 demonstrates how to work with temporary data storages and use them
for operations with files.
Chapter 21 describes how to work with the Event Log.
Chapter 22 describes the cryptographic mechanism.
Chapter 23 describes how to work with external data sources.
Chapter 24 focuses on data separation.
Chapter 25 describes the mobile application development.
Chapter 26 explains how to use a special form editor, text editor, spreadsheet
editor, flowchart editor and picture editor.
Chapter 27 outlines configuration debugging and testing.
Chapter 28 depicts how to compare and merge configurations.
Chapter 29 illustrates how to prepare for and perform distributed configuration
development.
Chapter 30 describes creation of distribution files, update files and distribution kits.
This chapter is especially interesting for developers of standard configurations.
It  also highlights how to use distribution and update files for standard configura-
tions supported by user configuration developers.
Chapter 31 explains the service modes: setting up parameters of the Designer,
working with the Syntax Assistant, customizing templates, using built-in calculator
and calendar, comparing files, working with dialog boxes and localizing configura-
tions in  the 1C:Enterprise system.
Chapter 32 details how to connect external components.
Chapter 33 contains recommendations on cross-platform applied solutions devel-
opment.
Introduction 1-23

WHAT YOU NEED TO KNOW

In writing this guide, we assumed that you were familiar with the operating
system of the computer running 1C:Enterprise (Microsoft Windows 2000,
Microsoft Windows XP, Microsoft Windows Vista, all referred to as "Microsoft
Windows" hereinafter) and possessed the basic skills for working with it.
You should be familiar with the following concepts and skills:
„„ using the Start menu to start programs
„„ working in  dialog boxes
„„ using the mouse
„„ using standard techniques for working with text and spreadsheets (entering text,
entering values into spreadsheet cells, editing, formatting, printing, etc.)
„„ using menus
„„ using dialog box controls
„„ working in  standard dialog boxes
„„ using the Microsoft Windows clipboard (hereinafter referred to as "clipboard")
„„ customizing Microsoft Windows using Control Panel
If you haven't completely mastered the concepts and skills listed above, we recom-
mend you refer to the operating system documentation.

THE BOOKS INCLUDED IN  THE DOCUMENTATION

The documentation includes the following books covering the 1C:Enterprise tech-
nological platform:
„„ "1C:Enterprise 8.3. User Manual". Describes the basic concepts and features
that are common for all 1C:Enterprise applications.
„„ "1C:Enterprise 8.3. Developer Guide". Describes how to customize applications
to reflect the accounting procedures in  a specific company, as well as how to
develop new applications.
„„ "1C:Enterprise 8.3. Administrator Guide". Describes 1C:Enterprise administra-
tion, including features related to building client/server systems.
„„ "1С:Enterprise  8.3. Client/Server. Administrator Guide". Describes
1C:Enterprise installation and operation with client/server infobase versions.
The syntax of the 1C:Enterprise script and query language is described
in "1C:Enterprise 8.3. Developer Guide". The full object model description
is included in the distribution kit in the electronic form (in the Designer help
topics and in  the Syntax Assistant).
IMPORTANT!
The distribution kit for a  specific product may not include all of the above books.
1-24 1C:Enterprise 8.3. Developer Guide

Training Materials and Additional Opportunities

1C Company supports 1C:Enterprise users in  adopting and deploying its solutions.
Support includes various sources of information that will help develop and use
applications properly and efficiently.

Text Files Included in  the 1C:Enterprise 8.3 Distribution Kit

The distribution kit includes electronic documents that include the list of features
added in  this version and migration recommendations. They are copied to the hard
disk during 1C:Enterprise installation. They are copied to the hard disk during
1C:Enterprise installation.
These documents are located in  the directory with 1C:Enterprise installation files,
in the \docs\en subdirectory. If you do not change the default installation path, they
are copied to C:\Program Files\1cv8\VersionNumber\docs\en. The  VersionNumber
stands for the 1C:Enterprise version number. For example, this is how the path
looks for version 8.3.3.721: C:\Program Files\1cv82\8.3.3.721\docs\en.
The file V8Update.htm contains the list of changes as compared to previous plat-
form versions, and update instructions.

ABOUT 1C:ENTERPRISE 8 PAGE

1C:Enterprise is  a universal cloud and on-premise system of programs for auto-
mating a company’s financial and wider operational activities. 1C:Enterprise
has the breadth of capability to address the diverse needs of today’s business.
This  is  achieved through "configurability" – the ability to customize the system
based on the specific needs of companies and their business processes.
For detailed information on 1C:Enterprise features, see http://1c-dn.com/1c_enterprise/.

1C:DEVELOPER NETWORK
1C:Developer Network at http://www.1c-dn.com helps developers to create business
solutions based on the 1C:Enterprise platform.
The 1C:Developer Network knowledge base at http://1c-dn.com/library/ has informa-
tion for both novice and experienced developers, and provides you with everything
needed to create a  complete business solution from scratch.
Introduction 1-25

AGREED NOTATION
To help you understand the material, this guide uses some general techniques to set
off certain text elements. You will find the agreement on these techniques below.
Keys: Keys such as Enter, Esc, Del and the like will be shown with the lettering on
the keys themselves, without quotation marks.
When referring to cursor control keys (arrow keys), we will use the phrase cursor
control keys when we need to refer to all these keys at once. If we need to refer to
these keys individually, we will use the expressions Up Arrow, Down Arrow, Right
Arrow and Left Arrow.
Keyboard Shortcuts: When you need to press a combination of two keys to
execute a  command, it  will be presented as Ctrl + F3.
Buttons: The names of the buttons in a form will be presented by their names
without quotation marks, for example, OK, Cancel, Delete and so forth.
1C:Enterprise Script Keywords: Keywords of the 1C:Enterprise script will be
highlighted by a  font and written as in  program modules: WorkingDate. The  text
might also contain references to descriptions of sections or items in  the 1C:Enter-
prise script (properties, methods, etc.). To view these descriptions, use Help content
(1C:Enterprise script branch).
Menu Actions: To describe selection of a  menu item, we will use the following
sequence: Menu – Submenu – Submenu – … – Item. For example, "To choose the
scale, use Table  – View  – Scale." It  is  the same as the following: "To select the
image scale, use Scale on the View submenu of the Table menu in  the program's
main menu." If the selection is  not to be made in  the main menu, this is  specifi-
cally described.
1C:Enterprise Operation Modes: The  1C:Enterprise system has two modes of
operation: configuration setup and verification mode (hereinafter "Designer mode"
or "Designer" to refer to configuration creation or modification) and configuration
running mode (hereinafter "1C:Enterprise mode").
For the purposes of this guide, a  user means a  specialist who develops or supports
a configuration.
The %APPDATA% expression refers to a  Windows environment variable which
contains a path to a directory (in the user profile) for the applications used for
storing data. If the default installation is  used (for the user name Ivanov), the path
will appear as follows:
C:\Documents and Settings\Ivanov\Application Data

For Windows Vista and later versions the path will appear as follows:
C:\Users\Ivanov\AppData\Roaming
1-26 1C:Enterprise 8.3. Developer Guide

%LOCALAPPDATA% means a Windows Vista and above environment

variable that contains a  directory path (in the user’s profile) where user-specific
application data resides. In a standard installation (for an Ivanov user) this path
looks as follows:
C:\Users\Ivanov\AppData\Local
Chapter  1

CONCEPT OF THE SYSTEM

1C:Enterprise is an all-purpose enterprise automation system. The all-purpose

nature of the 1C:Enterprise system means it can be used to automate the most
diverse areas of economic operations: accounting for merchandise and materials,
mutual settlements with contractors, etc.

1.1. CONFIGURABILITY
A major feature of the 1C:Enterprise system is  its configurability.
The 1C:Enterprise system itself is a set of mechanisms designed to manipulate
various types of objects in  a subject area. A set of objects, data array structures and
information processing algorithms for the assigned task are defined by a  specific
configuration. Joined with the configuration, the 1C:Enterprise system functions as
a  ready-to-use software product customized for particular enterprise types and task
classes.
The configuration is  created and supported by standard system tools. A configura-
tion is  usually supplied as standard for a  particular area of application, but it  may
be modified or extended by the user or developed from scratch. The  1C:Enterprise
system supports standard configurations using standard tools.

1.2. FUNCTIONING OF THE SYSTEM

Functioning of the system involves two processes: development (description of
a  subject-area model by system tools) and execution (processing of subject-area
data).
The development stage includes:
„„ Structuring the processed information
„„ Creating forms for source data entry and data list display
1-28 1C:Enterprise 8.3. Developer Guide

„„ Storing the entered and derived information

„„ Generating reports and data processors
„„ Creating command interfaces for various user groups
„„ Creating a  user list
„„ Assigning rights to users
Development results in  software (configuration) representing a  model.
The designing mode permits the user to create new configurations, edit the existing
ones and compare or merge several configurations.
At the development stage, the system uses universal concepts or objects such as
Document, Document Journal, Catalog, Attribute, Form, Register and others. A set
of these concepts defines the concept of the system. In  its turn, the configuration
process is  broken down into several components (this is  an arbitrary division) that
define the order in  which volumes of description are written and assigned. These
are "visual" configuration (creation of the configuration structure, forms for dialog
boxes and output documents, user-data interaction mechanism or interface and
access rights of various user groups to various types of information) and generation
of programs in  the 1C:Enterprise script for processing input and output data.
The actual concepts of objects and standard operations for processing them are
defined at the system level. Configuration tools can be used to describe the structure
of information included in  the objects and algorithms that describe the specifics of
their processing to account for their various accounting features.
The information structure is  designed at the level of the processable subject-area
objects specified in  the system (constants, catalogs, documents, registers, enumera-
tions, etc.).
As it  runs, the system works with specific concepts described at the configuration
stage (product and organization catalogs, bills, invoices, etc.).
When the user works in  the 1C:Enterprise mode, information is  processed both
with standard system tools and using algorithms created at the configuration stage.

1.3. BASIC CONCEPTS OF THE SYSTEM

This section discusses the basic concepts used by the 1C:Enterprise system.
It  is  useful to those who are not yet familiar with the 1C:Enterprise system.
The description of various mechanisms is illustrated with examples. You can
encounter unfamiliar terms and concepts in the description. Keep reading – the
meaning of the terms used will become clear as you do so; if you want more
detailed information, you can always refer to the corresponding chapters of this
guide.
Chapter 1. Concept of the System 1-29

1.3.1. Configuration Concept

The basic concept is  that of configuration.
In the 1C:Enterprise system, a configuration means a set of interrelated compo-
nents:
„„ subsystems
„„ accounting data structures and data input, selection and print forms
„„ a set of mechanisms for totals accounting and register records of accounting
data
„„ a set of various reports and data processors
„„ command interface
„„ a set of roles or access rights
„„ a set of common procedures and functions (application module, managed
application module, external connection module, session module, and common
modules), spreadsheet templates, etc.
„„ auxiliary objects:
○○ functional options and their parameters
○○ settings storages
○○ Web tools (Web-services, WS references)
○○ various auxiliary information (pictures, templates, styles, etc.)
In fact, a configuration structure is a subject area model. A configuration
is created using the Designer. The resulting configuration is used by the
1C:Enterprise system to create a  software environment suitable for the accomplish-
ment of the necessary accounting tasks.
Roles in  the 1C:Enterprise system define whether users can work with informa-
tion processed in  the system. A set of privileges granted to the user is  generally
defined by the scope of the user's duties.
Assignment of roles to the user accomplishes two things:
„„ On the one hand, it  limits the number of users having access to sensitive infor-
mation that is  always a  part of any accounting system.
„„ On the other hand, prohibition of certain operations (primarily data deletion and
editing) helps prevent a  possible loss of information.
All components of a  configuration are closely interrelated and generally require
consistency in  making changes (this applies especially to user rights).
Thus, roles can be assigned only for existing configuration objects (specific docu-
ments, journals, catalogs or reports). Insertion of an object into the configuration
structure must be accompanied by appropriate role changes.
When creating a  command interface, the system accounts for the assigned object
rights. For example, if a  user is  not allowed to view a  catalog, the Open command
1-30 1C:Enterprise 8.3. Developer Guide

for the catalog list form is automatically removed from the command interface.
When displaying forms, granted rights are also important.

1.3.2. Configuration Object

In the 1C:Enterprise system, a  configuration object means a  formal description of
a  group of concepts (the subject area and the means of interaction between the user
and the system) with similar characteristics and the same purpose.
Consider the following example. The  Catalog configuration object in  1C:Enter-
prise is intended for maintaining lists of similar data items: catalogs, card files,
regulatory handbooks and the like. Use of this type of configuration objects enables
the user to organize any catalogs needed to automate enterprise operations.
As a  rule, Catalog type configuration objects are electronic equivalents of catalog
types that actually exist at the enterprise (e.g., a  catalog of employees or a  product
list), although they can also be used to organize lists that have no obvious physical
equivalents.
Please keep in mind that configuration objects describe value types rather than
specific values. For example, the Persons catalog does not describe particular
persons; it contains a list of attributes (a set of characteristic types for an indi-
vidual person) as well as forms for entering their values, forms for viewing lists
and templates for printing information. In  other words, the configuration contains
a  descriptive model that is  used to account for all similar objects in  a subject area
(in the above example with the Persons catalog, a  single description is  used for
both Peters and Jones or any other person).
Therefore, a configuration object is an electronic equivalent of a particular
concept in a subject area implemented in the 1C:Enterprise system using
a  configuration object.

1.3.2.1. Properties of Configuration Objects

Each configuration object possesses a unique set of properties. This set
is  described at the system level and cannot be changed during task configuration
setup. The property set of a configuration object is determined mainly by its
purpose in  the 1C:Enterprise system.
The main property of any configuration object is  its name – a  short description of
the configuration object. When a  new configuration object is  created, it  is  auto-
matically assigned a  conventional name consisting of a  word determined by the
object type and a  number (for example, when an attribute is  created, it  is  named
Attribute1; when a document is created, it is named Document1, etc.).
This  name can be changed when editing configuration object properties; the system
makes sure names are unique. The  name of a  configuration object cannot be null.
Chapter 1. Concept of the System 1-31

Of all the properties inherent in a configuration object, some are available for
editing and can be modified during system configuration. Types of possible
changes and their limits are set at the system level. The specialist configuring
the system can intentionally modify properties of a  configuration object to make
it  behave as desired when the system runs. However, these changes do not alter the
essence of the object and will not enable it  to perform actions that are not inherent
in  objects of this type.
Consider the following example.
The Constant configuration object in the 1C:Enterprise system is designed to
store information that does not change over time or changes very rarely. Previous
values of a  constant are irrelevant. A simple example of a  constant would be the
name of the enterprise: it generally does not change as the enterprise operates
(if you expect to select values of time-variable accounting data depending on the
timing, you should use an information register without dimensions rather than
a constant).
A constant has a  large number of editable properties. The  following are the most
relevant:
„„ constant name
„„ synonym (alias)
„„ comment
„„ data type
„„ data lock control mode
„„ link opening the constant manager module
In the most general case, the value of a  constant is  entered once (for example, the
enterprise name). From the standpoint of constant use, it is not important what
exactly is  stored in  the constant; what matters is  that the constant should preserve
the entered value.
The ability to preserve the entered value is  an integral feature of constants in  the
1C:Enterprise system. Editing constant properties does not affect this ability.

1.3.2.2. Basic Types of Configuration Objects

All the configuration objects that exist in  the 1C:Enterprise system fall into several
basic types. Each type makes up one of the "building blocks" that are used to create
a configuration.
Formally, configuration objects are combined into types in  the configuration tree.
Type names are displayed at the top level of the configuration tree when you open
the Configuration window in  the Designer (see fig. 1).
Even though there is  no formal definition, names of configuration object types are
widely used when working with the 1C:Enterprise system.
1-32 1C:Enterprise 8.3. Developer Guide

Fig. 1.  Metadata Tree

For example, a  specialist who configures the 1C:Enterprise system aims to develop
a required set of catalogs, documents, reports and journals that implement the
desired accounting system. The  end user of the 1C:Enterprise system – an execu-
tive, accountant, manager, storage clerk, etc. – also works with particular catalogs,
documents and so forth to accomplish his/her tasks. These two categories of users
also communicate in  terms of configuration object types.
A data object of some type is  a specific document, report, journal, constant, etc.
Each object is  generally used to work with specific information of a  subject area.
Below we outline basic types of configuration objects in  the 1C:Enterprise system.
Detailed information on the configuration objects that make up each of these types
is  provided later in  this guide.
Constants
The system uses Constant type objects for constant and nearly constant data.
Information stored in  constants rarely changes, but is  often used, as a  rule. For
example, constants can store the name of the enterprise, its tax ID, names of the
director and chief accountant and similar information.
The system supports an unlimited number of constants.
Catalogs
The system uses Catalog type objects for constant and nearly constant data
consisting of value sets.
Catalogs are usually lists of materials, products, entities, currencies, employees, etc.
Chapter 1. Concept of the System 1-33

The catalog engine allows the user to design and support various catalogs. Prop-
erties of each catalog can be described at the configuration stage. Customizable
properties include, for example, code length and type, number of hierarchical
levels, code uniqueness support and catalog attribute set.
Aside from the code and description, the catalog engine allows the user to create
attribute sets for storing any additional data about catalog items (e.g., for a  product
line it  could be the purchase and sale prices and the manufacturer; for an employee
it  could be his/her job title, education, residence, etc.) as well as tabular sections.
Tabular sections store variable arrays of similar-type data, such as description of
product components, list of employee family members, organization telephone
numbers, etc.
Each catalog has several form type options: item, folder, list, selection and folder
selection. You can create an unlimited number of forms of each type.
You can use subordinate catalogs to describe subordinate entities. In  this case, each
item of the subordinate catalog "belongs" to a  particular item of the parent catalog.
In a  specific configuration, the required number of catalogs is  created to store data
on objects used to automate the given subject area. For example, you might have
catalogs called Organizations, Goods, Employees, etc.
Enumerations
The 1C:Enterprise system uses enumerations to describe constant sets of values that
do not change as the configuration runs.
At the configuration stage, you can describe a virtually unlimited number of
enumerations. Unlike values in  a catalog, enumeration values are specified at the
configuration stage and cannot be changed at run time.
Typical examples of enumerations are forms of payment (cash, check or barter),
client status (regular or one-time), etc.
One of the main features of an enumeration that makes it  different from a  catalog
is  that a  set of values within enumeration does not change as the end user works
with the system. For example, the configuration algorithm could be designed so
that each client has one of two statuses: either "regular" or "one-time". In this
case, the user can specify the client's status by selecting one of the values from the
enumeration. The  user cannot add a  new status.
Enumerations are different from catalogs in  that you normally enter specific values
for catalogs as you work with the program, for example: product names, contrac-
tors, etc.
Documents
Documents are objects used to represent business process events pertaining to
the automated subject area. For example, a  configuration designed to account for
trading transactions may contain documents such as bills, receipts, invoices, etc.
1-34 1C:Enterprise 8.3. Developer Guide

Documents are used to show payments from the account, cash register transactions,
warehouse register records and other similar events.
Configuration involves customizing an arbitrary number of document types.
Typical examples of document types are Purchase Order, Bill, Goods Receipt, Sales
Invoice, Warehouse Transfer, Cash Receipt, etc. Each document type represents
a  certain event type. It  determines the structure and properties of the document as
defined in  the configuration.
Each document type can have an unlimited number of attributes and tabular
sections. Several tabular sections are required when one document must record
essentially different but related events, for example: to show receipt of goods at the
warehouse and record additional expenses incurred – payment for transportation,
truckers, etc.
Document data are entered via input forms which are on-screen equivalents of
hard-copy documents. If the document data are used in  other forms, forms selec-
tion are created to include this information. List forms are created for editing the
list of documents of a  given type. The  number of forms is  unlimited.
Each document can also have an unlimited number of print forms.
All documents are characterized by a number, date and time. At the document
setup step, other options such as document number length, number uniqueness rules
and others can be set.
Documents are central to the basic mechanisms implemented by the system. All
documents form a single chronological sequence. The latter represents the
sequence of actual events. Within a certain date, document sequence is defined
by the document creation time. The  document creation time is  a way of arranging
documents in  a proper and unambiguous order within the same date rather than
a record of the actual (astronomic) time of document input. Data entered in a
document (in its attributes and tabular sections) usually contain information about
an event – for example, an invoice contains information about the originating ware-
house, the type and quantity of goods shipped and any additional expenses incurred.
A crucial action for a  document is  its posting. If a  document is  not "postable",
it  means that the event it  reflects does not affect the state of the accounting main-
tained in  that particular configuration. If a  document is  posted, it  changes some
of the accounting data. Posting permits the event recorded in  the document to be
reflected in  the mechanisms implemented by various registers.
For example, a company can use Quote documents. These documents indicate
customer’s intents to buy goods or services and they usually do not alter the
status of the goods or cash. Therefore, they do not require posting transactions to
accounting registers.
In some cases a  Quote can be used for reserving goods for a  specific customer.
This locks a certain quantity of goods and removes them from the warehouse
balance. Therefore, this document will require posting the transaction to accounting
registers.
Chapter 1. Concept of the System 1-35

Document Journals
Document journals are designed for viewing various types of documents. Each
document type can be shown in  several journals. A document journal does not add
new data to the system; it  is  a means of displaying documents of several types
in  a single list.
For example, you can create a  Warehouse Documents journal which will show all
receipts and invoices as well as internal waybills.
You can define columns for a  journal to show attributes of the various document
types assigned to the journal. For example, a  trading document journal can include
a  Counterparty column that contains the Vendor attribute of a  Purchase Order
document, the Customer attribute of a  Sales Invoice document, etc.
Each journal can have an unlimited number of display and print forms.

Reports and Data Processors

To describe reports and information processing procedures, an unlimited number of
reports and data processors can be created at the configuration stage. Reports and
data processors can have several forms designed, for example, for entering report
generation or data processing parameters. For example, to generate a  warehouse
report, select a  specific warehouse.
The algorithm used to obtain a report can be described using the 1C:Enterprise
script or automatically created by the system if the data composition schema
is  used (see page 1-531). To generate reports, you can use either text format or
a  specialized tabular report format (templates).
The system also supports development of external data processors stored in  sepa-
rate files rather than the configuration.

Charts of Characteristic Types

In the 1C:Enterprise system, Charts of characteristic types objects are designed for
describing sets of similar analytical accounting objects.

Charts of Calculation Types

Objects of this type are designed for creating calculation types used in  periodic
payment mechanisms.

Charts of Accounts
A chart of accounts is  one of the basic accounting concepts. A chart of accounts
is  a set of synthetic accounts that group information about enterprise transactions.
Data stored in  synthetic accounts enable the user to get a  complete picture of the
state of enterprise funds in  monetary terms.
1-36 1C:Enterprise 8.3. Developer Guide

Exchange Plans
This object type is  used to arrange data exchange between different infobases or
between infobases and external software systems.

Business Processes and Tasks

These are designed to create formal descriptions of standard job sequences within
the organization that are later used to make lists of tasks assigned to an employee
at a  specific point in  time. For example, a  process of product sales can be repre-
sented as a  sequence of events: billing, bill approval, cash payment and product
shipment from a  warehouse. Each step can be assigned to a  different employee.
Therefore, you can see the state of the product sales process at every step and iden-
tify an employee responsible for specific actions at this step.

Registers
Registers are designed for storing and processing various information that reflects
the enterprise commercial and organizational operations and has no objective
nature.
Registers usually store information on changes in the status of objects or other
information that does not directly reflect subject-area objects. For example, regis-
ters can hold information on currency exchange rates or information on the receipt
and dispensing of merchandise.
The 1C:Enterprise system has four types of registers:
„„ information registers
„„ accumulation registers
„„ calculation registers
„„ accounting registers

Specialized Configuration Objects (Common Branch)

In addition to objects that describe the domain of accounting, the configura-
tion contains several auxiliary objects that do not relate directly to the enterprise
operations, but are closely tied to the functioning of the system itself. These are
mechanisms that help users interact with the 1C:Enterprise system (command
interfaces, filter criteria, access rights of various user groups to different types of
information); auxiliary formatting objects that enable configuring based on existing
styles, picture libraries that take the national language into account; the application
module and common modules containing procedures and functions accessible from
other configuration modules; common print form templates and much more.
Chapter 1. Concept of the System 1-37

1.3.2.3. Subordinate Object Groups

Depending on the type of a  configuration object, it  can have various subordinate
object groups. For example, attributes, dimensions, forms, tabular sections, etc.
The  type of the object determines the structure of its subordinate objects.
Attributes are additional object information that is accessible from within the
object only.
Tabular sections are sets of additional information about the object represented as
a table.
IMPORTANT!
A tabular section cannot contain more than 100,000 lines.
Attributes of tabular sections are the contents of the object tabular sections that are
accessible from within the object tabular sections only.
Forms are used to enter, view and edit information stored in a configuration
object; each form contains a form module, i.e. a program in the 1C:Enterprise
script. Having a visual representation configuration objects can interact with
users. Nature of this interaction is defined by the specialist who configures the
1C:Enterprise system and is  determined mainly by the type of the configuration
object. To  develop forms, the Designer has a  comprehensive form editor which
enables you to edit all components of a  form interactively. Each object can have
several forms.
Commands are used to run operations with an object. They can be independent or
defined by parameters.
Templates are spreadsheet, HTML or text documents (you can also use binary and
Active documents) designed to generate print forms for an object.
Graphs are columns of document journals.
Dimensions (for registers) are configuration objects with data accounted for in  the
register.
Resources are data accounted in  the register.
Groups of subordinate objects cannot be deleted and do not have editable proper-
ties.

1.3.2.4. Typed and Type-Specifying Objects

One of the main properties of certain configuration objects is  Type, which repre-
sents the object data type. This  property defines the kind of information that the
configuration object can contain. Configuration object data type is  set when object
properties are created or edited during configuration setup.
In the 1C:Enterprise system, configuration objects whose information type can be
specified are called typed configuration objects.
1-38 1C:Enterprise 8.3. Developer Guide

Configuration objects such as Catalog, Document and Data Processor are not
typed because they contain "complex" information and typed configuration objects.
Possible configuration object data types can be divided into two groups.
The first group comprises primitive data types: Number, String, Date and
Boolean. Accordingly, information stored in a configuration object can be
a number, an arbitrary character string, a date or a logical value. Additionally
primitive types include NULL, Undefined and Type (for details see section "Primi-
tive Data Types" in  the 1C:Enterprise script help).
Some configuration objects in the 1C:Enterprise system can also specify data
types. For example, a constant can be assigned the DocumentRef data type.
In this case, the constant value represents a reference to a document existing
in  the 1C:Enterprise system.
Configuration objects that can specify types of configuration values in the
1C:Enterprise system are called type-specifying configuration objects. These are:
„„ catalogs
„„ documents
„„ charts of characteristic types
„„ charts of accounts
„„ charts of calculation types
„„ exchange plans
„„ business processes
„„ tasks
„„ enumerations
Please note that type-specifying configuration objects specify the data type
as soon as the Designer creates any of these types of objects. Three new
types appear immediately: Ref, Object and List. For example, when the
Designer creates a new catalog, new data types appear in its list of data
types: CatalogRef.<CatalogName>, CatalogObject.<CatalogName> and
CatalogList.<CatalogName>. These data types can be assigned to any typed
configuration object.
Some data can be assigned composite data types. To do this, select the Composite
data type check box in  the data type editing window and specify the types that data
can have. You can also select a  special type, AnyRef.
In addition to selecting attribute data types defined in  a particular application, you
can select sets of types. AnyRef, CatalogRef and Characteristic.<name> are
examples of type sets.
Type sets, like the composite data type, contain a certain list of types defined
in the application, but, unlike the composite type, the system generates this list
automatically based on metadata analysis.
Chapter 1. Concept of the System 1-39

For example, an application contains Nomenclature and Contractors catalogs.

If composite data type attributes are defined and contain CatalogRef.Nomen-
clature and CatalogRef.Contractors types, you can define another attribute
containing the CatalogRef type set. In  both cases, the attribute can store refer-
ences to the Nomenclature and Contractors catalogs.
After you add a  new Prices catalog, the composite type attribute can still only
store references to the Nomenclature and Contractors catalogs, while the
attribute described as a  type set allows you to store references to any catalog avail-
able in  this configuration, including the Prices catalog.
Upon application startup, the system usually converts the type set to the composite
type which contains all types included in this set. Therefore, the new Prices
catalog is  included in  the type set in  the second case.
However, the system does not always convert the type set to the composite data
type. If a  single value type is  included in  the type set, it  is  converted to this value
type. This  is  possible when a  chart of characteristic types (e.g., Properties) has
a  single value type in  the CharacteristicValueType property. Then the system
converts the Characteristic.Properties type set to the only value type speci-
fied for the chart of characteristic types rather than to the composite data type.
This feature may be important when, for example, an attribute whose type
is described as Characteristic.Properties is checked for completeness.
If  Characteristic.Properties is converted by the system to the composite
data type, you should run a  check for the Undefined value; if Characteristic.
Properties is  converted to a  specific value type, a  check for the default value of
this type is  required.

1.3.3. Command Interface

Command interface is  a basic tool allowing the user to navigate the configuration
functionality. It is based on subsystems. The configuration developer includes
application objects into the corresponding subsystems.
This information (i.e. the structure of subsystems and object assignments to
subsystems) is  used in  the system to create a  command interface for the user auto-
matically. The user can see application structure (subsystem hierarchy) and use
standard commands to access application object functionality (e.g., call catalog or
document lists, open reports or data processors, etc.). At the same time, the devel-
oper can edit the system layout of the command interface (change the command
order and display options). A command interface editor serves this purpose. It  can
be called both for a  particular subsystem and for all subsystems.
Commands included in  the command interface (opening lists, entering new objects,
opening reports, etc.) are automatically provided by the system. The  developer can
also create custom commands to be displayed in  the command interface.
The interface gives users quick access to the information they need to perform their
duties.
1-40 1C:Enterprise 8.3. Developer Guide

1.3.4. Form
Form is  a combination of a  dialog box, module, attributes and commands.
Most configuration objects in  the 1C:Enterprise system can have a  visual form.
In  the most general case, a  form as a  configuration object comprises the following
components:
„„ on-screen dialog box used to enter and edit information;
„„ form module, i.e. program in the 1C:Enterprise script. The form module
generally processes information entered in the dialog box for input control,
calculations, etc.;
„„ list of attributes;
„„ commands used in  the form.
Any of the form components can be blank, in  other words, contain no information.
Forms can be used to implement user interaction with an application object.
The corresponding behavior is defined by the specialist who configures the
1C:Enterprise system. For details on form structure see page 1-361.
To develop forms, the Designer has a  form editor which enables you to edit all
form components interactively.

1.3.5. Module
Module is a program in the 1C:Enterprise script. Modules are located at speci-
fied points in  the configuration structure and executed at predefined times in  the
course of 1C:Enterprise operation. The  specialist who configures the system can
use modules to describe complex algorithms of interaction between configuration
objects that do not have adequate visual tools available in  the Designer.
A configuration has several types of modules. These are: managed applica-
tion module, ordinary application module, external connection module, session
module, common modules, form modules and configuration object modules (value
managers for constants, catalogs, documents, charts of characteristic types, charts
of accounts, charts charts of calculation types, exchange plans, business processes,
tasks, reports, data processors and sets of register records), configuration object
manager modules (for catalogs, documents, charts charts of characteristic types,
charts charts of accounts, charts charts of calculation types, exchange plans, busi-
ness processes, tasks, reports, data processors, information registers, accumulation
registers, accounting registers, calculation registers, enumerations, document jour-
nals and settings storages), record set modules (information registers, accumulation
registers, accounting registers, calculation registers), command modules.
To access a module, select Open Object Module… in the configuration object
context menu. Select managed application module, session module, external
connection module and ordinary application module for the root configuration
object. Some objects (for example, constants or document journals) have no
modules.
Chapter 1. Concept of the System 1-41

For a  detailed description of modules see section "What is  a Program Module?"
in  the 1C:Enterprise script help.
Within object modules you can declare variables, procedures and functions that
extend the object context and are available for working with the object externally
using the 1C:Enterprise script. These modules contain procedures for processing
various events, for example, Generate. They also have various procedures to
perform actions with an object that are initiated from outside the object (for
example, printing).
Manager module allows you to extend the system-provided manager functionality
by creating procedures and functions using the 1C:Enterprise script. In  fact, this
enables you to define methods for a  configuration object (e.g., a  catalog) that refer
to the configuration object in general rather than to a specific database object
instance. The  manager module cannot have variables or a  module body.
If the manager module procedures and functions are declared as exported, they are
accessible through the object module.

// Manager module of the Contractor catalog.

Function GetReceivablesList()
…
EndFunction

// Call from application code.

Receivables = Catalogs.Contractor.GetReceivablesList();

1.3.6. Template
In the 1C:Enterprise system a template is a configuration object designed to
generate print forms.
Common print form templates are located in the Common templates branch of
the configuration tree Common branch, while print forms of configuration objects
(catalogs, documents, document journals, charts of accounts, charts of character-
istic types, charts of calculation types, registers, reports, data processors and other
objects) are located in  Templates subordinate objects and in  external files (in the
latter case, you have to set the Template property for the spreadsheet).
Templates can be of the following types:
„„ Spreadsheet document: Standard methods to create and use templates are
expected. The  template is  prepared using the spreadsheet editor.
„„ Text document: Use of a  text document as a  template is  expected. The  text
template is  prepared using the text template editor.
„„ Binary data: Binary data are used.
„„ Active document: Use of OLE Active document method is  expected.
„„ HTML document: Use of HTML editor is  expected.
1-42 1C:Enterprise 8.3. Developer Guide

„„ Geographical schema: Use of a geographical schema prepared in the

geographical schema editor as a  template is  expected.
„„ Graphical schema: Use of a graphical schema prepared in the graphical
schema editor is  expected.
„„ Data composition schema: Use of a  data composition schema prepared in  the
wizard is  expected.
„„ Data composition appearance template: Use of a  data composition appear-
ance template is  expected.

1.4. OPERATION MODES

1C:Enterprise supports two operation modes:
„„ file mode
„„ client/server mode
In both versions all applications function in an identical way. The file mode
is  mostly intended for personal use, while the client/server mode is  used in  work
groups or throughout the organization.

1.4.1. File Mode

The file mode of infobase operation can be used by a  single user or by a  small
group of users in  the local network. In  this case all infobase data (configuration,
database and administration data) are stored in  a single file.
This version facilitates installation and operation of the automated system. There
is  no need in  additional software to operate the infobase, apart from the operating
system and 1C:Enterprise.
The file mode of 1C:Enterprise ensures infobase integrity and easy creation of
backup copies. System failure due to a  user error resulting in  storing infobase files
incorrectly (e.g., while copying the infobase) is  totally ruled out.
You can also create backups at the file level by simply copying the infobase file.
Despite its ease of use, the file mode has certain restrictions (see page 2-1249).

1.4.2. Client/Server Mode

The client/server mode can be used by work groups or the entire organization.
It  is  implemented as a  three-tier client/server architecture.
The client-side application interacts with the 1C:Enterprise server cluster,
while the cluster communicates with the database server, as necessary (Micro-
soft SQL Server, PostgreSQL, IBM DB2 or Oracle Database). Physically, the
1C:Enterprise server cluster and the database server can be located on either
a  single machine or different machines. This  is  useful if the administrator needs
to distribute the workload between the servers.
Chapter 1. Concept of the System 1-43

Using the 1C:Enterprise server cluster is a good way of centralizing the most
resource-intensive operations of data processing. For example, user applica-
tion can only retrieve the required data selection, while the server performs all
the processing, even with the most complex queries. Expanding a  server cluster
is  generally a  lot easier than upgrading all client machines.
Another important aspect of the three-tier architecture is  ease of administration and
streamlined access of users to the infobase. In  this mode the user is  not supposed
to know the physical location of the configuration or the database. Access is  always
granted through the 1C:Enterprise server cluster. When sending a request to
a database, the user is only required to specify the cluster and infobase names,
while the system prompts the user to enter username and password. For details on
system administration see "1C:Enterprise 8.3. Administrator Guide".
Although the 1C:Enterprise system tries to hide database server behavior from
the user, it  is  not always possible. For information about system interaction with
a  specific database server see page 2-1250.
An important feature of the client/server mode is the ability to run
the 1C:Enterprise server and database servers under various operating systems
(the Windows family and various Linux distribution kits).

1.5. DEVELOPMENT TOOLS

The 1C:Enterprise system uses several methods to describe specific algorithms for
processing information and creating an interface for convenient representation of
data described in  the configuration.
1C:Enterprise Script. The need in the 1C:Enterprise script is defined by the
system customizability concept. Syntax of the 1C:Enterprise script meets all the
standards of high-level languages.
The script is object-oriented. It supports specialized subject area data types
defined by the system configuration. The  1C:Enterprise script processes these data
types using object techniques. The  script is  designed for users with various levels
of qualification. In  particular, it  is  characterized by weak data typing (it supports
quick writing of program modules) and tight syntax check reducing probability of
errors.
Since the system combines visual and linguistic configuration tools, using the
1C:Enterprise script in  the system has an event-dependent orientation, i.e. script
modules are used at specific places to handle certain algorithms that are customized
in  the configuration process. Thus, you can describe an algorithm for automatically
filling in  document attributes when a  new document is  entered. The  system will
call this procedure when needed.
Query Mechanism. The  system provides an object-oriented query mechanism that
can produce any report with a  complex structure. This  tool relies on the existing
1-44 1C:Enterprise 8.3. Developer Guide

conventional variable structure of the system infobase permitting fairly complex

queries to be described in  a relatively simple way.
The built-in text editor is used to create program modules in the 1C:Enterprise
script and to edit text documents.
One of the editor features is  contextual color-coding of the 1C:Enterprise script
syntactic constructs and grouping various syntactic constructs.
When typing texts in  the 1C:Enterprise script, it  is  convenient to use tooltips and
templates.
The 1C:Enterprise script has powerful text manipulation tools, so you can use text
format successfully to share all types of information with other systems.
Built-in Form Editor. Working with customizable data structures and working
in  the Microsoft Windows interface requires the ability to setup information input
and editing forms arbitrarily. To do this, the 1C:Enterprise system has a  built-in
form editor.
The editor enables you to format most windows used in  the system to enter and
view object information (document and catalog forms and report settings).
Built-in Spreadsheet Editor. All output documents (primary documents and
reports) have a  uniform system-defined format: spreadsheet document format.
The spreadsheet editor is  a powerful tool that combines spreadsheet structure and
vector graphics formatting capabilities. It  can be used either to create small docu-
ments with very complex line structures (such as payment orders) as well as long
payrolls, journals and other similar documents.
The spreadsheet editor offers users a  rich variety of formatting capabilities (fonts,
colors, lines and patterns). It has the ability to output information in graphical
form (as charts).
One of the main features of the spreadsheet editor is  its orientation toward genera-
tion of reports using the 1C:Enterprise script. Flexible features of report creation
are ensured by a mechanism for manipulating named areas of a document.
The  spreadsheet editor permits manipulation of both horizontal and vertical areas
which makes it  possible to create reports scalable both horizontally and vertically.
Using the editor together with the data composition system enables you to create
all-purpose reports where you can process and represent information in various
ways and drilldown levels without additional developer intervention.
On the other hand, a  spreadsheet can serve as a  form control element and thereby
be used for data input.
Built-in Picture Editor. This  editor enables you to create pictures of any size and
use them as toolbar icons, button images and for other formatting purposes.
Built-in HTML Editor. This  editor enables you to create user descriptions and
has strong formatting capabilities (hyperlinking, use of styles, picture placement,
etc.).
Chapter 1. Concept of the System 1-45

Wizards are auxiliary tools that simplify development of standard items in the
1C:Enterprise system. For example, the system has wizards for constant forms,
catalogs, documents, document journals, reports and other objects; print form
wizards; register record wizards and more.
You can use wizards to generate visual components of these objects and, in  certain
cases (generating objects based on other objects, printing, output form, etc.), to
generate program modules.
User Interface Customization System. For the interface of a  particular system
configuration to fully include customized data structures and algorithms, the
1C:Enterprise system, in  addition to the dialog box form and spreadsheet editor,
provides a  functionality of system command interface setup.
The command interface is  set up automatically based on the access rights of a  user
logging into the system. Consequently, the user will only see accessible system
objects.
Subsystems. The Designer enables you to select various subsystems within
a single configuration (for example, trade accounting and research system) at
the design stage. You can specify configuration objects to be included in each
subsystem. A single object can be assigned to multiple subsystems. In essence,
subsystems define main configuration sections available to the user. Since the
subsystem structure defines the configuration interface, you should pay special
attention to subsystem design (and hierarchy).
Access Rights (Roles) Customization System. This  system permits description of
sets of rights corresponding to user job titles or types of activities. The  structure
of rights is  determined by the specific system configuration. For example, you can
create sets of rights such as Chief Accountant, Storekeeper, Manager and Head of
Department.
In addition, for objects stored in  the database (catalogs, documents, registers, etc.),
you can define access rights to specific fields and records.
The actual user list is  created for your specific organization. Each user is  assigned
one or more roles, default interface and language to be used when he or she works
with the program.
Debugger. The  system provides a  debugger for convenient configuration develop-
ment. The  debugger permits the user to follow execution of configuration program
modules, measure the relative execution time and inspect the contents of variables.
Configuration Repository. In  distributed configuration development, developers
use a  configuration repository mechanism. It  enables you to assign access rights to
modify a  configuration object and make the necessary changes concurrently rather
than sequentially.
Configuration Support. To make configuration updates easier, the system
provides a mechanism for developers to generate standard configurations of
distribution files and distribution kits (including installation program) as well as
a  mechanism for updating standard configurations under support contracts.
1-46 1C:Enterprise 8.3. Developer Guide
Chapter  2

WORK WITH CONFIGURATION

This chapter describes general techniques for working with configuration objects
which are applicable to objects of all types. We will discuss specifics of creating
and editing various types of configuration objects later, in  the corresponding chap-
ters of the guide.
This chapter mainly covers visual tools for configuration object management in  the
Designer. For a  description of the 1C:Enterprise script see the 1C:Enterprise script
help.
For information about saving and restoring infobases see "1C:Enterprise 8.3.
Administrator Guide" or "1C:Enterprise 8.3. Client/Server. Administrator Guide".
The 1C:Enterprise infobase stores two configurations:
„„ basic configuration (editable and referred to as "configuration")
„„ database configuration
The database configuration determines the structure of database tables and the full
set of functions accessed by users. The  master configuration is  only used to make
changes. When operated by users, it  allows changes to be entered and saved in  the
configuration. The database configuration cannot be changed when operated by
users. For information on working with the database configuration see page 1-63.

2.1. OPENING CONFIGURATION

Use the Configuration window to work with configurations. To open a  configura-
tion, select Configuration  – Open Configuration. The  Configuration window will
appear (see fig. 2).
To make more area available for working with various objects, you can temporarily
close the Configuration window. Closing the Configuration window does not end
your session with its individual components open for editing: you have not closed
1-48 1C:Enterprise 8.3. Developer Guide

the configuration, just the Configuration window. To open the Configuration

window, select Configuration – Configuration Window.

Fig. 2.  Configuration

2.2. SAVING CONFIGURATION

While editing a  configuration, you can create new objects, modify or delete the
existing objects and subordinate objects (forms, attributes, etc). Any change of this
kind results in  a modified configuration. If the configuration has been modified,
the * character appears in  the Configuration window title.
To save the configuration (without ending your session), select Configuration  –
Save Configuration. This menu item is available if the configuration has been
modified, while text, spreadsheet and HTML editors always display this item.
You can save a  changed configuration at any time even if the 1C:Enterprise mode
has been started or during debugging.

2.3. CLOSING CONFIGURATION

To close the configuration, select Configuration – Close Configuration. If the config-
uration has been modified (if you have made changes), the Designer will prompt
you: Configuration has been changed. Save changes? To save your changes, click
Yes.
You can close the configuration and save changes at any time even if the
1C:Enterprise mode has been started or during debugging.
Chapter 2. Work with Configuration 1-49

2.4. SAVING CONFIGURATION TO FILE

To save a  configuration to a  file on disk, select Configuration – Save Configuration
to File. The  standard file selection dialog box will be displayed. Choose a  direc-
tory and specify the file name to save the configuration.
You will need the saved configuration file if you want to compare or merge
configurations (see page 2-1071).
NOTE
If the configuration is  supported, the infobase always stores a  vendor configura-
tion.

2.5. LOADING CONFIGURATION FROM FILE

To completely replace the current configuration with one saved to a file, select
Configuration – Load Configuration from File.

2.6. CONFIGURATION OBJECT TREE

The configuration is displayed as a tree structure where each branch describes
a component of the configuration. Configuration objects on the configuration
tree are represented by their names. For example, the Documents branch contains
objects for all documents used in  the configuration, the Invoice branch describes
the Invoice document object, the Common  – Roles branch describes all roles
(information access rights) used for various user types, the SalesManager branch
describes access rights for a  the sales manager, etc.
The root branches of the tree consolidate general-purpose configuration objects that
are logically interrelated.
For example, the Documents branch consolidates Sequence and Document
numerator type objects as well as Document type objects. All these objects are
designed for document entry into the 1C:Enterprise system.
When working in the Designer, use the keyboard for convenience. A list of
keyboard shortcuts used in the Designer is available in the built-in help (see
section Keyboard shortcuts (Designer)).
You can arrange configuration objects in whatever order you like within "their
own" group of configuration objects. The same order is used to display the
configuration objects in  various lists.
To move a configuration object, select it in the Configuration window and use
menu items Actions – Move Up or Actions – Move Down or else Actions – Sort.
To easily find an object you are currently editing in the configuration tree (an
object editing window, form, template or module), use Edit  – Find in  Tree. First
make the object editing window active. After you execute the command, the object
you are currently editing is  selected in  the configuration tree.
1-50 1C:Enterprise 8.3. Developer Guide

You can search the metadata tree using one of two methods:
„„ Start entering the object name (it searches the object in  open tree branches only).
„„ Use standard search functionality (press Ctrl  +  F to open the search window).
This  opens the Search results window where you can navigate to the required
metadata object.
You can use the mouse to drag names of configuration objects and subordinate
objects (attributes, tabular sections, forms, etc.) into modules and text documents.

2.7. METADATA TREE SORT SETTINGS

This mode is  designed for sorting configuration objects. You can sort same-type
configuration objects subordinate to one configuration object simultaneously.

Fig. 3.  Sorting Metadata

For example, forms that belong to a  specific catalog.

„„ Sort by: Choose the property to be used as a  sorting criterion:
○○ Name. Configuration objects are sorted by name.
○○ Synonym. Configuration objects are sorted by synonym.
○○ Comment. Configuration objects are sorted by comments.
„„ Sort direction: Select the sort direction:
○○ Ascending. Results are presented in  ascending order.
○○ Descending. Results are presented in  descending order.

2.8. CREATION AND DELETION OF CONFIGURATION OBJECTS

2.8.1. Create Configuration Objects
You can manage most configuration objects in the Configuration window.
This  section outlines common techniques for creating configuration objects which
apply to all types of configuration objects.
To create a  new configuration object, do the following:
„„ In the configuration tree, select the name of the configuration object type or any
existing configuration object of the type to be used for the new object.
Chapter 2. Work with Configuration 1-51

„„ In the Configuration window, select Actions – Add.

You can also create a  new subordinate object as follows:
„„ Open the object editing window (in the Configuration window, select Actions –
Change).
„„ Specify the desired type of subordinate object.
„„ Click Add.
As a  result, a  new object appears on the current branch of the configuration tree,
and its properties palette where you can edit the object properties is  automatically
displayed if not open yet (for more on how the properties palette works see page
1-53). Objects with a  wide range of editable properties allow you to call up the
editing window in  addition to the properties palette (for more on how this window
works see page 1-59).
The new configuration object is assigned a conventional name consisting of
a  word that corresponds to the type of object created and a  number – the sequence
number of the new configuration object. For example, a  new catalog name begins
with Catalog. The  object properties palette contains default property values.
The Designer checks the object names before the database configuration is  updated
and the distribution is  generated.
For objects that can have subordinate objects (for example, a catalog can have
attributes, tabular sections, forms and templates), the desired number and content
of subordinate objects are created. You can shape and setup them using various
Designer tools.
To simplify creation of certain object components (queries, templates and print
routines, register records and generation of objects based on other objects),
the Designer has various wizards – auxiliary tools that facilitate the design process
(for details see page 2-937).
For the object types that can have forms, the system has form wizards – auxiliary
tools that facilitate development of object forms. The  form wizard launches when
you create a  new form (for more on how the form wizard works see page 2-987).
You can use the form editor to edit forms (for more on how it  works see page
2-937).
You can edit spreadsheet-based templates with the spreadsheet editor (see page
2-996). To generate templates, you can use the print wizard (see page 2-982) and
the report generator (see page 2-979).
You can edit text-based templates with the text editor (see page 2-957).
You can edit programs in  the 1C:Enterprise script located in  modules with the text
editor (see page 2-943).
You can create a  new object by clicking and dragging. When you drag and drop an
object (either within its branch or outside it), you create a  new object. The  possible
use of the object original properties in the resulting object is checked.
1-52 1C:Enterprise 8.3. Developer Guide

If the resulting object supports the properties, they are copied. An example of

a  successful copy would be carrying attributes and catalog templates over into the
document. When you copy the same catalog to a  Style-type object, only its name,
synonym and comments are carried over.
If the original object contains subordinate objects (attributes, forms, templates, etc.),
then dragging it  to a  similar level (for example, dragging the Catalog.Curren-
cies object to the Documents branch) copies its attributes, forms, templates and
tabular sections. However, some properties of component parts may be changed
(for example, a  document may lack the Parent property).

2.8.2. Deletion of Configuration Objects

To delete a configuration object, select it in the configuration tree and use
Actions  – Delete in the Configuration window. If no other configuration objects
reference this object, it  is  deleted.
If the object is  referenced (i.e. is  in  use), the following message appears: Object
cannot be deleted, because other objects contain links to it! The  message window
also displays a  list of the object uses.
Fig. 4 below shows an example of the message window after an attempt to delete
the GoodsReceipt document.

Fig. 4.  Service Messages

To navigate to the object referencing the object you wish to delete, double-click its
name in  the message window.

2.8.3. References to Configuration Objects

From the standpoint of interconnection, configuration objects are divided into
non-referenced objects (for example, the Purchase Price attribute with the Number
type) and referenced objects (for example, the Unit of Measure attribute in the
Nomenclature catalog which references the Units of Measure catalog).
It is  often useful to know which configuration objects reference the object in  ques-
tion or which objects are associated with it. You can find it  out by using commands
Actions – Find references to object and Actions – Find References in  Object in  the
Configuration window.
It displays a  dialog box.
Chapter 2. Work with Configuration 1-53

Fig. 5.  References to Object

You need to specify the search area (properties, subordinate objects) and click OK.
If references exist, they will be listed in  the message window when you execute the
command. If there are no references, one of the following warnings is  displayed:
„„ There are no references to this object.
„„ Reference not found in  object.
Use Actions  – Find References in  Object to display a  list of all aggregate types
used in  the object.
To follow a  link, double-click the corresponding line containing the name of the
referenced object in  the message window.

2.9. PROPERTIES PALETTE

The process of editing a  configuration object consists of changing its properties
in  order to achieve the desired behavior when the object is  used.
The properties palette is  a window in  the form of a  set of properties that can be
defined for the configuration object. The  list of properties depends on the type of
object being edited.
This section describes basic techniques for working with the properties palette.
To open the properties palette, point to the configuration object and select Edit  –
Properties.
Object properties are grouped in  the properties palette by category. The  number
of categories and the properties included in  each category depend on the type of
object being viewed. For example, the properties palette for a  document attribute
only contains property categories General, Use and Presentation. The  list of prop-
erties in  a category also depends on the type of object. Even if you select identical
object types, the list of properties is  determined by the individual settings of the
specific objects. For example, for a  hierarchical catalog, the list of properties of
a  table box in  the Use category includes additional properties: Tree, Hierarchical
View and others.
Properties also depend on values chosen for other properties. For example, when
you select the Number primitive type, properties that characterize the selected type
are added to the Type property: Length, Precision and Non-negative.
1-54 1C:Enterprise 8.3. Developer Guide

The properties palette toolbar has five buttons (see fig. 6). The  first three buttons
manage how properties are displayed.

Fig. 6.  Buttons in  Properties Window

The toolbar buttons are described below:

„„ Sort alphabetically. When selected, it lists object properties in alphabetical
order. Categories are not displayed.
„„ Sort by category. When selected, it  lists object properties by category.
„„ Show only important elements. When this button is selected, only important
object properties are displayed; when it  is  not, all properties are shown.
„„ Cancel edit. It  discards changes to property text field.
„„ Save. It  writes changes to property text field.
Categories of properties can be arranged into tabs or lists. When properties are
arranged in  a list, they can be sorted by category or alphabetically (category names
are not displayed).
To select a category display method (select the Sort by categories button to
enable category display), open the context menu anywhere in the properties
palette window and select the appropriate display method (Tabs or List). If Tabs
is selected as the display method, the buttons Sort alphabetically and Sort by
categories become unavailable.
If you want to navigate to another category with the Tabs display method selected,
click the corresponding tab.
To display categories as a  list again, select List in  the context menu of the proper-
ties window.
If the selected display method is  List, object properties are arranged by category
or in  alphabetical order. To select alphabetical order, click the Sort alphabetically
button on the properties palette toolbar. All properties will be shown in alpha-
betical order.
Chapter 2. Work with Configuration 1-55

To sort by category, select the Sort by categories button on the toolbar. All  prop-
erties are grouped in categories and displayed as a list (one below another).
Category names are displayed in bold. You can control display of properties
within the category by using a  button to the left of the category name. This  button
hides or displays a  set of properties.
Double-clicking the name of a  property category collapses all other categories and
shows properties of the selected category.
If you select the Show only important elements button, only important (main) prop-
erties of the object are displayed (regardless of whether the display is  set to list or
tabs, categories or alphabetical order). To view all properties, press the Show only
important elements button again.
Object properties are available or unavailable for editing depending on its type. For
example, in  a text document, object properties are designed only to show the number
of lines and characters and the document status, but they are not available for editing.
Each property in the properties palette has a name and detailed explanation.
The detailed description can be viewed using the Comment command of the
context menu which can be displayed by clicking anywhere in the properties
palette (outside text boxes). If this mode is  set and you select a  property, detailed
explanation appears in  the lower part of the properties palette. In  addition to the
explanation, the name of the property may be displayed for access to the value from
the program module.
Properties accessible via the 1C:Enterprise script can be displayed either as descrip-
tions or as property names, e.g. a  property with the Value type description has the
ValueType name. Display mode can be changed using the Display property names
command in the context menu. Property names are displayed according to the
selected option of the 1C:Enterprise script.
IMPORTANT!
Names of properties for metadata objects and the Configuration metadata object
are not displayed.
The way you enter values in  the properties palette depends on the type of property
you are editing.

Fig. 7.  Available Actions

1-56 1C:Enterprise 8.3. Developer Guide

You can enter text for text attributes in  the usual way (using the clipboard) or select
check boxes by clicking. For some properties, values are selected from lists. Fields
of such properties have a  selection list button (see fig. 7). If a  property field has
a  selection button (see fig. 7), clicking it  opens a  window where you can select
a  value for the property (or view it  if editing is  not permitted, for example, for
objects that are not locked in  the configuration repository or for objects that are
supported without possibility of change). Such properties include, for example,
picture file selection, color definition and others.
The view button (see fig. 7) has various functions: for text data, it opens the
window for editing strings in various languages; for events, it calls the form
module procedure that handles a  particular event; for properties from the Presen-
tation category, it  calls the existing data object form. The  clear button (see fig. 7)
clears the value of the specified property. The  spin button (see fig. 7) increases or
decreases a  numeric value by 1.
Fields can also have combinations of buttons.
When you begin editing any text field in the properties palette, the properties
palette toolbar buttons Cancel Editing (see fig. 6) and Save (see fig. 6) become
available. Clicking the Cancel Editing button discards any changes you have made.
Clicking the Save button saves the changes.
The properties palette may contain links that open various forms associated with
the selected object. These may include, for example, displaying help content
(description) for a  configuration object, various forms or form module procedures.
These links are underlined. Clicking the link opens the associated window.
If you view properties of an object that you cannot edit (for example, if the object
is  not locked in  the configuration repository (see page 2-1088), you can open the
type editing dialog box as read only.

2.10. MORE WINDOW

To make viewing and setting basic interface properties of a  configuration object
more convenient, you can use the More window. To open it, select Edit – More.
To view the properties, just select the desired object in  the Configuration window.
Its properties immediately appear in  the More window.
Information in  the window is  organized on tabs.
You can include metadata objects into subsystems regardless of their mutual subor-
dination. An object can belong to both a  parent subsystem and its subordinates.
Use the Subsystems tab to do this (see fig. 8).
The Rights tab shows a list of roles and the rights of each role relative to
a  particular object (see fig. 9).
Chapter 2. Work with Configuration 1-57

Fig. 8.  Subsystems tab

Fig. 9.  Rights Tab

The Data Access Restrictions table box allows you to edit data access restrictions at
the level of individual fields and records (for details see page 1-188).
The Functional options tab lists functional options existing in  the system. You can
select the functional options bound to a  particular metadata object.

Fig. 10.  Functional Options Tab

1-58 1C:Enterprise 8.3. Developer Guide

The Common attributes tab can be used to specify to which common attributes the
current object belongs. The  editing rules in  this window are similar to those in  the
Content window of a  general attribute property.

Fig. 11.  Common Attributes Tab

The Exchange plans tab shows a list of exchange plans. The exchange plans
where changes for a  particular object are recorded are marked in  the list.

Fig. 12.  Exchange Plans Tab

The Command interface tab can be used to edit visibility of standard and custom
commands for the selected metadata object in various subsystems. Commands
included in  the desktop are grouped in  the Desktop node.

Fig. 13.  Command Interface Tab

The Enter based on tab shows a  list of objects used as a  basis to create a  particular
object and a  list of objects serving as a  basis for exchange plans.
Chapter 2. Work with Configuration 1-59

Fig. 14.  Enter Based On Tab

The Only selected check box can be used to display selected objects only or all
objects that can be input on a  certain basis with selected objects marked by check
boxes.
The Delivery settings tab can be used to select a  distribution rule for the configu-
ration object selected, similar to the special distribution configuration dialog (see
page 2-1122).

Fig. 15.  Distribution Configuration Tab

2.11. OBJECT EDITING WINDOW

For basic configuration objects (catalogs, documents, document journals, etc.),
it  is  easy to edit properties, add or delete subordinate objects and objects interac-
tion setup using the object editing window.
In most cases you can open the object editing window by selecting Actions  –
Change in  the Configuration window.
Editable properties are organized on several tabs. Each tab contains a  set of attrib-
utes for customizing properties of a  particular type of object. Thus, the Main tab
allows you to enter Name, Synonym and Comment properties, while the Subsys-
tems tab helps specify which subsystems use the object. You can navigate through
the tabs using the Next > and < Back buttons. You can also select the desired tab
with the mouse. This  window contains the Actions button. Clicking it  displays the
object context menu. You can use this menu to open the desired form or object
module (if any), call the desired wizard and perform other actions.
1-60 1C:Enterprise 8.3. Developer Guide

Available tabs and a  set of controls on similar tabs can vary depending on the type
of configuration object.
For example, for a  Catalog object, the editing window looks like the following:

Fig. 16.  Main Tab

The Main tab allows you to specify Name, Synonym and Comment properties.
Additionally this tab is used to set properties that create an object presentation
in  the command interface (for details see page 1-250).
On the Subsystems tab, you can specify which subsystems use the object. You are
allowed to include the object into subsystems regardless of their mutual subordina-
tion. The  object can belong to both a  parent subsystem and its subordinates. Object
membership in  subsystems defines where in  the command interface commands for
the edited object are displayed. For details on the command interface see page 1-83.
The Data tab can be used to create attributes, resources, dimensions, tabular sections
and tabular section attributes as well as other subordinate objects (depending on the
object type). This  tab can also contain other controls for setting up properties that
are characteristic of particular object types.
Thus, for a  catalog, its description and code length, code type and default presenta-
tion of catalog items is  defined (see fig. 17).
Use buttons on the toolbar located above the lists of subordinate objects to add,
delete and sort these objects. Specify properties of subordinate objects in  the prop-
erties palette.
If you open the editing window for an object that you cannot edit (for example,
if the object is  not locked in  the configuration repository (see page 2-1088)), you
can open the type editing dialog box as read-only.
Chapter 2. Work with Configuration 1-61

Fig. 17.  Data Tab

The Forms tab is  used to manage object forms and to select default forms.

Fig. 18.  Forms Tab

For details on default and additional forms see page 1-263.

The Input by string property group defines object attributes used in  the system to
search for information. For details on input by string see page 1-258.
1-62 1C:Enterprise 8.3. Developer Guide

The Quick choice property controls the default selection mode. For details on how
this property works see page 1-274.
The Commands tab can be used to set custom commands associated with the
object. For a  description of command types see page 1-338.
Adding a  new form launches the form wizard that can be used to select a  form type,
attributes placed in  the form and the form structure. For details on how the form
wizard works see page 2-987. For the main form editing methods see page 2-937.
The Templates tab is  used to handle object templates.
Adding a  new template launches the template wizard that helps create templates.
For details on how the template wizard works see page 2-990.
Below the list of templates is  the Wizards button. Clicking it  opens a  submenu
where you can select the type of wizard (wizard availability depends on the object
type).
„„ Selecting Print Design Wizard launches the print wizard that is  used to create
a print template and routine. For details on how the print wizard works see
page 2-982.
„„ Selecting Output Form Wizard launches the output (report) form wizard.
On the Rights tab, define rights relative to a  particular object for each role.
For application objects (catalogs, documents, charts of characteristic types, charts
charts of accounts, charts charts of calculation types, registers, business processes
and tasks), the Data exchange tab specifies a  list of ExchangePlan objects. Mark
the exchange plans that will record changes to the object you are editing.
The Other tab contains buttons that open an object module, manager module or
help content and can also contain the Predefined button that opens a  list of prede-
fined object items (for catalogs, charts of characteristic types, charts of accounts
and charts of calculation types). The  tab can also contain lock control attributes
(see page 1-516) and full text search settings (see page 2-835). These attributes are
only displayed for the following application objects:
„„ catalogs
„„ documents
„„ charts of characteristic types
„„ charts of accounts
„„ charts of calculation types
„„ registers
„„ business processes
„„ tasks
Some objects may contain special tabs associated with this object type only.
„„ Catalog type objects may have Hierarchy, Owners and Numbering tabs;
„„ Document objects may have Numbering, Posting, Journals and Sequences tabs;
Chapter 2. Work with Configuration 1-63

„„ ChartOfCharacteristicTypes objects may have Hierarchy tab;

„„ ChartOfCalculationTypes objects may have Calculation and Generation
tabs;
„„ ChartOfAccounts objects may have Extra dimensions tab;
„„ CalculationRegister objects may have Recalculations tab;
„„ Task objects may have Addressing tab;
„„ all registers may have Recorders tab;
„„ objects that can have their changes recorded in  exchange plans may have Data
exchange tab.

2.12. CREATE HELP CONTENT SECTION

Some configuration objects allow you to "pin" text explaining the object purpose
and use. This  text is  called user description. When working in  the 1C:Enterprise
system, the user can display this description for viewing.
You can create and edit user descriptions in  the built-in HTML editor which can
be opened from the object properties palette via the Open link of the Help Content
property. You can create and edit description text using HTML editor tools. To
specify a  name, create a  top-level title in  the topic text using the <H1> tag of the
markup language.
Please note that the <STYLE> tag (and its contents) that can be specified when
the reference information tag is  edited manually outside of the <BODY> tag will
be ignored if the reference text is  displayed in  1C:Enterprise mode. Should any
special formatting be used for the reference information page, it  should be defined
within the <BODY> tag.
If you set the Include in  Help Contents property, object synonym is  used as a  help
topic. Regardless of this property, the object synonym line is  added to the index
list (for help search purposes).

2.13. WORK WITH DATABASE CONFIGURATION

2.13.1. Database Configuration Object Tree
To view the tree structure of the database configuration, properties, forms,
templates and other information about objects, you can open the database
configuration window. To do so, select Configuration  – Database Configuration  –
Open Database Configuration. It looks just like the Configuration window (see
fig. 19).
You work with database configuration objects the same way as you do in the
Configuration window, with one exception: all objects are read-only.
1-64 1C:Enterprise 8.3. Developer Guide

Fig. 19.  Database Configuration

2.13.2. Update of Database Configuration

As you edit the configuration, you can create new objects, modify or delete the
existing ones. The current structure of the database can differ from that of the
configuration. Differences in  the two configurations are represented by <!> charac-
ters in  the title of the Configuration window.
NOTE
The configuration difference mark (<!>) appears only after you have saved changes
to the master configuration. However, after saving the master configuration, you
can continue making changes; in  that case the title of the Configuration window
will contain signs of modification of both configurations.
To align the configuration and the database configuration, you should update the
database configuration. To do so, select Configuration – Update Database Configu-
ration. If the master configuration has not yet been saved, the Designer first saves
it  and then updates the database configuration.
If the message window has opened in  the database configuration update process,
it is cleared.
IMPORTANT!
Updating the database configuration may require terminating all user sessions.
Before updating you can compare or merge configurations.
If debugging is  run during the updating the database configuration, after saving
the current configuration the system prompts: To update the database configura-
tion you need to stop debugging. Do you want to continue? Select Yes to terminate
Chapter 2. Work with Configuration 1-65

debugging and update the database configuration. Select No to discard the update
and continue debugging.
To update the database configuration, the Designer requires exclusive access to
the infobase. Depending on whether there are users working with the database and
what mode they use, the system may behave in  different ways:
„„ The Designer displays an exclusive lock error message in  the following cases:
○○ The file mode of the database is  in  use.
○○ Some sessions are connected to the infobase without using the Web Server.
○○ No sessions are connected through the Web Server.
○○ Updating the configuration requires database restructuring.
„„ The Designer prompts to terminate all sessions and re-try updating in the
following cases:
○○ Updating the configuration requires database restructuring.
○○ The file mode version of the infobase is  used by web clients and thin clients
connected via the Web Server.
„„ In all other cases the Designer prompts the user to perform a  dynamic update.
NOTE 1
Troubleshooting messages contain characteristics of the sessions preventing the
system from performing the requested action. If the number of these sessions does
not exceed 5, a  detailed list of sessions is  displayed (with the machine name,
application type, etc.); otherwise the total number of sessions is  only displayed.
NOTE 2
Infobase operation in  the exclusive mode does not switch the Microsoft SQL
Server database to the single user mode.
NOTE 3
To speed up infobase restructuring, it  is  recommended to set the database recov-
ery mode to the Simple or Bulk logged values when Microsoft SQL Server DBMS
is  used. The  mode can be changed either before the restructuring operation or on
an ongoing basis if it  is  not necessary to restore the database at an arbitrary point
of time. Before changing the database recovery mode, back up the database.

Exclusive Access Error

If the system cannot gain exclusive access to the infobase, you can wait until all
users disconnect from the infobase and retry the update operation.

Fig. 20.  Exclusive Lock Error

1-66 1C:Enterprise 8.3. Developer Guide

Session Termination and Update Attempt

If updating the configuration requires terminating all sessions, the user will see the
following message (see fig. 21).

Fig. 21.  Session Termination for Update

If Close sessions and repeat is selected, the user is prompted to confirm the
selection action (Closing sessions will result in  abnormal termination of all infobase
users’ work! Do you want to close sessions?). If the action is  confirmed, the system
attempts to terminate all infobase sessions. Then the system retries to save the data-
base configuration.
Terminating all sessions shuts down all client applications.
In some situations sessions cannot be terminated. In  this case you can either retry
to update the database configuration later or terminate sessions by other methods
(e.g., by reloading the working processes).

Dynamic Update
If dynamic update is allowed, the user will see a corresponding message (see
fig. 22).

Fig. 22.  Dynamic Update

Select the Dynamic update command to perform an update without interrupting user
operations. In  this case changes you make are saved dynamically as a  version of
configuration changes (the database configuration remains unchanged). Repeated
changes to the master configuration are allowed. If during the next database
Chapter 2. Work with Configuration 1-67

configuration update you can enable the exclusive mode, the Designer will perform
the database configuration update and include all the changes (both current and
previous).
NOTE
If the client/server mode of the infobase is  used, then the Designer is  restarted
after the update. All unsaved changes in  text, spreadsheet and other documents
will be lost.
In case of dynamic update active users continue to work with the previous
configuration. To access the updated configuration, the user should restart the
1C:Enterprise system. For the purposes of control and user notification about
dynamic changes, use the DataBaseConfigurationChangedDynamically()
global context method.
NOTE
After the database configuration is  updated all other versions created by dynamic
updates are removed.
If changes requiring database restructuring are found, a  dialog box with a  list of
these changes is  displayed so that you can confirm that the update should go ahead.

Fig. 23.  Reorganizing Information

Click Accept to save the changes or Cancel to discard.

2.13.3. Background Database Configuration Update

2.13.3.1. General information
It can take a  long time to perform a  database configuration update connected with
database restructuring for large volume infobases. The  infobase will be unavailable
during the update.
To minimize the time spent on this operation, you can use a special mode that
allows the background database configuration update. The background database
configuration update incorporates the following features:
„„ It is  available only in  the client/server mode of infobase.
1-68 1C:Enterprise 8.3. Developer Guide

„„ It can be performed with Designer closed.

„„ The greater part of the background database configuration update is  performed
without exclusive access to the database (including the period of database
restructuring).
„„ The background database configuration update makes the following operations
unavailable:
○○ Configuration editing;
○○ Application debugging;
○○ Database configuration update operations;
○○ The SetAggregatesMode(), SetAggregatesUsing(), RebuildAggre-
gatesUsing() methods are not allowed;
○○ Changing a  chart of accounts or chart of calculation types if the relevant
accounting register or calculation register is involved in the background
update. An attempt to change the content of the chart of accounts or chart of
calculation types will lead to an error.
„„ The background configuration update can be paused for up to 48 hours. If the
pause exceeds 48 hours, the background configuration update will be cancelled.
„„ The background update is not supported for configurations in the mode of
compatibility with version 8.1 (see page 1-170).
„„ The background database configuration update is not supported when IBM
DB2 9.1 is  run.
The background database configuration update consists of a  number of phases:
„„ Processing phase:
○○ This phase takes long time.
○○ The phase can be started by any of the following methods:
□□ interactively from Designer;
□□ from 1C:Enterprise script (using appropriate methods);
□□ from Designer startup batch mode.
○○ Users can use the infobase during this phase.
○○ The main volume of data is restructured for the following configuration
objects:
□□ Catalogs
□□ Documents
□□ Document journals
□□ Information registers
□□ Accumulation registers
□□ Accounting registers
□□ Calculation registers
□□ Sequences
Chapter 2. Work with Configuration 1-69

□□ Charts of accounts
□□ Business processes
□□ Tasks
○○ In the processing phase, the system records all data changes for the above
objects by analogy with a  data exchange mechanism.
„„ Refreshing phase:
○○ This starts automatically with a  1-minute interval after the processing phase
finishes.
○○ Users can work with the infobase during this phase.
○○ The phase comprises automatically repeated iterations. Each iteration
analyzes the changes accumulated since the previous iteration (or since the
processing phase finished) and performs restructuring of the data.
○○ Iterations are completed at the moment the next phase starts.
„„ Change acceptance phase:
○○ This phase requires exclusive access to the infobase.
○○ Users cannot use the infobase in  this phase.
○○ The first step here is  refreshing any data accumulated since the most recent
iteration of the refreshing phase.
○○ Then the system performs restructuring of data that were not involved
in processing and refreshing operations during the respective phases.
Changes to this data are not significant, thus their restructuring does not take
very long.
○○ The next step is  acceptance of all changes made in  the database.
○○ The database configuration update process is  then complete.
If the background update is  run in  such a  way that it  does not require database
restructuring, the entire update process is  executed at the change acceptance phase,
which begins just after the background update is  launched.
During the background update, the server operation can be stopped or the back-
ground update process can be paused.
After the server is  stopped or the working process supporting the system’s back-
ground update job is aborted, the creation of the first session will require a bit
more time than usual. This  occurs due to background update recovery. However,
the background update process itself is  suspended. To proceed, you need to restart
the background update execution. This behavior is implemented to prevent the
system looping in the event that the abnormal end of the working process that
supports the background update was caused by this background update itself.
After the server operation is recovered, the background database configuration
update proceeds as follows:
„„ If the operation has been terminated at the processing phase, the process
resumes from the most recent configuration object whose processing has not
been completed.
1-70 1C:Enterprise 8.3. Developer Guide

„„ If the operation has been terminated at the refreshing phase, any iteration that
has not been completed will resume.
TIP
We recommend canceling any background database configuration update process
already started if you do not plan to complete the background database configu-
ration update (e.g. if the process is  put on an "infinite pause"). Following this
recommendation will be positive for the system characteristics as no change
registration will be performed to execute the refreshing phase.
When executing background restructuring, please note the following features of the
system’s operation:
„„ If the accumulation register or accounting register is  part of a  separator, then
the register is  processed during the change acceptance phase.
„„ If the type of an independent separator has been changed (see page 2-895), all
the objects included in  this separator are processed during the change accept-
ance phase.
„„ If the dimension type included in  the main filter of an independent information
register is  changed, the register will be processed during the change acceptance
phase.

2.13.3.2. Background database configuration update dialog

To call the background database configuration update operation, select the Configu-
ration – Database Configuration – Background database configuration update menu
item.

Fig. 24.  Background Database Configuration Update

Chapter 2. Work with Configuration 1-71

Clicking the Run button will launch the Processing Phase. When you do this, the
service message window will display the following:

Background database configuration update has started successfully.

The configuration is  not available for editing. Background database configuration update is  being executed.

After the background update has been started, the configuration becomes locked
against changes. The  background update operation can be paused at any phase by
clicking the Pause button. Click the Continue button to go on with the background
update process.
The processing phase is  followed by the refreshing phase, during which you can
move the system to the change acceptance phase by clicking Finish or choose not to
update by clicking the Cancel button.
TIP
We recommend canceling the background database configuration update process
already started if you do not plan to complete the background database configu-
ration update (e.g. if the process is  put on an "infinite pause"). Following this
recommendation will be positive for the system characteristics as no change
registration will be performed to execute the refreshing phase.
The Allow dynamic update check box is used to define whether the system
should try to execute a  dynamic update instead of starting the background data-
base configuration update process after the Run button is  clicked. If this option
is  checked, then once the Run button is  clicked, the system will verify whether the
dynamic configuration update can be performed. If the configuration allows this,
the background database configuration update will be replaced with a dynamic
update.
The Update on the server check box is  used to define where the process will be
launched, completed or canceled. The  above commands will be executed in  the
client application if this option is  unchecked, or on the 1C:Enterprise server side
if checked. In  addition, if the option is  checked, the configuration can be updated
even if you have only the DataBaseConfigurationUpdate right, setting the
Administration right is  not obligatory.

2.13.4. Saving Database Configuration to File

To save the database configuration to a  file on disk, select Configuration  – Data-
base Configuration  – Save Database Configuration to File. The standard file
selection dialog box is  displayed. Choose a  directory and specify the file name to
save the database configuration.
You will need the saved configuration file if you want to compare or merge
configurations (see page 2-1071).
1-72 1C:Enterprise 8.3. Developer Guide

2.13.5. Comparison of Configuration and Database

Configuration
If you are making changes to the configuration and want to create a  report on how
it is different from the database configuration, select Configuration  – Database
Configuration – Compare and Merge with Database Configuration.
If necessary, you can restore the changed objects.

2.13.6. Cancellation of Configuration Changes

To discard changes to the configuration, just select Configuration  – Database
Configuration – Return to Database Configuration.
NOTE
Even when the edited configuration is  closed, Save Database Configuration to File …
and Return to Database Configuration menu items are available. When the infobase
is  connected to the configuration repository, the Return to Database Configuration
command remains inaccessible.

2.14. 1C:ENTERPRISE LAUNCH

You can run the 1C:Enterprise mode from the Designer. To do so, select Tools –
1C:Enterprise. You might frequently need to start 1C:Enterprise in debugging
mode. Use the Debug  – Start Debugging command to do so (for details on the
debugger see page 2-1033).
If the configuration has been modified (if changes have been made), the Designer
displays the following message: Configuration being edited differs from database
configuration. Update database configuration? To save your changes, click Yes.
If you click No, the 1C:Enterprise mode is  launched without saving the configura-
tion.
If you refuse to save the configuration, the following prompt is  displayed: Data-
base configuration does not match stored configuration. Continue? If you click OK,
the 1C:Enterprise mode is  launched with the previous database configuration. If
you click Cancel, the 1C:Enterprise mode is  not launched.

2.15. DOWNLOAD/UPLOAD OF CONFIGURATION FILES

The mechanism of downloading/uploading configuration files allows you to down-
load and upload selected properties of configuration objects (modules, templates
and help content). To download properties, select Configuration – Dump configura-
tion files.
Chapter 2. Work with Configuration 1-73

Fig. 25.  Downloading Configuration Files

In the window that appears, check configuration objects to be downloaded, specify

the type of downloaded data and choose a  directory to download into. To run this
utility click the Execute button. Downloaded data are written into files with the same
names as the downloaded properties. The  file extensions depend on the data types.
„„ htm – for help content and HTML document templates
„„ txt – for modules and text document templates
„„ mxl – for spreadsheet document templates
„„ geo – for geographical schema templates
„„ bin – for binary data templates
Pictures are downloaded in  the format in  which they are stored in  the configura-
tion. Pictures of all supported formats can be downloaded (see page 1-230).
To download/upload access rights you need to select the roles required (or all of
them) and check the Rights item in  the Process list. Access rights are downloaded
in XML format. The files downloaded will include the access right itself, data
access restrictions and access restriction templates.
When help files and HTML document templates are downloaded, a  separate file
is generated for every language, for which the layout is defined. The language
code is included in the file name before the extension, for example Document.
ConsumptionOfProduct.Help.en.htm is  an English help file for the Consumption-
OfProduct document.
1-74 1C:Enterprise 8.3. Developer Guide

To download the properties, select Configuration  – Load configuration files.

The  actions in  this window are similar to data downloading actions.
When data are downloaded, an attempt to download help files and HTML docu-
ment layouts is  made for every language defined in  the application. If only one
file (without the language code in  the file name) is  found, it  will be downloaded
for the current configuration language.
To upload data, select Configuration  – Load Configuration Files. Actions in this
window are similar to data downloading actions.

2.16. CONFIGURATION DUMP AND RESTORATION

This feature allows you to dump all configuration objects into xml files and restore
them. All the configuration objects are dumped into one or more files. The  main
file for the dump is  Configuration.xml. It  contains a  description of the configura-
tion properties.
The following is  dumped into separate files:
„„ Configuration objects, i.e. top level objects, as well as subordinate objects that
are held separately in  the configuration repository.
File name examples:
○○ Document.GoodsSales.xml – a  description of the Document.GoodsSales
configuration object.
○○ CommonPicture.SubsystemPurchasing.xml – a  description of the Common-
Picture.SubsystemPurchasing configuration object (but not the picture
itself).
„„ Individual properties – generally these are properties that have a  large volume
or a  complex structure.
File name examples:
○○ CommonPicture.SubsystemPurchasing.Picture.xml – a picture description
(but not the picture itself).
○○ DataProcessor.Guidebook.Template.HomePage.xml – a description of the
template being processed (but not the template itself).
„„ Individual property values that are files of known formats (other than XML).
These include form modules, templates, and pictures.
File name examples:
○○ CommonPicture.SubsystemPurchasing.Picture.Picture.png – a  picture
saved to common pictures with the SubsystemPurchasing name.
○○ Catalog.Goods.Form.ItemForm.Form.Module.txt – a  managed module of the
Goods catalogue item form.
○○ DataProcessor.AssistantOfDataExchangeCreation.Form.Form.Form.
SecondInformationBasePicture.Picture.png – an absolute picture in the
Picture property of the SecondInformationBasePicture item of the
managed form.
Chapter 2. Work with Configuration 1-75

Objects other than development objects are saved to parent object files, e.g. the
DataProcessor.PrintLabelsAndTags.Template.BarcodePrintingComponentLinux32.
Template.bin file means the external component of label and tag printing that
is located in the BarcodePrintingComponentLinux32 binary template.
The following items are dumped in  a particular way:
„„ Object module – it  is  dumped as a  text file (if any) or in  the binary form.
File name example:
○○ DataProcessor.EventLog.ObjectModule.txt – the Processing.EventLog
metadata object module.
„„ HTML – it  is  dumped as a  set of files: a  property root file, HTML page files,
picture files (if any). The root file contains a list of HTML pages included
in the document. HTML files are pages included in the document. Each of
these corresponds to a  specific language defined in  the configuration. Configu-
ration Object Help represents a  particular instance of HTML dump.
File name examples (for the Help property):
○○ Catalog.Goods.Help.xml – a root file of the external help property of the
Catalog.Goods metadata object.
○○ Catalog.Goods.Help.ru.html, Catalog.Goods.Help.en.html – help pages for
the Russian and English versions respectively.
○○ Catalog.Goods.Help.Picture.png – a picture file in the HTML document
with help.
„„ Vendors' configurations – these are damped as a  file with the information on
vendors' configurations in  an external format (other than XML) and configura-
tion files (.cf) for each vendor's configuration.
File name examples:
○○ Configuration.ParentConfigurations – a  file with the information on vendors'
configurations.
○○ Configuration.ParentConfigurations.TradeManagement.cf – the vendor's
configuration TradeManagement.
All references to metadata objects as well as references to fields, type identi-
fiers, etc. are dumped as names (Catalog.Goods). All identifiers are dumped
in  English – a  reference to the Goods catalog will appear as Catalog.Goods.
Should configuration objects contain references to absent configuration objects,
such references are dumped as identifier text views and are restored in  a reference
to the absent configuration object at loading (to keep these two configurations iden-
tical). Internal identifiers are dumped for attributes and managed form elements.
These identifiers are used to save and restore settings, among other things.
When roles are dumped, the system dumps only the values of those rights that are
different from the default values at the moment of dumping. When default rights
values are defined, the following role properties are used: Set rights for new objects
1-76 1C:Enterprise 8.3. Developer Guide

and Set rights for attributes and tabular sections by default. The  values of these
options are default options for access rights to configuration objects and access
rights to attributes and tabular sections, respectively.
NOTE
Ordinary forms and interfaces of ordinary applications are dumped in binary
form.
If any errors are identified in  files when they are being restored, the system will
generate a  window containing the list of errors. Where errors are not critical, you
can click Accept. Selecting a  line with an error will open the file with the error.

2.17. WORKING WITH A  MOBILE APPLICATION

For information on working with a  mobile application, see page 2-917.

2.18. CONFIGURATION REPORT

The Designer lets you output data on all configuration objects in  text or spread-
sheet form. To do this, select Configuration – Configuration Report.
It displays a  dialog box in  which you must select the type (text or spreadsheet) and
name of the file where description of the configuration structure will be saved.

Fig. 26.  Configuration Report

Creating descriptions of configuration objects for complex configurations can take

a  long time.
If you need a  report on specific configuration objects, press the selection button
in the Objects field and select the required check boxes in the object selection
dialog box (see fig. 27).
You are allowed to select objects by subsystems.
After you have finished creating the configuration description, a window
containing the description in  the selected format (text or spreadsheet) will open.
Chapter 2. Work with Configuration 1-77

Fig. 27.  Object Selection for Configuration Report

2.19. GLOBAL SEARCH AND REPLACEMENT

Global search and replace mode is  used to find a  specific string in  all modules,
dialog boxes, spreadsheets, configuration descriptions and external files (external
reports, data processors and spreadsheets). Once found, the text can be replaced.
This mode can be used, for example, to find all calls of a global procedure or
references to an attribute in  various modules.
You can invoke the search mode by selecting Edit – Global search and the replace
mode by selecting Edit – Global replace.
Both modes use the same dialog box. If the search mode is  selected, attributes of
the replace mode become unavailable. To make the description shorter, we will
examine the global replace procedure and then point out specifics of the search
mode.
A dialog box appears for you to set search parameters.

Fig. 28.  Global Replace Window

1-78 1C:Enterprise 8.3. Developer Guide

In the Find what field of the dialog box, enter a  search string or select one of the
strings used in  previous search operations.
In the Replace field, enter replacement text or select one of the strings used
in  previous replace operations.
To make the search case-sensitive, select the Match case check box. If you select
Find whole words only, the system only finds whole words rather than their parts.
If you do not want to open editors in  a global replace operation (using the Replace
all button), select Silent global replace (do not open editors). The  editor will open
regardless of this check box setting if you click Find or Replace.
Below is  a panel with tabs where you can specify objects where the string should
be searched.
On the Text types tab, you can mark types of subordinate objects to be searched.
If the configuration is  editable for the Managed application run mode (see page
2-1148), user interfaces will be excluded from the object list.
On the Configurations tab, you can specify precisely, down to the object, configura-
tion sections to be searched.

Fig. 29.  Global Search

In addition to the master configuration, the list of configurations also includes the
database configuration and the repository configuration. The  repository configura-
tion must be open before you start the search or replace mode.
Chapter 2. Work with Configuration 1-79

To specify a  set of objects, select the Selected objects toggle and check the objects
to be searched. The  first time you run the search, all objects in  the list are checked
by default. To clear the setting, uncheck the box for the line with the configuration
name. Then you can specify particular objects to be searched.
On the Files tab, you can specify directory and file types to be searched. You
can view the following types of viewable files: configurations in files (saved
configurations and distribution files), external reports and data processors, text
and spreadsheet documents. If no directory is  specified (the Directories attribute
is  blank), the system does not search in  files. You can also search open documents
of the same types. To do so, check Search in  open documents.
You can save the selected group of settings for further use. To do so, specify the
setting name in  the Search scope field. To use the previous setting, simply select
the setting name from a  dropdown list. The  following settings are saved: settings
on the Text types tab, the object structure for the main configuration on the Configu-
rations tab, and the settings from the Files tab. If the search mode has been started,
press the Find button to begin the search.
You can interrupt global search by pressing Ctrl + Break.
A list of matches found for the source text is displayed in the Search results
window.

Fig. 30.  Global Search Results

If a  module has restricted access (see page 2-956), the system requests an access
password before searching for the source text in  that module. You must enter the
correct password or refuse to enter the password. If you do not enter the password,
this module is  skipped.
You can view search results and go to each occurrence found by selecting the
desired line in  the search results and pressing Enter. To view the next or previous
occurrence, you can use the following menu items: Actions  – Next item and
Actions – Previous item.
You can copy search results (the entire list) to the clipboard using the Copy
command of the context menu or clicking the corresponding button on the toolbar
of the search results window; you can also export the results to a  text or spread-
sheet document.
1-80 1C:Enterprise 8.3. Developer Guide

You can change the column width by using a standard method: dragging the
column border while holding down the Ctrl key.
If the replace mode has been started, use the Replace box to enter the text string
that will substitute the source text specified in  the Find what box.
If you need to view the source text before replacement, click the Ignore button to
begin the search. The  first found occurrence of the source text will appear on the
screen. If you click Ignore, the current text is  skipped and the next occurrence of
the source text is  displayed in  the current window or another window containing
the source text.
If in  case of global replace you do not need to open objects in  which the source
text is  found, check Silent global replace (do not open editors).
IMPORTANT!
While viewing search results, you cannot change search criteria.
The selected search area (types of text, list of configuration objects, files and open
documents) is  saved and restored the next time you open the dialog box. If you
need to save several areas, you need to give each a name in the Search scope
attribute. When you reopen the search window, you just have to select the area you
need from the list and perform your search.

2.20. CUSTOMIZATION OF DESIGNER WORK SPACE

To create and edit a  configuration, you must simultaneously use various windows.
For example, configuration objects are viewed, selected, added and deleted in  the
Configuration window, properties of objects and their components are edited in  the
properties palette, help on the 1C:Enterprise script is  accessed in  the Syntax Assis-
tant window, and messages and search results are viewed in  the message window.
In  addition, each configuration object can generally consist of various parts, each
of which is  edited in  a separate window.
Simultaneously opening various service windows noticeably reduces the work
space available for editing application objects (forms, modules and templates) and
editing shared configuration objects (application module and common modules,
templates, styles, interfaces, etc.).
To expand the work space and make your work more convenient, you can use
several recommendations on customizing various panels of the Designer, on the
display and behavior of various service windows and on the use of window display
modes.
Chapter 2. Work with Configuration 1-81

2.20.1. Panel Customization

The Designer is intended for maximum use of work space by automatically
selecting the needed toolbars for each window type. Thus, when editing a  spread-
sheet the Designer offers a  toolbar with spreadsheet editing commands, but when
you switch to a window containing a form module, the Designer closes the
spreadsheet toolbar and shows the text editor toolbar.
The user can customize the contents of toolbars and their placement on the screen.
If non-default commands are included in  the command bar during setup, the order
of these commands on the command bar may change once Designer is  restarted.
In that event, a standard bar shall be hidden. Instead, we recommend that you
create an additional command bar and place the required commands in the
preferred order. The  order of these commands will not change.
In addition to toolbars, the Designer has Window Bar and Status Bar at the bottom.
Each of these occupies a  separate line and cannot be moved. If any of the bars
is  not needed, it  can be hidden using the context menu from anywhere in  any bar.
A bar is  shown if the check box to the left of its name is  selected and is  hidden if
the box is  cleared. To change the bar display mode, just select the line with the bar
name in  the context menu.
If you do not want the window bar to always occupy a  part of the program work
space, you can set the Autohide mode. While you are working, the window bar
is  hidden. You can display it  by placing the cursor over the bar location.

2.20.2. Configuration Window

You can open and close the Configuration window at any time. After selecting
all the windows you need, you can close the Configuration window. Closing the
window does not end your session with the configuration. You can open it  at any
time.
The initial state of the Configuration window is  Docked. In  this state it  "overlaps"
all windows in  MDI state (most windows are displayed in  this state). To use the
area occupied by the Configuration window, you can change its status to MDI (in
this case other windows are displayed above the Configuration window) or Auto-
hide (if the window is  not needed, it  hides automatically and reappears if you put
mouse over it).

2.20.3. Use of Window Display Modes

In MDI mode, a  window can be placed (it is  visible) only within the available work
space of the Designer. Using other modes enables you to expand the work space or
use it  more efficiently. In  addition, you can "send" a  window outside the bounda-
ries of the work space.
1-82 1C:Enterprise 8.3. Developer Guide

Every window in  the Designer (except the Calculator) can be switched to Autohide
mode. This  mode allows you to select the desired window for viewing and editing
simply by moving the cursor to the window title bar. When you are done viewing
it, you can minimize the window simply by moving the cursor to any other window
or to the title bar of an autohiding window. It's good to use this mode with windows
you need briefly (Syntax Assistant, the Configuration window, message and search
results window and windows of application objects, spreadsheet and text docu-
ments which you open mainly for viewing).
The Floating window state lets you place any window anywhere on the screen,
regardless of the size and position of the program (Designer) window.
In the Docked mode, a  window can be docked to another window in  this state,
to one of the sides of the Designer window or above another dockable window
(stacked windows).
We recommend combining windows that you do not need to view simultaneously.
For example, the properties palette window and the Syntax Assistant window or
Immediate window and Call Stack during debugging.
For details on window display modes see page 2-1143.
Chapter  3

APPLICATION INTERFACE

The application interface is  oriented for a  better user experience and designed in  a
such way that users work with different forms when they perform necessary actions
in  the application. You can open any form using different methods, as is  described
later in  this manual.
To get access to a  form you need to find a  corresponding command (open list,
generate report, enter document, etc.) in the application interface and run it.
The  process of searching for a  command is  called application navigation.
The structure of the application solution in the managed application represents
a  hierarchy formed by subsystems and their metadata objects (see page 1-173).
Forms with which users work
can be displayed using different
methods:
„„ A start page
„„ A separate window
„„ A separate tab
„„ A single-window mode, i.e.
the Taxi interface
The form opening mode (in
separate windows or tabs)
is  defined by the client applica-
tion setting and is  effective after
the client application has been
restarted.

Fig. 31.  Setting the form

opening mode
1-84 1C:Enterprise 8.3. Developer Guide

This setting is  configured in  the client application option setting dialog available
via the Main Menu – Tools – Options command.
When the required display option is  selected, the system prompts the user to restart
the application.

Fig. 32.  Restart confirmation box in  the options dialog

When the Restart button is  pressed, the application is  restarted and opened again
using the selected display option.
There are two types of windows in  1C:Enterprise:
„„ main window
„„ auxiliary window
Each window type in 1C:Enterprise is used to perform certain tasks. The main
application window is  used to navigate through the application solution and run
various commands. The auxiliary window is used to work with the infobase
objects (such as documents or catalog items), build reports and run data proces-
sors. The  auxiliary window role can be performed by a  tab displayed in  the main
window's work area.

3.1. OPEN FORMS IN  SEPARATE WINDOWS

In this mode, forms are opened in  auxiliary windows. Each 1C:Enterprise window
appears on the OS task bar and at the window toggle when pressing Alt + Tab
keys.

3.1.1. Main Application Window

When you work in  1C:Enterprise, you can use a  single main application window
only. Its structure makes user navigation throughout the application more efficient,
i.e. allows the user to find the required sections and commands faster (see fig. 33).
Each status of the main window can be considered a  distinctive work space. For
example, when moving to the Stocks section, the user will see a  set of commands
for performing the most frequent actions related to stock management.
Chapter 3. Application Interface 1-85

Fig. 33.  Structure of Main Application Window

3.1.1.1. Sections Panel

The sections panel displays a list of top-level subsystems allowing to quickly
switch between them. Each section corresponds to a subsystem (e.g., Sales,
Purchases or Inventory). Visualization can be improved by assigning an easy-to-
understand picture to each subsystem. Subsystems are displayed in the sections
panel even if they have no pictures. The first section is always the main one,
named Dashboard. The  dashboard contains the most relevant and frequently used
tools of the application solution.
Other sections correspond to subsystems of the first hierarchy level.
You can scroll through the sections panel horizontally, but you can also avoid
scrolling altogether by limiting the set of partitions using access rights.
NOTE
If the sections panel has no sections (they are unavailable or hidden by the user),
it  hides automatically and the main application window navigates to the configu-
ration desktop.
1-86 1C:Enterprise 8.3. Developer Guide

3.1.1.2. Navigation Panel

The navigation panel displays the configuration structure according to the sections
selected in  the sections panel. If a  subsystem has subordinate subsystems, they are
displayed as minimizable groups. Hereinafter, subsystems that are subordinate to
top-level subsystems are referred to as subsections.
Clicking hyperlinks on this panel generally opens list forms. Forms are opened
directly in  the main window replacing each other.
Clicking a hyperlink opens a form in the work space of the main application
window.
The navigation panel can contain three standard groups of commands: Important,
Normal and See also. Commands in  the Important group are displayed in  bold.
If a  group does not exist, it  is  skipped. The  configuration developer can define
custom groups of commands in  the Navigation panel category. These are placed
before the See also group (it is  always the last to be displayed in  the navigation
panel).
The following rules also apply to displaying the See also group:
„„ Commands of the See also group from the displayed section and all of its
subsections are placed into a  single See also list.
„„ Commands are displayed in  the same order as sections and subsections custom-
ized during configuration.
„„ Commands within sections and subsections are displayed in the order set
during configuration.
The order of sections (top-level subsystems), subsections (subordinate subsystems)
and commands in the See also group of the navigation panel can be modified
in  the editor of command interface fragment.

3.1.1.3. Actions Panel

The actions panel contains commands corresponding to the section currently
selected in  the sections panel. These commands are divided into standard groups
(Create, Reports and Tools) and groups created by the developer.
The Create group contains commands for creating new infobase objects, such as
documents and catalog items. This group covers commands used to create all
objects that are part of a subsystem; however, by default these commands are
hidden. The  developer can display the most frequently used commands of object
creation. The  Reports group contains commands for opening reports, and the Tools
group includes commands for opening data processors. If any of the groups has
no commands, it  is  not displayed. The  configuration developer can define custom
groups of commands in  the Actions panel category. These are displayed below the
Tools group.
Chapter 3. Application Interface 1-87

The following rules also apply to displaying groups in  the Actions Panel:
„„ Commands of identical groups from the displayed section and all of its subsec-
tions are placed into a  single list.
„„ Commands are displayed in  the same order as sections and subsections custom-
ized during configuration.
„„ Commands within sections and subsections are displayed in the order set
during configuration.
The order of sections (top-level subsystems), subsections (subordinate subsys-
tems) and commands in  the groups of the Actions Panel can be modified in  the
command interface editor.
By default height of the Actions Panel is defined by the number of commands
in  the groups and does not exceed three lines when set automatically. The  user
can, however, customize the height using the separator below the panel. If
the Actions Panel of the current height cannot accommodate all commands of
a  particular group, the bottom right corner of the group contains an icon that opens
a  menu with all commands of the group.

3.1.1.4. Information Panel

The information panel is used to open the latest data edited by the user and
to display a list of the latest notifications (information about system actions).
For details see page 1-349.

3.1.1.5. System Commands Area

The system commands area can be used to perform actions that do not depend on
the applied specifics of the configura-
tion, but help manage the system.
Additionally this area contains
various commands facilitating use of
windows.

Fig. 34.  System Commands Area:

Left-Hand Part
1-88 1C:Enterprise 8.3. Developer Guide

The left-hand part of the system commands area contains a  button that opens the
main menu and commands used to switch between navigation points and user
favorites menus. Navigation point is  a fragment of the main application window
interface. You can navigate to the fragment by using commands in  the main appli-
cation window.
In 1C:Enterprise, favorites are a  list of links selected by the user for fast navigation
to the selected configuration sections, navigation points, infobase object forms or
report and data processor forms.
You can manage the favorites list programmatically. To do so, use the
UserWorkFavorites object. You can retrieve it  from the system settings storage.
NOTE
When working with favorites, please remember that the favorites list has one level
only.
You cannot add a  link to a  standard function (opened by selecting Main Menu – All
functions – Standard) to the favorites list.

The system commands area in  auxiliary windows has a  different look (see page
1-90).
The right-hand part of the system commands area contains auxiliary commands
that facilitate use of windows. You can set up the list of commands using a  special
settings menu.

3.1.2. Auxiliary Window

Auxiliary windows are used to perform actions rather than navigate throughout the
entire application. For example, document or catalog item forms as well as report
and data processor forms are opened in  these windows (see fig. 35).
Closing an auxiliary window does not close the application.
You can open any number of auxiliary windows, but each infobase object (such as
a  document or catalog item) has only one auxiliary window, i.e. you cannot open
multiple windows for viewing the same document unless this is  specified in  the
configuration.
You can identify a  default form for an auxiliary window. This  form appears by
default when you open the auxiliary window or click the first link in  the form navi-
gation panel. Clicking other links in the form navigation panel opens auxiliary
forms.
Chapter 3. Application Interface 1-89

Fig. 35.  Structure of Auxiliary Application Window

3.1.2.1. Form Navigation Panel

The navigation panel of an auxiliary window (the form navigation panel) can be
used to view any information logically associated with the data displayed in  the
default window form.
The navigation panel can hold three groups of commands: Important, Go to and
See also. Commands in  the Important and Go to groups will be united by a  single
header, Go to, and the Important group commands will be shown first highlighted
in  bold font and separated from the other commands located under the Go to header
by a  small indent. A group will be skipped if it  does not exist. A configuration
developer can define custom groups of commands in  the form Navigation panel
category. These are placed above the See also group (it is  always the last to be
displayed in  the form navigation panel).
You are able to go back to the default form. To do this, click the hyperlink in  the
top of the navigation panel (highlighted with bold font).
1-90 1C:Enterprise 8.3. Developer Guide

3.1.2.2. Form Command Bar

Form command bar contains commands directly linked to an object displayed
in  the default form. Apart from standard groups (Important and Generate), the bar
can also include groups created by the developer. Each command in  the Important
group is  displayed as a  separate button in  the bar. The  Generate group appears as
a  bar submenu. All command groups created by the developer are also displayed as
submenus. Form commands, such as Write and close, are placed above the Impor-
tant commands.
If any of the groups has no commands, it  is  not displayed. If the configuration
developer adds custom groups to the area, these are placed below the Generate
group.

3.1.2.3. System Commands Area

The left-hand part of the system commands area in an auxiliary window only
contains a button that opens the main menu and commands used to work with
favorites. The  right-hand part contains auxiliary commands that facilitate use of
windows (e.g., commands that retrieve and click links, open calculator or calendar,
etc.). The  right-hand part of the area can be customized using a  special menu.

3.2. OPEN FORMS IN  TABS

In this mode, forms are opened as main window work area tabs. Some forms are
still opened in  separate windows (e.g., the selection window), but these windows
are not displayed in  the taskbar.
A form opened in  a tab can be opened in  an auxiliary window if this is  required
by the work logic. In  this case, the auxiliary window will be displayed in  the
operating system taskbar and will be available when you switch windows with
Alt + Tab.

3.2.1. The Main Application Window

When you work in 1C:Enterprise, you can use the main application window
only. The structure of the main window makes user navigation throughout the
application more efficient, i.e., it  allows a  user to find the required sections and
commands more quickly.
Each status of the main window can be considered a  distinctive work area. For
example, when moving to the Finances section, the user will see a  set of commands
for performing the most frequent actions related to stock management.
You can close any tab shown in the main window work area (including the
Desktop tab). You can do this using the context menu (the Close command) or by
clicking the blue picture at the right side of every tab.
Chapter 3. Application Interface 1-91

Fig. 36.  Main window with tabs

NOTE
The Desktop tab is  always shown first.
You can open any tab (except the Desktop tab) in  an auxiliary window. To do this
you need to run the Open in  new window command in  the tab's context menu.
The tab header changes its size according to the number of tabs in  the main menu.
When the number of tabs increases, the tab header size decreases and the header
may become unreadable. In  this case you will need to use a  special button to the
right of the tabs to get a  list of the tabs opened (see fig. 37).
If a  blocking form (such as the selection form) is  opened in  a form which was
opened in a tab, this form is not shown as a separate tab and is not included
in  the window list in  the taskbar. This  form blocks only contents of the tab where
the blocking form was opened. You can still switch between tabs. If you switch to
a  tab with an opened blocking form, it  will be shown on the screen.
1-92 1C:Enterprise 8.3. Developer Guide

Fig. 37.  Tab list

3.2.1.1. The Sections Panel

The Sections panel displays a list of top-level subsystems which allow you to
switch between them quickly. Each section corresponds to a subsystem (e.g.,
Sales, Purchases, Inventory). Visibility can be improved by assigning a  recogniz-
able image to each subsystem. Subsystems are displayed in the Sections panel,
even if they do not have any images assigned. The  Desktop is  always displayed
as the first section. The  Desktop contains the most relevant and frequently used
tools of the application solution. Other sections correspond to subsystems of the
first hierarchy level.
You can scroll through the Sections panel horizontally, but you can also avoid
scrolling altogether by limiting the set of sections using access rights.
The information shown in  the work area is  not changed as you navigate through
the sections. However, the navigation and action panel content is changed
(see fig. 38).
NOTE
If the Sections panel has no sections (i.e., if they are unavailable or hidden by the
user), it  hides automatically, and the main application window will navigate the
configuration desktop.
Chapter 3. Application Interface 1-93

Fig. 38.  Subsystem switching and work area

3.2.1.2. The Navigation Panel

The navigation panel displays the configuration structure according to the sections
selected in  the sections panel. If the subsystem has subordinate subsystems, they
will be displayed as groups that can be minimized. Hereinafter, subsystems that are
subordinate to top-level subsystems are referred to as subsections.
If you click on the hyperlinks on this panel, list forms will generally be opened. Forms
are opened directly in  the main window, replacing one another as they are opened.
A form opens in  the work area of the main application window when you click on
a hyperlink.
The navigation panel can contain three standard groups of commands: Important,
Normal and See also. Commands in  the Important group are highlighted with bold
font. A group is  skipped if it  does not exist. A configuration developer can define
custom groups of commands in  the Navigation panel category. These are placed
before the See also group (this is  always the last to be displayed in  the navigation
panel).
The following rules also apply to displaying the See also group:
„„ Commands of the See also group from the displayed section and all of its
subsections are placed into a  single See also list;
1-94 1C:Enterprise 8.3. Developer Guide

„„ Commands are displayed in  the same order as sections and subsections custom-
ized during configuration;
„„ Commands within sections and subsections are displayed in the order set
during configuration.
The order of sections (top-level subsystems), subsections (subordinate subsystems)
and commands in the See also group of the navigation panel can be modified
in  the editor of the command interface fragment.

3.2.1.3. The Actions Panel

The Actions panel contains commands corresponding to the section currently
selected in  the sections panel. These commands are divided into standard groups
(Create, Reports and Tools) and groups created by the developer.
The Create group contains commands for creating new infobase objects such as
documents and catalog items. This group contains commands used to create all
the objects that are part of a subsystem; however, by default these commands
are hidden. The developer can display the most frequently used commands for
the creation of new objects. The  Reports group contains commands for opening
reports, and the Tools group includes commands for opening data processors. If
any of the groups has no commands, it  will not be displayed. The  configuration
developer can define custom groups of commands in  the Actions panel category.
These are displayed below the Tools group.
The following rules also apply to displaying groups in  the Actions Panel:
„„ Commands of identical groups from the section displayed and all of its subsec-
tions are placed into a  single list;
„„ Commands are displayed in the same order as the sections and subsections
customized during configuration;
„„ Commands within sections and subsections are displayed in the order set
during configuration.
The order of sections (top-level subsystems), subsections (subordinate subsys-
tems) and commands in  the groups of the Actions Panel can be modified in  the
command interface editor.
By default the height of the Actions Panel is  defined by the number of commands
in  the groups and does not exceed three lines when set automatically. A user can,
however, customize the height using the separator below the panel. If the Actions
Panel of the current height cannot accommodate all the commands of a  particular
group, the bottom right corner of the group will contain an icon that will open
a  menu with all of the group's commands.

3.2.1.4. The Information Panel

The Information Panel is  used to open the most recent data edited by a  user and
to display a list of the latest notifications (information about system actions).
For details, see page 1-349.
Chapter 3. Application Interface 1-95

3.2.1.5. The System Commands Area

The System Commands Area can be used to perform actions which do not depend
on the applied specifics of the configuration and instead help to manage the system.
Additionally, this area contains various commands which facilitate the use of the
windows.

Fig. 39.  Left part of the System Commands Area

The left part of the system commands area contains a  button that opens the main
menu as well as commands for opening the function and user favorites menus.
The main menu contains the View menu, which can be used to configure the appli-
cation's window appearance.

Fig. 40.  View menu

1-96 1C:Enterprise 8.3. Developer Guide

In particular, this menu can be used to hide the Section Panel, Navigation Panel
and Actions Panel. It  will increase the space for forms and decrease the likelihood
of scrollbars being displayed. Also note the Hide all command bars command.
The Sections Panel, Navigation Panel and Actions Panel are hidden after this
command is  run.

Fig. 41.  Hiding command bars

If you run the command again, the hidden panels will be restored. You need to
remember the following: the Hide all command bars command will not work if the
Sections Panel, Navigation Panel and Actions Panel are hidden with the View menu.
To fasten and simplify access to commands of a subsystem, a special mode,
Function menu, is  used. You need to click a  special button located in  the system
command area to enter this mode (see fig. 42).
The Function menu is  a section panel with a  special form containing all commands
for the selected section. A list of sections and commands corresponds to the current
user settings. The first form column corresponds to the navigation panel, other
columns correspond to actions panel groups of the selected subsystem. Display of
a  sections panel does not depend on the state of the Main Menu – View – Sections
panel setting. Once you have selected the command you need, the window restores
its appearance to what it  was before the function menu was opened. The  list of
commands is  updated if you select another section in  the function window.
Chapter 3. Application Interface 1-97

Fig. 42.  Function menu

In 1C:Enterprise, the Favorites are a list of links selected by the user for fast
navigation to the selected configuration sections, navigation points, infobase object
forms or report and data processor forms.
You can control the Favorites list programmatically. To do so, use the
UserWorkFavorites object. You can retrieve this from the system settings storage.
NOTE
When you work with the Favorites, please remember that the Favorites list has
one level only.
You cannot add a  link to a  standard function (opened by selecting Main Menu – All
functions – Standard) in  the Favorites list.

The system commands area in the auxiliary windows has a different look (see
page 1-90).
The Window menu displays the main menu, window tabs and auxiliary windows.
The  following items are checked:
„„ the active auxiliary window
„„ the active main window tab
„„ the main menu itself, if no tab is  opened in  it.
The right side of the system commands area contains auxiliary commands which
facilitate the use of windows. You can set up the list of commands using a  special
setup menu. Command availability and composition depend on the form currently
in  the active tab.
1-98 1C:Enterprise 8.3. Developer Guide

3.2.2. The Auxiliary Window

For a  description of auxiliary windows, see page 1-88.

3.3. TAXI INTERFACE

This mode displays forms in  the working area of the main window. Some forms
are still opened in separate windows (choice windows, for instance), but these
windows are not displayed in  the tasks panel. Switching between windows using
Alt + Tab is  not supported. You can use special buttons in  the headers of all forms
that are opened in  the working area of the main window of the application in  order
to switch between open forms.

3.3.1. Main application window

Only one main application window is used when working with 1C:Enterprise.
The  main window is  laid out so that the user can effectively navigate around the
application and quickly find the sections and commands required. No forms are
opened (except for in  the working area) in  the main application window.

Fig. 43.  Main window of the Taxi interface

Chapter 3. Application Interface 1-99

The Taxi interface supports placing several different panels in  the main applica-
tion window in  any order (see page 1-106). The  work area of the main application
window displays all the forms with which a  user works. The  only exception is  the
blocking forms, which open in  separate windows. If a  blocking form (a selection
form, for instance) is  opened in  another form that has been opened in  the work
area, then that blocking form is  displayed as a  separate window but is  not shown
in a list of windows on the tasks panel. Depending on the mode for opening
windows (see page 1-396), either an owner form or the whole system interface
will be blocked. If an auxiliary window is  opened in  the blocked owner window
mode, you can still open other forms and use the command interface of the applica-
tion. When a  user switches to the form that was used to open another form which
blocked the owner, the blocking form will be displayed on the screen.
We will now review the components of the main application window in  greater
detail.

3.3.1.1. The start page

When working with the application you start at the start page.

Fig. 44.  The  start page

1-100 1C:Enterprise 8.3. Developer Guide

This is  the page where the application developer places all the forms that he or she
believes are most useful in  this application. The  availability of the forms on this page
depends on access rights and functional options. The  start page cannot be closed.
The interface of the start page is  set up with the aid of the configuration properties
(see page 1-167). Users can also customize the contents of the start page from a  list
of available forms that the application developer placed on the start page. To do
this, use a  special start page setup dialog: Main Menu – View – Start page setup.

3.3.1.2. The Sections panel

The sections panel shows a  list of upper level subsystems and facilitates the quick
selection of the required set of functions. Each section correlates with a  separate
subsystem (for instance, Sales, Purchases, Inventory). For the sake of ease of view,
each subsystem may be assigned an icon. If a  subsystem does not have an icon,
this does not affect whether or not it is displayed in the partition panel. Dash-
board is  always the first section. The  main section contains the most frequently
used tools in  the application. Other sections correlate with first level subsystems of
the hierarchy.

Fig. 45.  The  sections panel

Fundamentally, each element of the sections panel groups together system

commands that are logically related to a  specific area of work within the applica-
tion. For instance, different sections correlate with actions related to purchasing
management (Purchases section), inventory management (Inventory section), etc.
The sections panel cannot be used as a tool for switching between automated
workplaces.
The sections panel supports scrolling. The contents of the sections panel for
a  given user depend on his or her access rights and the functional options set for
the system. The  display of the available sections is  configured via Main Menu  –
View – Sections panel setup.
The action taken when a  section is  selected depends on whether the command bar
of the current section is  displayed in  the main window (see page 1-102):
„„ The panel is not displayed. In that case, if a section is selected, the screen
displays the function menu for that section. The current section is not
displayed on the screen (when the function menu is  closed).
Chapter 3. Application Interface 1-101

Fig. 46.  The  function menu is  displayed when a  section is  selected

„„ The panel is  displayed. In  that case, if a  section is  selected, the function menu
will not be opened, but the contents of the command bar of the current section
will be changed. If the displayed information is  not sufficient, you can open
the function menu by selecting the section once again. In  that case, the sections
panel always displays the current section.

Fig. 47.  The  current section command panel

The function menu contains the navigation panel and action panel commands.
A  command can be added to favorites from the functions menu. To do this, click
the star icon to the left of the command. To remove the command from favorites,
click the asterisk again.
When the function menu is opened, hyperlinks for customizing the navigation
panel (Navigation settings hyperlink) and the action panel (Action settings) for this
subsystem are displayed in  the upper right corner.
There are several ways to open the functions menu:
„„ Select a  section.
„„ Use a  toolbar command (see page 1-105).
1-102 1C:Enterprise 8.3. Developer Guide

„„ Using the keyboard:

○○ Using a  keyboard shortcut: Ctrl + Shift + T.
○○ Using a  keyboard shortcut: Alt + 2. In  this case, the cursor is  set to the first
command on the navigation panel.
○○ Using a  keyboard shortcut: Alt + 3. In  this case, the cursor is  set to the first
command on the actions panel.
NOTE
If the sections panel contains no sections (they are either unavailable or hidden by
the user), the sections panel is  automatically hidden.

3.3.1.3. The current section command panel

The current section command panel of the current section contains commands for
that section.

Fig. 48.  The  current section command panel

The command bar of the current section:

„„ Commands for the navigation panel are located at the start of the panel.
Commands for the Important group are in  bold.
If the panel is displayed horizontally, the maximum possible number of
commands is  displayed (at least one). If all the commands do not fit into the
panel, the panel displays a  More submenu that contains other commands.
If the panel is displayed vertically, it displays at least one navigation panel
command (and a  maximum of 10). If the panel contains the More menu, this
will be the 11th element of the command bar.
„„ Navigation panel commands are followed by a submenu of all non-empty
groups of navigation panel commands and action panel commands for the
selected partition.

3.3.1.4. The opened items panel

This panel contains a  list of forms opened in  the current session (see fig. 49).
The start page is always the first open form (if it is setup in the application).
The work area forms of the start page are not displayed as separate forms on
the open forms panel. Click the icon (X) in  the upper right corner of the panel’s
element to close the form displayed by the item.
Chapter 3. Application Interface 1-103

Fig. 49.  The  opened items panel

3.3.1.5. History
1C:Enterprise saves the history of the user’s actions, which can be used to quickly
access recently opened, created or edited infobase objects (documents, catalog
items, etc.). History contains navigation links to application items, ordered
according to when they were last used. The history can be displayed as either
a  history form or as a  history panel.

Fig. 50.  The  history form

List items are grouped by dates when a given application form has been used.
Moreover, the items are sorted according to the time last used, as displayed to the
right of the item.
The user’s work history is  saved in  the infobase. The  history contains a  single
record for each infobase object (a record for a subsequent change replaces the
record of the previous change to that object during a  given day). A maximum of
400 records is  stored per user. When the number of stored items reaches 400, the
oldest history events will be deleted when new items are added.
If a  history list is  very large, use the search function to simplify the search for the
required data. A special box at the top of the form can be used to enter the search
request. Press Ctrl + F to open the box or simply start typing the required text.
1-104 1C:Enterprise 8.3. Developer Guide

If the history is  displayed in  the main window panel (see page 1-106), it  will have
the following features:
„„ Items are not grouped by date, the time at which an application item is  used
is  not shown.
„„ If the panel is placed horizontally, it displays all the elements that can fit
in  that space.
„„ If the panel is  placed vertically, it  displays only the first 10 elements.
„„ Click the panel’s header (History) to open the history form.
You can also use a  toolbar command or press Ctrl + Shift + H to open the history
form.
There are several ways in  which information is  added to the user’s work history:
„„ Interactive operations (open, create, write).
„„ User notification, containing a navigation link to a specific system object,
is  displayed (the history then contains the object which is  referenced by the
navigation link). For more information on the notification mechanism, please
see page 1-350.
„„ If the user’s work history is  changed though a  program by means of a  global
context property, UserWorkHistory.
If an object is written or opened programmatically, the information about the
object is  not included in  the history.

3.3.1.6. Favorites
The favorites contains a  list of navigation links to different application elements
marked by the user as to be used frequently. Favorites can be displayed as
a  favorites form or a  favorites panel.

Fig. 51.  Favorites form

A user may select the most frequently used elements from among the added
elements. Click the icon to the left of the element to add it to the favorites.
Chapter 3. Application Interface 1-105

The  element will be in  bold, and the next time the favorites is  opened, it  will be
located in  the upper part of the panel and will not be moved. You can also rename
the element or remove it  from the list.
If a favorites list is very large, use the search function to simplify finding the
required data. A special box in  the upper part of the form can be used to enter the
search request. Press Ctrl + F to open the box or simply start typing the required text.
If the favorites is  displayed in  the main window panel (see page 1-106), the list
will have the following features:
„„ You cannot search for, rename, delete, or mark an important favorites element.
„„ If the panel is placed horizontally, it displays all the elements that can fit
in  that space.
„„ If the panel is  placed vertically, it  displays only the first 10 elements.
„„ Click the panel’s header (Favorites) to open the favorites form.
You can also use a  toolbar command or press Ctrl + Shift + B to open the favorites
form.
The favorites is  unavailable unless the user has the right to SaveUserData (see
page 2-1209).

3.3.1.7. The toolbar

The toolbar facilitates easy access to the following functions of the system:
„„ Function menu. For further information, please see page 1-95.
„„ The user’s work favorites (if the current user is assigned the right to
SaveUserData (see page 2-1209). For further details, see page 1-104.
„„ The user’s work history. For further details, see page 1-103.
„„ Full text search form (if it  is  enabled). For further details, see page 1-106.
This list corresponds to the toolbar
icons.

Fig. 52.  The  toolbar

1-106 1C:Enterprise 8.3. Developer Guide

3.3.1.8. Full text search form

The system provides a special form to be called from the toolbar in order to
perform a  full text search (see page 1-105). This  form is  only available if full text
search is  enabled.

Fig. 53.  Full text search form

The right part of the form displays the most recent queries entered by the user.
To obtain search results quickly, simply click a hyperlink that contains the
required text.
If full text search is  used, you can employ a  special language as detailed on page
2-1207.
If the application developer is  not satisfied with the system form of the full text
search, it  can be replaced via a  configuration property, Default search form (see
page 1-167).
You can also use a  toolbar command or press Ctrl + Shift + F to open the full text
search form.

3.3.1.9. The system commands area

The system commands area supports a number of activities that do not depend
on application specific configuration, but that facilitate system management.
Moreover, this area contains a  number of commands that facilitate working with
the system.

Fig. 54.  The  system commands area

Chapter 3. Application Interface 1-107

The left part of the system commands area contains a  button that opens the main
menu of the application. For instance, the main menu contains the View menu to
control the appearance of the main application window.

Fig. 55.  The  View menu

This menu is  used to customize the appearance of the sections panel, the start page,
and the panel layout. This  menu also contains a  command to hide all the panels
of the main application window (except for the toolbar). Repeat the command to
restore the hidden panels. The toolbar will be oriented as specified by the user
in  the panels editor.

Fig. 56.  Hide all panels

The right part of the system commands area contains different service commands
that simplify working with the system and do not depend on the application used,
i.e. printing commands, the commands to obtain a  navigation link and to navigate
it, etc.
1-108 1C:Enterprise 8.3. Developer Guide

3.3.1.10. Panel setup

The Taxi interface can be used to set up the display and location of different panels
in  the main application window. This  is  done via the Customize panes window.
To open the editor, use the application main menu command Main menu – View –
Pane settings.

Fig. 57.  The  panel editor

In the editor, the user can move elements of the main application window (the lower
part of the form with the grey background) to the required location with the mouse.
Elements should be moved inside the light-colored boxes with gray borders. In  this
case, the panels will be located in  different rows or columns. You can position an
element on top of the existing element. Then elements will be located in  one row
or column. The  central part of the editor displays the work area of the start page.
A panel cannot be placed here (see fig. 58).
To remove an element, move it  back from the schema to an element with a  gray
background.
Any elements except for the work area of the main application window can be
removed from the main application window. For instance, you can create a  mini-
malistic interface for the application, and the main window will only contain
a  work area, toolbars, and an open forms panel (see fig. 59).
When the Default button is  pressed, the interface will return to the state specified
by the developer via a  configuration property Client application interface (see page
1-168).
Chapter 3. Application Interface 1-109

Fig. 58.  Sample panel layout

Fig. 59.  Minimalistic interface

1-110 1C:Enterprise 8.3. Developer Guide

3.3.2. The auxiliary window

The auxiliary window is  an application window that opens forms created in  the
application. An auxiliary window may be opened in the work area of the main
application window and in  a separate window. The  mode in  which an auxiliary
window is  opened depends on the value of the Window open mode form property
(see page 1-396).

Fig. 60.  Structure of an auxiliary application window

When an auxiliary window is closed, this does not close the application. There
could be an unlimited number of auxiliary windows, but each infobase object (for
instance, a  document or a  reference element) can only have one window, i.e. you
cannot open several windows to view the same document, unless this is  specified
in  the application.
The main form, i.e. a form displayed by default when an auxiliary window
is  opened, and opened when the Main command in  the form’s navigation panel
is pressed, can be found in the auxiliary window. Clicking other links in the
form’s navigation panel opens auxiliary forms.
The buttons to control the forms are located in all the auxiliary forms.
These buttons have the following functions (from left to right):
„„ A button to navigate to the start page;
„„ Buttons to navigate to the previous/next form help to navigate through a  list of
open windows. The  button for navigating to the next form becomes active only
after the button for moving to the previous window has been pressed at least once.
Chapter 3. Application Interface 1-111

„„ A button to add the form to a list of favorites (see page 1-104). If a form
is not included in a list of favorites, the color of the asterisk matches the
background of the form. Otherwise, the asterisk is  yellow. This  button is  only
available if the user has the right to SaveUserData (see page 2-1209).

3.3.2.1. The form navigation panel

The navigation panel of the auxiliary window (form navigation panel) allows a  user
to view different information that is  logically connected to the data displayed by
the main form of the window.
The navigation panel may contain three groups of commands: Important, Go to and
See also. The  general layout of the commands is  as follows:
„„ The first command is  always the Main command (highlighted in  bold) to be
used to open the main form of the auxiliary window of the application.
„„ This is  followed by the Important group commands.
„„ These are followed by the Go to group commands.
„„ Finally there are the See also group commands. If the configuration devel-
oper defined custom command groups from the form Navigation panel
category, commands from these groups will directly precede the See also group
commands (this group’s commands are also placed at the very end of the form
navigation panel).
If the commands do not fit in  the navigation panel, the final command of the panel
is the More submenu where all the commands that are not displayed in  the visible
part of the navigation panel can be found.

3.3.2.2. The form command bar

The command bar of the form contains commands that are directly related to the
object displayed in  the main form. There are standard groups, such as Important
and Generate, and the panel could also host the groups created by the developer.
Each Important group command are displayed as a  separate button on the panel.
The  Generate group will look like the panel’s submenu. All command groups
created by the developer are also displayed as a  submenu. Form commands, such
as Write and close, are located before the Important group commands.
If there is  no command in  a group, the group is  not displayed. If a  configuration
developer added custom groups to this area, they are located after the Generate
group.
Should all the commands of the command bar not fit in  the form, then they are
placed in a special submenu, More, which is the final command on the bar.
The  only exception is  the Help button, which is  placed to the right of the More
submenu, if any reference information is  provided for the form.
1-112 1C:Enterprise 8.3. Developer Guide
Chapter  4

1C:ENTERPRISE
SCRIPT

1C:Enterprise is  a flexible configurable system that can be used to solve various
tasks in the area of enterprise automation. Description of specific configuration
algorithms is provided in the 1C:Enterprise Designer or, more specifically,
in  program modules that contain texts in  the 1C:Enterprise script.

4.1. BRIEF DESCRIPTION AND PURPOSE

OF 1C:ENTERPRISE SCRIPT
The 1C:Enterprise script is  used to specify algorithms of application task execution
(at the configuration development stage).
The 1C:Enterprise script is  a domain-specific programming language specifically
designed for both professional programmers and users. Thus, all 1C:Enterprise
script operators can be used both in  Russian and in  English in  the same source
text. This  book is  dedicated to the English language; however, Russian synonyms
of operators are also provided.
Although the 1C:Enterprise script is  relatively simple, it  has some object-oriented
features, e.g., access rules for properties and methods of special data types (docu-
ments, catalogs, etc.) which resemble properties and methods of objects used
in  other object-oriented languages. However, you cannot define special data types
using 1C:Enterprise script tools. You should use visual mode instead.
Variable types in the 1C:Enterprise script are not fixed, i.e. type of variable
depends on its value. You do not need to declare variables explicitly. You can
declare a  variable indirectly by using it  in  the left part of an assignment operator.
You can also declare variables directly using specific operators. You can use arrays,
structures, maps and other universal collections of values.
1-114 1C:Enterprise 8.3. Developer Guide

4.2. SOURCE TEXT FORMAT IN  PROGRAM MODULES

4.2.1. What is  a Program Module?
Program modules in 1C:Enterprise configuration are not independent programs
in  the usual sense, since they are only a  part of the entire configuration. A program
module is  a text in  the 1C:Enterprise script that contains procedure and function
codes with the required algorithms called by the system when needed. Therefore,
program modules have no formal borders of description like: "Begin Module" –
"End Module".
The Designer shows location of specific program modules in  configuration points
that require description of specific functioning algorithms. These algorithms should
have the form of procedures or functions called by the system in  certain predefined
situations (e.g., when the user clicks a  button in  a dialog box).
Each individual program module is  interpreted by the system as a  whole; there-
fore, all procedures and functions of a  program module are executed in  a single
context.

4.2.2. Program Module Execution Context

Each program module is  related to the rest of the configuration. This  relationship
is  referred to as module execution context.
There are two types of context:
„„ global context
„„ local context of specific module execution

4.2.2.1. Global Context

The global context is  formed by:
„„ values of global context properties and methods
„„ system enumerations and system sets of values (e.g., DialogReturnCode and
Chars)
The global context is  visible to all program modules and acts as a  source for the
common language environment of the configuration.

4.2.2.2. Local Context

The local context of a module is based on a specific task configuration point
which uses the program module. The  local context is  only visible to the specific
program module. It determines a set of objects accessible to the module along
with their methods and properties.
Chapter 4. 1C:Enterprise Script 1-115

4.2.3. Types of Program Modules

The 1C:Enterprise system has several types of program modules. Modules differ by
location and available context.

4.2.3.1. Managed Application Module

Managed application module runs automatically when a  configuration is  loaded
during 1C:Enterprise startup in  the following modes:
„„ thin client
„„ web client
„„ thick client in  the managed application mode
The managed application module is  used for processing tasks related to the end
user session (primarily for processing session start and end events). The  managed
application module is  inaccessible to procedures working on the server. We recom-
mend using it  to implement event handlers only.
Procedures and functions of the managed application module, along with its vari-
ables that have the Export keyword in  their titles, can be accessed:
„„ in non-global common client modules
„„ in client procedures and functions of a  command module
„„ in client procedures and functions of a  managed form module
The context of the managed application module makes the following accessible:
„„ part of the global context that can be executed in  a managed application
„„ exported procedures and functions of any common client modules
„„ exported procedures and functions of non-global common server modules with
the Server call property set

4.2.3.2. External Connection Module

Similar to the application module, the external connection module is located
in the root section of the configuration. It contains event handling procedures
initialized when the system starts up and closes down in  the external connection
(CОМ-connection) mode.
You can use an external connection module to declare variables as well as declare
and describe procedures and functions that are accessible to an external application.
1C:Enterprise objects accessible to external objects via COM-connection:
„„ exported variables and procedures/functions of the external connection module
„„ exported variables and procedures/functions of shared modules:
○○ including and excluding entire modules by setting common module properties
○○ including and excluding fragments of common modules with preprocessor
instructions
1-116 1C:Enterprise 8.3. Developer Guide

„„ 1C:Enterprise global context:

○○ except for the objects that are tightly linked with the client application
(TextDocument, SpreadsheetDocument)
The module is  available only in  an external connection session.
User interface is  completely unavailable in  this mode.

4.2.3.3. Session Module

Session module runs automatically when the configuration is loaded during
1C:Enterprise startup.
The session module is  used to initialize session parameters and process session-
related actions. This  common module is  always executed in  privileged mode at
the 1C:Enterprise server.
Session parameters are set in  the SessionParametersSetting() event handler.
The session module is  executed before the managed application module (external
connection module).
The session module can only contain definitions of procedures and functions.
It can use procedures from common modules of the configuration and cannot
contain exported procedures or functions.

4.2.3.4. Common Modules

Common modules reside in a separate branch of the metadata tree. The main
purpose of common modules is to contain common configuration algorithms
accessible from different modules. Common modules do not have a  variable decla-
ration area and main program area, i.e. they only contain procedural and functional
areas (see section "Program Module Structure").
You can declare and describe procedures and functions which will be available to
all configuration modules in  any common module.
For details on common modules see page 1-174.

4.2.3.5. Application Object Modules

The set of application objects has its own modules. These objects include:
„„ constant value managers
„„ catalogs
„„ documents
„„ reports
„„ data processors
„„ charts of characteristic types
„„ charts of accounts
Chapter 4. 1C:Enterprise Script 1-117

„„ charts of calculation types

„„ exchange plans
„„ business processes
„„ tasks
„„ registers
Modules reside in  the configuration branches that contain the objects. They repre-
sent object properties. Each object has its own individual module. These modules
can be used to declare variables, procedures and functions that will extend the
object context and will be available for working with the object externally using the
1C:Enterprise script.
The context of the application object module grants access to attributes, tabular
sections, methods and events of an object.

4.2.3.6. Object Manager Modules

Each application object has a manager that manages this object as a configura-
tion object. Using this manager, you can create objects and work with forms and
templates. The  manager module allows you to extend the managers' functionality
by creating procedures and functions using the 1C: Enterprise script. In  fact, this
enables you to define methods for a  configuration object (e.g., a  catalog) that refer
to the configuration object in general, rather than to a specific database object
instance.
The manager module's context consists of:
„„ Properties and methods of the global context;
„„ Export procedures and functions of global common modules, if these modules
are compiled on the server;
„„ Export procedures and functions of non-global common modules, if these
modules are compiled on the server;
„„ The local context of the module.
The manager module cannot have variables or a  module body.
If the manager module's procedures and functions are declared as exported, they are
accessible through the object's manager.
Look at a sample function description in the Contractors catalog manager
module:

Function GetReceivablesList() Export

…
EndFunction

To call this function from the application code, use the following:
Receivables = Catalog.Contractors.GetReceivablesList();
1-118 1C:Enterprise 8.3. Developer Guide

4.2.3.7. Form Modules

These modules are a  part of configuration forms (see page 1-361). Each form has
its own module. You can use these modules to declare variables, procedures and
functions that will extend form context and will be available for working with the
form externally using the 1C:Enterprise script.
The form context is  formed by:
„„ local context of the form module and attributes of the form that owns the
module;
„„ properties and methods of the ManagedForm object in  the 1C:Enterprise script;
„„ properties and methods of the form extension defined by the type of object that
has its data stored in  the main form attribute;
„„ global context, including non-global common modules and exported functions
and procedures of global common modules. It's important to match the procedure
description in  the form module (&AtClient, &AtServer, etc.) and the proper-
ties set for the common module (Client (managed application), Server, etc.);
„„ exported variables, procedures and functions of the managed application
module.

4.2.3.8. Command Modules

Command module describes actions the system performs when a  command is  called
in  the 1C:Enterprise script. The  command module can only contain descriptions of
functions and procedures. It  cannot have variables or a  module body.
The CommandProcessing() handler should always be preceded by the &AtClient
preprocessor instruction, since this is  where the command execution starts.
Context of client procedures in  the command module is  formed by the following:
„„ global context, including non-global common modules and exported functions
and procedures of global common modules. It's important to match the proce-
dure description in the form module (&AtClient, &AtServer, etc.) and the
properties set for the common module (Client (managed application), Server,
etc.);
„„ local context of the command module.
Context of server procedures in  the command module is  formed by the following:
„„ properties and methods of the global context;
„„ export procedures and functions of global common modules if these modules
are compiled on the server;
„„ non-global common modules if these modules are compiled on the server
(export methods of the modules are also available);
„„ server methods of the command module.
Chapter 4. 1C:Enterprise Script 1-119

In the command module, you can describe methods using the Export keyword.
However, you cannot use them outside the module. You cannot access commands
and accordingly their context from the 1C:Enterprise script.

4.2.4. Program Module Format

Program modules consist of the following areas:
„„ variable declaration area
„„ procedure and function area
„„ main program area
Any of these areas may be missing in  a particular module.
Variable declaration area occupies space from the beginning of the module text
down to the first Procedure or Function operator or any executable operator.
This  area may contain only variable declaration operators Var.
The procedure and function area occupies space from the first Procedure or
Function operator to any executable operator outside this area.
The main program area occupies space from the first executable operator outside
the last procedure and function area to the end of the module. This area may
contain only executable operators. The main program area is executed during
module initialization. The main program area generally contains operators that
initialize variables using specific values that should be passed before the first call
of any procedure or function in  the module.
Source text of program modules may contain operators and comments.

4.2.4.1. Comments
You can use comments to make various notes regarding module work. In  program-
ming, a  good practice is  providing a  detailed comment with algorithm description
in  the source code. In  execution mode comments are ignored. In  program module
text a  comment begins with "//" characters and ends at the end of a  string. You can
start a  comment at the beginning of a  string or write it  after an operator in  the
same string. You cannot add an operator after the comment in  the same string; you
have to finish the comment at the end of the string.
A = B; // This  is  a comment
// This is also a comment

4.2.4.2. Operator Format

All operators, except the assignment operator (A = В;) and syntactic constructs of
the 1C:Enterprise script (e.g., For, While, If), look like standard procedure calls.
Use semicolons to separate operators. End of string does not mean end of operator,
i.e. operators may freely move over several strings and continue in  another string.
1-120 1C:Enterprise 8.3. Developer Guide

You can place any number of operators in  a string if you separate them with semi-
colons.
There are two categories of operators in program modules: variable declaration
operators and executable operators.
Variable declaration operators create variable names which are used by executable
operators.
Any executable operator may have a  label that can be used by the GoTo operator.
Generally, language operator format looks like the following:
~label:Operator[(parameters)] [AddKeyWord];

Labels are special identifiers that begin with a tilde character and consist of
a  sequence of letters, digits and underscore characters. To mark an operator, you
should put a  label before it  followed with a  colon.
~label:A=В;

4.2.4.3. Names of Variables, Procedures and Functions

Variable, procedure and function names may consist of any sequence of letters,
digits and underscore characters beginning with a  letter or an underscore character.
New names cannot be the same as reserved words or names of properties that are
directly available in  the current context. Variable, procedure and function names
are not case sensitive.

4.2.4.4. Program Module Script

The 1C:Enterprise script is  bilingual. Almost all reserved words as well as names
of value types, properties, methods and events have two names: one in  Russian
and another in English. The only exception is words that cannot be translated
into Russian adequately. You can use both Russian and English names in  the same
module text without any limitations.

4.2.4.5. Case Sensitivity of Program Module Text

Names of variables, properties, methods, procedures, functions and 1C:Enterprise
script functions are not case sensitive.

4.2.4.6. Reserved Words

The following keywords are reserved and cannot be used as names for variables,
configuration object attributes and declared procedures and functions:
„„ If
Chapter 4. 1C:Enterprise Script 1-121

„„ Then
„„ ElseIf
„„ Else
„„ EndIf
„„ For
„„ Each
„„ In
„„ To
„„ While
„„ Do
„„ EndDo
„„ Procedure
„„ Function
„„ EndProcedure
„„ EndFunction
„„ Var
„„ Goto
„„ Return
„„ Continue
„„ Break
„„ And
„„ Or
„„ Not
„„ Try
„„ Except
„„ Raise
„„ EndTry
„„ New
„„ Execute
NOTE
Keyword names are not case sensitive.

4.2.5. Special Characters Used in  Source Text

Character Description
// Two slashes indicate a  comment. All text between this character and the end of the
string is  considered a  comment
| It is  only used in  string constants and indicates that this string continues the previous
string (line break)
~ Start of operator label
1-122 1C:Enterprise 8.3. Developer Guide

Character Description
: End of operator label
; Character separating operators
() Round brackets contain a  list of parameters for methods, procedures, functions and/or
wizards.
They can also be used in  1C:Enterprise script expressions
[] Square brackets can be used to call object properties based on property name string
presentation.
You can also call collection items by index or another parameter
, It separates parameters in  a list of parameters for methods, procedures, functions and/
or wizards
"" It is  used on both sides of string literals
'' It is  used on both sides of date literals
. Decimal point in  numeric literals.
A separator used to call properties and methods of 1C:Enterprise script objects
+ Addition operation.
Operation of string concatenation
- Subtraction operation
* Multiplication operation
/ Division operation
% It retrieves a  remainder in  division. Fractional values are permitted for a  dividend and
a  divisor
> Greater logical operation
>= Greater or equal to logical operation
< Less logical operation
<= Less or equal to logical operation
= Assignment operation
Equal to logical operation
<> Not equal to logical operation

4.3. PRIMITIVE DATA TYPES

The 1C:Enterprise script supports a  set of primitive data types. You can use literal
constants for most primitive data types in  module text, i.e. directly specify values
of a  certain type in  the module.

// Example of using String type literal constant

A = "My String";

// Example of using Boolean type literal constant

B = True;

// Example of using Number type literal constant

В = 12345.6789;
Chapter 4. 1C:Enterprise Script 1-123

NULL
Description:
Values of this type are used only to specify a  missing value for a  database,
e.g., for joining tables.
Literal constants:
NULL

Boolean
Description:
Values of this type may have two values – True and False specified by corre-
sponding literal constants. Values of this type result from evaluation of logical
expressions.
Note:
Comparison operations of the 1C:Enterprise script use logical expressions.
It  means that you do not have to write the following in  a comparison expression:
If MyVariable = True Then

EndIf;

You can write the following:

If MyVariable Then

EndIf;

Literal constants:
„„ True
„„ False

Date
Description:
Values of this type contain date (AD, from January 01, 0001) and time with
accuracy up to one second.
Literal constants:
A string of digits enclosed in single quotation marks with a format of
'YYYYMMDDhhmmss', where:
„„ YYYY – four digits of a  year (including age and millennium)
„„ MM – two digits of a  month
1-124 1C:Enterprise 8.3. Developer Guide

„„ DD – two digits of a  date

„„ hh – two digits of an hour (in 24-hour format)
„„ mm – two digits of a  minute
„„ ss – two digits of a  second
In the 1C:Enterprise script, Date literal constants should contain year, month
and day values. To specify the initial date, use '00010101'. You can omit the
last characters (seconds, minutes, hours, etc.) in  Date type literal constants.
If not specified, these values are set to 0 (for time) and 1 (for date).
Various separators are allowed in  date literal constants.
Example:
Date('2008.03.23 10:45:23') = "23.03.2008 10:45:23"

Number
Description:
Any decimal number can be represented by numerical type. For numerical
types, the main arithmetic operations are defined: addition, subtraction, multi-
plication and division.
IMPORTANT!
A number cannot have more than 32 digits.

Literal constants:
A set of digits written directly in  the source code, with the following syntax:
[+|-]{0|1|2|3|4|5|6|7|8|9}[.{0|1|2|3|4|5|6|7|8|9}]
A period is  used to separate the whole and fractional parts.
Example:
A = 15;
B = -968.612;

String

Description:
Values of this type contain a  string of arbitrary length in  Unicode format.
Literal constants:
String type literal constants are sets of values in double quotation marks.
To use the " character (double quotation mark) in a string, use two double
quotes in  a row ("").
Chapter 4. 1C:Enterprise Script 1-125

Besides, you can use string constants that occupy several lines. To specify
a  multi-line constant in  the source text, you can use one of two methods:
„„ There should be no other characters except spaces, line breaks and comment
lines between fragments that represent separate lines of a  multi-line string.
„„ Each part of a  multi-line string does not end with a  quotation mark, but all
lines end in  a | character (vertical line). In  this case comments are allowed
if the string starts with the comment sign, //.
Example:
// Sample string
MyString = "This is  a correct string";

// Sample multi-line string 1

MyMultiLineString = "This
|is a  correct
|multi-line
|string";

// Sample multi-line string 2

MyMultiLineString = "This is  also" // This  is  a comment
"a correct"
"multi-line"
"string";

// Sample string 3 with quotation marks

CompanyName = """Cornflower""Inc";

Displaying or printing the CompanyName line (sample string 3) results in  the
following:
"Cornflower" Inc

Undefined
Description:
This type of value is  used when you need an empty value that does not belong
to any other type. For example, this is  the initial value received by composite
type attributes. There is only one possible value for this type specified by
a  literal value.
Literal constants:
Undefined

Type
Description:
Values of this type are used to identify value types. This  is  required for type
definition and comparison. This  type has no literal constants and is  returned by
TypeOf and Type functions of the 1C:Enterprise script (see below).
1-126 1C:Enterprise 8.3. Developer Guide

4.4. ASSIGNMENT OPERATOR

Assignment Operator (=)
Description:
The assignment operator (= character) indicates assignment of <Source> value
to <Assignment> variable.
Syntax:
<Assignment> = <Source>;

Parameters:
<Assignment>
Any writable variable or property of 1C:Enterprise script object may act as an
assignment.
<Source>
An expression with a  value that needs to be assigned.
Example:
A = В;
Page1 = "777";
DocumentDate = '20020717';

4.5. SCRIPT EXPRESSIONS

An expression is  a mathematical, logical or string formula consisting of operations
that calculate a  value. Mathematical and logical expressions may be located to the
right of the equality sign in  assignment operators or may be a  parameter of proce-
dures or functions. Logical expressions can also be conditions in  If, While and
For control directives. Expressions consist of constants, variables and functions
linked with symbols of logical and/or arithmetic operations.

4.5.1. Arithmetic Operations

The following types of arithmetic operations are defined in  the 1C:Enterprise script:
Name Expression
Addition (Op1 + Op2)
Subtraction (Op1 – Op2)
Multiplication (Op1 * Op2)
Division (Op1 / Op2)
Remainder in  Division (Op1 % Op2)
Unary minus (-Op1)
Chapter 4. 1C:Enterprise Script 1-127

Arithmetic operations have one or two operands which determine operation seman-
tics. Semantics of an operation depend on the first operand. If the second operand
type does not match the required one, the value is  converted into the required type
in  compliance with type conversion rules. If the type of the first operand does not
match any of the valid types, depending on situation, types may be converted or an
execution error may occur.
Operation Description of Action
Addition is  defined for the Number + Number
following operand types Date + Number (number of seconds is  added to the date)
Subtraction is  defined for the Number - Number
following operand types Date - Number (number of seconds is  subtracted from the date)
Date - Date (result is  the difference between two dates in  seconds)
Multiplication Number * Number
Division Number / Number
Remainder in  Division Number % Number

4.5.2. Concatenation Operation

You can use the concatenation operation (+) to attach one string to another. Length
of the resulting string equals the total length of the strings attached. If the data type
of the second or subsequent operands does not correspond to the string type, their
value is  converted to the string type in  accordance with type conversion rules.
NAME = Last Name + " " + Name + " " + Middle Name;

4.5.3. Logical Operations

A logical operation compares operands and creates a  Boolean value: True or
False. There are two types of logical operations: comparison operations and
Boolean operations. You can use comparison operations to compare two values.
Boolean operations are used for Boolean values and implement Boolean algebra.
Boolean operation characters may combine forming compound operations.
Comparison operations:
The following comparison operations are defined in  the 1C:Enterprise script:
Operation Operation Expression
Greater Op1 > Op2
Greater or Equal Op1 >= Op2
Equal Op1 = Op2
Not Equal Op1 <> Op2
Less Op1 < Op2
Less or Equal Op1 <= Op2
1-128 1C:Enterprise 8.3. Developer Guide

Comparison operations are defined for the following operand types:

Operation Operation Expression
Greater Number > Number
String > String
Date > Date
Greater or Equal Number >= Number
String >= String
Date >= Date
Less Number < Number
String < String
Date < Date
Less or Equal Number <= Number
String <= String
Date <= Date
Equal Any type = Any type
Not Equal Any type <> Any type

Boolean operations:
The following types of Boolean operations are defined in the 1C:Enterprise
script:
AND Conjunction (Boolean AND)
OR Disjunction (Boolean OR)
NOT Logical negation (Boolean negation NOT)

Logical expressions are calculated from left to right. Use round brackets to
avoid ambiguity and manage operand sequence.
Logical operation seniority levels:
Level 1 operands in  round brackets
Level 2 NOT
Level 3 AND
Level 4 OR

NOTE
When a  logical expression is  calculated, only its required parts are used. For
example, if Price <= 0 in  the expression (Price > 0) AND CheckSum(), then
CheckSum() function is  not called.

4.6. OPERATORS AND SYNTACTIC CONSTRUCTS

? (Calculate Conditional Expression)
Description:
You can use it  to calculate one of two specified expressions depending on the
logical expression result.
Chapter 4. 1C:Enterprise Script 1-129

Syntax:
?(<Logical expression>, <Expression 1>, <Expression 2>)

Parameters:
<Logical expression>
The evaluated logical expression that defines which of the resulting expressions
is  calculated. If the evaluation result is  True, then <Expression 1> is  calcu-
lated. If the evaluation result is  False, then <Expression 2> is  calculated.
<Expression 1>
The resulting expression that is  calculated if the logical expression is  evaluated
as True.
<Expression 2>
The resulting expression that is  calculated if the logical expression is  evaluated
as False.
Return value:
Calculation result for one of the resulting expressions.
Example:
Status = ?(GetDiscount() > 10,"Preferred Customer", "Regular Customer");
Warning(Status);

Raise
Description:
This operator form is  used to raise a  new exception.
Syntax:
Raise <Expression>

Parameters:
<Expression>
The expression is  evaluated to a  string that is  used as exception description.
Example:
Raise "Cannot post the document";

See also:
Description of Try operator.
1-130 1C:Enterprise 8.3. Developer Guide

Execute
Description:
This operator is  used to execute a  code fragment passed as a  string value.
IMPORTANT!
It  is  not recommended to use this method to implement a  significant portion of
functionality in  application solutions.
NOTE
Executable code should not contain separate procedures or functions since the
code itself is  executed as a  procedure or a  function which uses this operator.
The  code also should not contain explicit declaration of variables.

Syntax:
Execute(<String>)
Parameters:
<String>
A string containing executable code text.
Example:
// Displays the current date in  the message window
Execute("Message(CurrentDate())");

AddHandler
Description:
It adds an event handler.
When adding an event handler a check is performed to make sure that the
number of event parameters matches the number of parameters for the method
assigned as a  handler.
Syntax:
AddHandler <Event>, <EventHandler>;

Parameters:
<Event>
The event to which the handler is  added.
The event is  set in  the <Expression>.<EventName> form where:
„„ <Expression> is any expression in the 1C:Enterprise script. It should
result in  an object with an event to which the handler is  added.
„„ <EventName> is  the event ID (name).
Chapter 4. 1C:Enterprise Script 1-131

<EventHandler>
A procedure or function that acts as event handler.
The event handler can be a method of 1C:Enterprise script object. Then
<EventHandler> is  set as <Expression>.<HandlerName> where:
„„ <Expression> is  any expression in  the 1C:Enterprise script that is  evalu-
ated to the object whose method serves as the event handler.
„„ <HandlerName> is  the event handler method name.
A procedure or function within the scope can be also set as the event handler.
In  this case the event handler is  specified using the name of this procedure or
function.
You can subscribe to events that have the same name (in COM objects) and
a  different number of parameters. To do so, you should create multiple handlers
in  the 1C:Enterprise script (each with a  unique name and the required number
of parameters); then the subscription mechanism selects a handler matching
a  particular subscription.
Example:
DataProcessor = DataProcessors.DocumentCheck.Create();
Invoice = Documents.Invoice.CreateDocument();
AddHandler Invoice.OnWrite, DataProcessor.OnWriteDocument;

msword = New COMObject("Word.Application");

AddHandler msword.DocumentChange, OnDocumentChange

Procedure OnDocumentChange()
Message("Document is  changed");
EndProcedure

Example with varying parameters:

// Handler with no parameters
Procedure EventProcessing()
EndProcedure

// Handler with a  single parameter

Procedure EventProcessing2(Parameter)
EndProcedure

// The  object can generate events both with

// and without parameters
Object = New COMObject("Test.Events");
AddHandler Object.TestEvent, EventProcessing
AddHandler Object.TestEvent, EventProcessing2
1-132 1C:Enterprise 8.3. Developer Guide

For
Description:
For operator is  used for loop-like repetition of operators within Do – EndDo
clause. Before the loop, <Expression 1> value is assigned to <Variable
Name> variable. <Variable Name> value automatically increments at each
iteration. Incremental step equals 1 for each loop. The  loop is  executed while
<Variable Name> is less or equal to <Expression 2> value. The loop
condition is  always checked at the beginning before the loop is  executed.
Syntax:
For <Variable Name> = <Expression 1> To <Expression 2> Do
// Operators
[Break;]
// Operators
[Continue;]
// Operators
EndDo;
Parameters:
<Variable Name>
An ID for a  variable (loop counter) whose value is  auto-incremented by 1 on
each iteration. It  is  the so-called loop counter.
<Expression 1>
A numeric expression that sets the initial value assigned to the loop counter at
the first iteration.
To
Syntax link for the <Expression 2> parameter.
<Expression 2>
Maximum value of the loop counter. When the <Variable Name> variable
becomes greater than <Expression 2>, execution of For operator is  stopped.
Do
Operators after the Do keyword are executed while the <Variable Name>
value is  less or equal to <Expression 2>.
// Operators
An executable operator or a  sequence of such operators.
Chapter 4. 1C:Enterprise Script 1-133

Break
It breaks loop execution at any point. After this operator is  executed, control
is  passed to the operator following the EndDo keyword.
Continue
It passes control immediately to the beginning of the loop where loop condi-
tions are evaluated and checked. Operators following this operator in  the
loop body are skipped in  this iteration.
EndDo
Keyword that denotes the end of a  loop operator structure.
Example:
// Cycling through days in  the current month
LastMonthDay = Day(MonthEnd(CurrentDate()));
For CurDay = 1 To LastMonthDay Do
State("Processing day: "+ CurDay);

// Operators for processing the next day of the month

...

EndDo;

For each
Description:
For each operator is  used for cycling through a  collection of values. Each
iteration returns a  new collection item. The  cycle is  running until all collec-
tion items are processed. You can use the Break operator to stop the cycle at
any time.
Syntax:
For each <Variable Name 1> In <Variable Name 2> Do
// Operators
[Break;]
// Operators
[Continue;]
// Operators
EndDo;
Parameters:
<Variable Name 1>
Value of the next collection item is  assigned to this variable on each cycle.
1-134 1C:Enterprise 8.3. Developer Guide

In
Syntax link for <Variable Name 2>.
<Variable Name 2>
A variable or an expression that represents a  collection. Items of this collection
are assigned to <Variable Name 1>.
Do
Operators following the Do keyword are executed until the cycle goes through
all collection items.
// Operators
An executable operator or a  sequence of such operators.
Break
It breaks loop execution at any point. After this operator is  executed, control
is  passed to the operator following the EndDo keyword.
Continue
It passes control immediately to the beginning of the loop where loop conditions
are evaluated and checked. Operators following this operator in  the loop body
are skipped in  this iteration.
EndDo
Keyword that denotes the end of a  loop operator structure.
Example:
// Cycling through lines of a  tabular section of the document.
Document = Documents.Invoice.FindByCode(12345);

// Check to see whether the required document can be found

If Not Document.IsEmpty() Then
For each ContentString from Document.Content Do
State("String: " + Document.Content.Index(ContentString)+1);
// Operators for processing the next string of the tabular section
...
EndDo;
EndIf;

If
Description:
If operator controls program execution based on a result of one or more
logical expressions. The  operator may contain any number of operator groups
within ElseIf – Then clauses.
Chapter 4. 1C:Enterprise Script 1-135

Syntax:
If <Logical Expression> Then
// Operators
[ElseIf <Logical Expression> Then]
// Operators
[Else]
// Operators
EndIf;
Parameters:
<Logical Expression>
A logical expression.
Then
Operators following Then are executed if the result of the logical expression
is  True.
// Operators
An executable operator or a  sequence of such operators.
ElseIf
A logical expression after ElseIf keyword is  evaluated only when all condi-
tions in  If and all previous ElseIf clauses are False. Operators following
ElseIf – Then are executed only when the result of the logical expression
in this ElseIf is  True.
Else
Operators following the Else keyword are executed if all previous If and
ElseIf conditions are False.
EndIf
Keyword that ends a  conditional execution structure.
Example:
If WeekDay(CurrentDate()) = 6 Then
Message("It’s Saturday.");
ElseIf WeekDay(CurrentDate()) = 7 Then
Message("It’s Sunday.");
Else
Message("It’s a  working day.");
EndIf;
1-136 1C:Enterprise 8.3. Developer Guide

New
Description:
You can use this operator to create a  value of specified type. This  operator can
be used only for types that allow creation of new values. You should use func-
tional form of the New operator (version 2) for application objects, since module
check in  the Designer has no types defined for application objects.
Syntax (version 1):
New <Type name>[(<Param 1>, ..., <Param N>)]

Parameters:
Type name
It specifies the type name for the new value.
<Param 1>, ..., <Param N>
The type name can be followed by parameters in  brackets if they are defined
in  wizards for this type. A valid number of parameters and their purpose are
specified in  object wizard descriptions.
Example:
// Creating a  three-item array.
Array = New Array(3);

Syntax (version 2):

New (<Type>[, <Wizard parameters>])

Parameters:
Type
Type name or Type value.
<Wizard parameters>
Array of wizard parameters.
Example:
ValueType = Type("StringQualifiers");
Parameters = New Array(2);
Parameters[0] = 20;
Parameters[1] = AllowedLength.Variable;
StrQualif = New(ValueType, Parameters);
Chapter 4. 1C:Enterprise Script 1-137

Goto
Description:
Unconditional control transfer to another operator of the program. It  transfers
control from one operator to another.
The scope of this operator is limited by the program module, procedure or
function; this operator cannot pass control outside the program module, proce-
dure or function.
NOTE 1
Label in  this operator should not lead to Procedure or Function operator.

NOTE 2
The operator of unconditional transfer cannot be used to pass control to operators
within the following clauses from outside: While – EndDo, For – EndDo, For
each – EndDo, If – EndIf, Try – Except – EndTry.

Syntax:
Goto <Label>;

Example:
Goto ~Label1;
...
~ Label1: Message("Transferred to label.");

Var
Description:
This operator is  used for explicit variable declaration.
Syntax:
Var <Variable name 1> [Export] [, <Variable name 2>, …];

Parameters:
<Variable name 1>[, <Variable name 2>, …]
It sets a  name or names of declared variables.
Export
An optional keyword. It means that this variable is exposed when other
modules access context of this module. This keyword should be specified
individually for each declared variable. It is meaningless in declarations of
variables for standalone procedures or functions.
1-138 1C:Enterprise 8.3. Developer Guide

Example:
// A single variable declaration example
Var А Export;
Var B;

// Example of declaring multiple variables with one operator

Var А, B Export;

Implicit variable declaration:

It is not mandatory to declare variables explicitly. A variable is declared
implicitly when it  first appears in  the left part of an assignment operator. Vari-
able type depends on the type of its value. Expressions cannot contain variables
that have not been declared, either explicitly or implicitly.
Variable scope:
The scope of variables depends on the location of their declarations in the
configuration. You can declare variables in  three scopes:
„„ Variable declaration area of the managed application program module.
These are global variables.
„„ Variable declaration area in  a module. These are module variables.
„„ Procedure or function. These are local variables.
Global variables declared with the Export keyword can be used in  executable
operators, expressions, in any procedure and function of any client program
module in  the configuration.
Module variables can be used by executable operators, expressions, any proce-
dure or function of the program module where they are declared. If they are
declared with the Export keyword, they can be accessed from other modules
through context of the module where they are declared.
Local variables are accessible only within a  procedure or function where they
are declared.
If a variable is defined as global, it can be accessed by any procedure or
function of any client program module within the configuration. If a  variable
is  defined within a  procedure or function, it  is  visible only in  this procedure
or function.
Therefore, if two variables with the same name are used in  two different proce-
dures in  a module and this name is  not defined as a  global variable, they are
two different local variables used for procedures. If a variable is defined as
global, any use of its name calls it.
The only way to create a  local variable for a  procedure that would have the
same name as a  global variable is  declaring it  explicitly using the Var oper-
ator.
Chapter 4. 1C:Enterprise Script 1-139

While
Description:
While operator is  used for cyclic repetition of operators within Do – EndDo
clause. The  cycle is  running while the logical expression is  True. The  loop
condition is  always checked at the beginning before the loop is  executed.
Syntax:
While <Logical expression> Do
// Operators
[Break;]
// Operators
[Continue;]
// Operators
EndDo;
Parameters:
<Logical expression>
A logical expression.
Do
Operators following Do are executed while the result of a  logical expression
is  True.
// Operators
An executable operator or a  sequence of such operators.
Break
It breaks loop execution at any point. After this operator is  executed, control
is  passed to the operator following the EndDo keyword.
Continue
It passes control immediately to the beginning of the loop where loop conditions
are evaluated and checked. Operators following this operator in  the loop body
are skipped in  this iteration.
EndDo
Keyword that denotes the end of a  loop operator structure.
Example:
SelectionDoc = Documents.Invoice.Select();

// Cycle through all documents

While SelectionDoc.Next() Do
1-140 1C:Enterprise 8.3. Developer Guide

// Display the Document in  the status bar

State("Processing document No." + SelectionDoc.Number);

// Operators for document processing

EndDo;

Try
Description:
Try operator manages program execution based on error (exceptional) situa-
tions and defines how these situations are handled.
Exceptions or error situations are module runtime errors. Custom exceptions are
not supported.
If a  runtime error occurs while executing a  sequence of operators, execution of
the operator causing the error stops, and control is  passed to the first operator
of the exception operator sequence. Control is  passed to the operator even if
the error was caused by an operator within a  procedure or function called from
a  Try operator. If the error occurred in  a procedure or function, it  is  termi-
nated, and its local variables are destroyed. It applies to any level of nested
calls. After the exception operator sequence is  executed, control is  passed to
the operator following the EndTry keyword. If the sequence of Try operators
is executed without errors, then the exception operator sequence is skipped,
and control is  passed to the operator following the EndTry keyword.
Try – Except – EndTry clauses can be nested. If an exception is  raised, control
is  passed to the handler where a  Try operator caused the error. If Raise oper-
ator is executed in the exception operator sequence of this handler, control
is transferred to a higher level exception handler and so on. If there is no
exception handler at a higher level, the exception is handled by the system,
and the program module is  terminated.
Built-in ErrorDescription() and ErrorInfo() functions can be useful
in  troubleshooting (see description of 1C:Enterprise script functions).
Syntax:
Try
// Try operators
Except
// Exception operators
[Raise;]
// Exception operators
EndTry;
Chapter 4. 1C:Enterprise Script 1-141

Parameters:
// Try operators
An executable operator or a  sequence of such operators.
Except
Operators following the Except keyword are executed if a  runtime error occurs
while executing a  sequence of operators.
// Exception operators
An executable operator or a  sequence of operators that process an exception.
Raise
This operator allows you to raise an exception in  cases when it  is  required to
shut down a  module and generate a  runtime error, even though the exception
has been processed. It  is  only allowed within the Except – EndTry clause.
This operator aborts exception operators and searches for an external excep-
tion handler (for nested tries). If such an exception handler is  found, control
is  passed to it. Otherwise the exception is  handled by the system, a  message
about the original error is  generated, and the module is  terminated.
EndTry
Keyword that ends the exception handling clause.
Example:
Procedure MakeInExcel()
Try
// Trying to call MS Excel
Table = New ComObject("Excel.Application");
Except
Warning(ErrorDescription());
Return;
EndTry;

// Report generation operators

...
EndProcedure

Procedure
Description:
Procedure keyword identifies the beginning of a source code area that can
be called from any point of the program module using ProcedureName()
operator with a  list of parameters (use round brackets even if no parameters
are passed). If an application module or a  common program module contains
1-142 1C:Enterprise 8.3. Developer Guide

the Export keyword in  the body of procedure description, it  means that this
procedure is  accessible from all other configuration modules.
When the Return operator is  executed, the procedure ends and returns control to
the point of call. If procedure text does not contain the Return operator, then an
implied Return operator is  executed after the last executable operator. The  end
of the procedure program area is  identified by the EndProcedure operator.
Variables declared in  the procedure body in  Local Variable Declarations area
are local variables and therefore they are only available in this procedure
(except when they are used as parameters for calling other procedures, functions
or methods).
NOTE
Procedure and EndProcedure keywords are not operators; they are operator
brackets. Therefore, they should not end with a  semicolon (this may cause mod-
ule execution errors).
Syntax:
Procedure <ProcedureName>([[Val] <Param 1> [=<DefVal>], ...
,[Val] <Param N>[=<DefVal>]])[Export]
// Local Variable Declarations;
// Operators;
...
[Return;]
// Operators;
...
EndProcedure
Parameters:
<ProcedureName>
It assigns a  procedure name.
Val
Optional keyword which specifies that the following parameter is passed
by value, i. e. changing the formal parameter value does not affect the actual
parameter passed during procedure call. If this keyword is  not specified, the
procedure parameter is  passed by reference, i. e. changing the formal parameter
value in  the procedure will change the actual parameter value.
<Param 1>, ..., <Param N>
Optional list of formal parameters separated by commas. Values of formal
parameters should correspond to values of actual parameters passed when the
procedure is  called. This  list defines a  name for each parameter as it  is  used
in  the procedure text. The  list of formal parameters can be empty.
Chapter 4. 1C:Enterprise Script 1-143

=<DefVal>
Optional setting of default parameter value. You can place parameters with
default values anywhere in  the list of formal parameters (for more details see
section "Passing Procedure and Function Parameters").
Export
Optional keyword specifying that this procedure is accessible from other
program modules.
// Local Variable Declarations
It declares local variables that can be referenced within this procedure only (see
Var operator description).
// Operators
Executable procedure operators.
Return
Optional keyword that ends the procedure and returns to the point of the
program that called the procedure. This  operator is  not required.
EndProcedure
Required keyword that identifies the end of the source text of the procedure
and ends the procedure. It  returns to the point of the program that called the
procedure.
Example:
Var Glob;

// Procedure description
Procedure MyProcedure(Par1, Par2, Par3) Export
Glob = Glob + Par1 + Par2 + Par3;
Return;
EndProcedure

Glob = 123;
MyProcedure(5, 6, 7); // Procedure call

RemoveHandler
Description:
It removes an event handler.
When removing an event handler a  check is  executed to make sure that the
number of event parameters matches the number of parameters for the method
assigned as handler.
1-144 1C:Enterprise 8.3. Developer Guide

Syntax:
RemoveHandler <Event>, <EventHandler>;

Parameters:
<Event>
An event for which the handler is  removed.
The event is  set in  the <Expression>.<EventName> form, where:
„„ <Expression> is any expression in the 1C:Enterprise script. It should
result in  an object with an event for which the handler is  removed.
„„ <EventName> is  the event ID (name).
<EventHandler>
A procedure or function that acts as the event handler.
The event handler can be a method of 1C:Enterprise script object. Then
<EventHandler> is  set as <Expression>.<HandlerName> where:
„„ <Expression> is any expression in the 1C:Enterprise script. It should
result in  an object whose method is  used as the event handler.
„„ <HandlerName> is  the method name of the event handler.
A procedure or function within the scope can be also set as the event handler.
In  this case the event handler is  specified using the name of this procedure or
function.
Example:
RemoveHandler Invoice.OnWrite, DataProcessor.OnWriteDocument;

Function
Description:
Function keyword begins an area in the source text of a function that
can be initiated from any point of the program module by specifying Func-
tionName with a  list of parameters (use round brackets, even if no parameters
are passed). If an application module or common program module contains
Export keyword in  the body of function description, it  means that this func-
tion is  accessible from all other configuration modules.
Function execution should end with the Return operator. The difference
between functions and procedures is that functions return a ReturnValue.
EndFunction operator identifies the end of the function.
You can record any function call in  the program module as a  procedure call,
i. e. it  is  allowed not to accept a  return value from a  function.
Chapter 4. 1C:Enterprise Script 1-145

If the Return keyword is not included in the function body or the module
string containing this keyword is  not executed, the function returns an Unde-
fined value.
Variables declared in  the Local Variable Declarations area of a  function body
are local for this function and are accessible only in  this function (except when
they are used as parameters for calling other procedures, functions or methods).
NOTE
Function and EndFunction keywords are not operators; they are operator
brackets. Therefore, they should not end with a  semicolon (this may cause mod-
ule execution errors).

Syntax:
Function <FunctionName>([[Val] <Param 1>[=<DefVal>], ... ,[Val]
<Param N>[=<DefVal>]])[Export]
// Local Variable Declarations;
// Operators;
...
Return <Return value>;
// Operators;
...
EndFunction
Parameters:
<FunctionName>
It assigns a  function name.
Val
Optional keyword specifying that the following parameter is  passed by value,
i.e. changing the value of the function parameter does not influence the actual
parameter that is  passed during function call. If this keyword is  not specified,
the procedure parameter is passed by reference, i. e. changing the formal
parameter value in  the procedure will change the actual parameter value.
<Param 1>, ..., <Param N>
Optional list of formal parameters separated by commas. Values of formal
parameters should correspond to values of actual parameters passed when the
function is  called. This  list defines a  name for each parameter as it  is  used
in  the function text. The  list of formal parameters can be empty.
=<DefVal>
Optional setting of default parameter value. You can place parameters with
default values anywhere in  the list of formal parameters (for more details see
section "Passing Procedure and Function Parameters").
1-146 1C:Enterprise 8.3. Developer Guide

Export
Optional keyword specifying that this function is accessible from other
program modules.
// Local Variable Declarations
It declares local variables that can be referenced in  this function (see Var oper-
ator description).
// Operators
Executable function operators.
Return <Return value>
Keyword that ends the function and returns the specified value into the caller
expression.
The return value can be any expression or variable that has a  value containing
the function call result.
EndFunction
Keyword that identifies the end of the function source text.
Example:
Var Glob;

// Function description
Function MyFunction(Par1, Par2, Par3) Export
Glob = Glob + Par1 + Par2 + Par3;
Return Glob;
EndFunction

Glob = 123;
Res = MyFunction(5, 6, 7); // Function call

4.7. MAJOR TECHNIQUES AND PRACTICES

4.7.1. Calls to Object Properties
In addition to point-based calls, the 1C:Enterprise script supports calling object
properties using strings with a  property name and [] operator (square brackets).

Object Property ([])

Description:
You can use this construct to call object properties in  a way similar to point-
based methods.
Chapter 4. 1C:Enterprise Script 1-147

Syntax:
<Object>[<Property Name>]
Parameters:
<Object>
Object with a  property being called.
<Property Name>
String type. The  name of the property to be called.

Example:
Cat = Catalogs.Nomenclature.FindByCode(SoughtCode);

// Calling catalog name using a  string with the property name

A = Cat["Name"];

// Calling catalog name using the property name

A = Cat.Name;

// Both property calls are identical

4.7.2. Enhancement of Object and Form Context

When you call objects and forms from external program modules, you can call
module variables, procedures and functions, just as you call properties and methods
of objects and forms. You can call variables, procedures and functions declared
with the Export keyword. You can also call form attributes (for forms).
Example:
// Example of using procedure of printing documents from a  document
// journal. Assume you have several documents,
// each of them with the Print() procedure. The  document
// journal module has the Print button that
// calls printing procedure for the current document.
Procedure PrintClick(Item)

// You will get the current document where the cursor is  positioned.
CurDoc = FormElements.LogList.CurrentRow;

// You will get the default form of the current document.

FormCurDoc = CurDoc.GetForm();

// Call the printing procedure located in

// the module of document form.
FormCurDoc.Print();

EndProcedure
1-148 1C:Enterprise 8.3. Developer Guide

4.7.3. Passing Procedure and Function Parameters

Procedure and function parameters are passed using two methods. One method
is called passing by reference. Rather than passing a specific parameter value,
it  passes memory addresses (variable references) where this value is  located. Any
changes in  a passed value in  the called procedure or function will change the vari-
able being changed in  the calling method.
Another method is  called passing by value. This  passes a  copy of the parameter
value. In  this case, any changes in  a passed value in  the called procedure or func-
tion will not change the variable being changed in  the calling method.
At the same time, the procedure and function parameter passing process depends on
the type of call:
„„ call without transferring control between the client and the server (only on the
client or only on the server);
„„ call with control transfer between the client and the server.
Let's look at each of the methods in  greater detail.

4.7.3.1. Call without Transferring Control from the Client to the Server
If a call is executed without transferring control between the client and the
server (the call is  executed only on the client side or only on the server side), by
default the parameters are passed by reference. In  this case, a  change in  a formal
parameter changes the corresponding actual parameter. You can use the Val modi-
fier before a  formal parameter name to specify that the parameter is  to be passed
by value. In this case, you can't change an actual parameter value by assigning
a  value to a  formal parameter.
&AtClient
Procedure MyProcedure()

A = 100;
ByRef(A);
// Variable (A) = 40, because in  the body of the procedure
// the Parameter1 parameter value was changed to 40.
// Variable (A) was modified because the parameter was passed by reference.

A = 100;
ByValue(A);
// Variable (A) = 100, although that in  the body of the procedure
// the Parameter1 value parameter changed to 40.
// Variable (A) was not modified, because parameter passed by value.

EndProcedure

&AtClient
Procedure ByRef(Parameter1)

Parameter1 = 40;
Chapter 4. 1C:Enterprise Script 1-149

EndProcedure

&AtClient
Procedure ByValue(Val Parameter1)

Parameter1 = 40;

EndProcedure

However, you should note the following: if an aggregate object is  passed as
a  parameter, you cannot assign another value to the actual parameter. But you
can modify the passed object. For example, if you pass an array to a  procedure by
value, you can clear the array using the Clear() method, but you cannot change
the parameter value in  the calling procedure.
&AtClient
Procedure MyProcedure()

Array = New Array;

Array.Add(12);
Array.Add(18);

// There are two elements in  the array

ByValue(Array);

// Array is  empty, but still it's an array, not Number

EndProcedure

// Parameter is  passed by value

&AtClient
Procedure ByValue(Val Parameter)

// There are two elements in  the array

Parameter.Clear();

// There are no elements in  the array

// Change formal parameter
Parameter = 14;

// Only formal parameter is  value changed

EndProcedure

You also need to consider the specifics of variable storage when calls are imple-
mented:
&AtClient
Procedure TestProcedure()

ValueA = New Array;
ValueA.Add(1);
ValueA.Add(2);
ValueB = ValueA;
1-150 1C:Enterprise 8.3. Developer Guide

// call to any variable: ValueA or ValueB raises the

// update of one and the same array

MyProcedure(ValueA, ValueB);

// After completion of the call procedure both variables (ValueA and // ValueB) reference at one array.
// There are the following values in  the array:
// ValueA[0] = ValueB[0] = "(A)"
// ValueA[1] = ValueB[1] = "B"

EndProcedure

&AtClient
Procedure MyProcedure(Parameter1, Parameter2)

// Although that there are two parameters, in  fact only ine array is  // processed

Parameter1[0] = 5;
Parameter1[1] = 6;

Parameter2[0] = "A";
Parameter2[1] = "B";

EndProcedure

In this case you should note that the assignment operation ValueB = ValueA;
(in TestProcedure()) will not create a  copy of the array in  the ValueA variable.
Both variables will refer to the same array.
Parameters are passed to MyProcedure() by reference, so if you change two
formal parameters, one physical array is  changed.

4.7.3.2. Call with Transferring Control from the Client to the Server
Calling procedures and functions while you are transferring control between the
client and the server are characterized by the fact that, in  general, such calls change
the computer where the called method is executed. This happens because the
client works on one computer and the server works on another. Thus we can't talk
about passing parameters by reference, as a  single computer can't get direct access
to another computer’s memory. In  the file server variant, the client and the server
represent one computer, but this does not affect interaction logic. So the parameters
are passed as follows in  client/server interaction:
„„ When control is  transferred from the client to a  server (and vice versa), param-
eter copies are always passed. When server procedure or function is called
from the client, a  copy of an actual parameter is  created and transferred to the
server side. When control is  returned from the server to the client, a  copy of
an actual parameter (one which was used in  the called procedure or function)
is  also created to transfer it  back to the client.
Chapter 4. 1C:Enterprise Script 1-151

„„ If a  formal parameter is  specified with the Val modifier, the parameter value
will be passed only when a  procedure or function is  called, but it  will not be
passed back when control is  returned to the client.
„„ If the same real value is  specified for several formal parameters, a  number of
real value copies will be created that equals the number of formal parameters
using the value.
„„ If a value of the same variable is specified as formal parameters, then after
control is  returned from the server this variable value is  set as the most proper
formal parameter (without the Val modifier) that was changed in the called
function.
&AtClient
Procedure TestProcedure(Command)

ValueA = New Array;
ValueA.Add(1);
ValueA.Add(2);
ValueB = ValueA;

// Call to any variable: ValueA or ValueB raises the

// modification of one and the same array

// a  copy of the array for each formal parameter is  created

// during the procedure call
ServerProcedure(ValueA, ValueB);

// After completion of the call procedure:

// 1. ValueA and ValueB variables refer to different arrays
// 2. There are different values in  the arrays
// ValuA[0] = 5
// ValuA[1] = 6
// ValueB[0] = "(A)"
// ValueB[1] = "B"

EndProcedure

&AtServer
Procedure ServerProcedure(Parameter1, Parameter2)

// formal parameter at server "its" own array is  created because

// the copies are passed

Parameter1[0] = 5;
Parameter1[1] = 6;

Parameter2[0] = "A";
Parameter2[1] = "B";

// Server will return copies of Parameter1 and Parameter2 variables

EndProcedure
1-152 1C:Enterprise 8.3. Developer Guide

Remember that a  copy of the value is  created when parameters are passed to
a  server. This  can help avoid hard to diagnose errors in  system operation. Let us
consider the following example:
&AtClient
Procedure TestProcedure(Command)

ValueA = New Array;
ValueA.Add(1);
ValueA.Add(2);
ValueB = ValueA;
Structure = New Structure("Key1, Key2", ValueA, ValueA);
ServerProcedure(Structure);
ValueA[0] = 9;
ValueA[1] = 8;
ValueB[0] = "C";
ValueB[1] = "D";

EndProcedure

&AtServer
Procedure ServerProcedure(Parameter1)

Parameter1.Key1[0] = "0";
Parameter1.Key1[1] = "1";
Parameter1.Key2[0] = "2";
Parameter1.Key2[1] = "3";

EndProcedure

After the TestProcedure() call is  completed, the variables will have the
following states:
„„ The ValueA and ValueB arrays are identical and contain the value "С" in  the
first element and the value "D" in  the second element, since the ValueB vari-
able refers to an array of the ValueA variable, and values of these variables are
not passed to the server.
„„ The Structure variable will hold two arrays:
○○ with the values "0" and "1" for array elements located in  structure element
with Key1 key;
○○ with values "2" and "3" for array elements located in  the structure element
with the Key2 key;
○○ such behavior is  due to the fact that when the procedure is  called, a  copy
is  created not only for the parameter itself (the Structure variable), but for
all the objects in  this structure; two arrays that initially referred to one array
with 0 and 1 element values.
Chapter 4. 1C:Enterprise Script 1-153

4.7.3.3. General Considerations for Specifying Parameters

If you specify a  default value and if this parameter is  last in  the list, you can omit
it  from the list of transferred actual parameters and should not put a  comma before
this parameter.
Procedure MyProcedure(Parameter1, Parameter2 = "Default")
…
EndProcedure

// When next call is  performed,

// Parameter1 parameter value will equal 1,
// and Parameter2 parameter value – "Default" in  procedure
// "MyProcedure"
MyProcedure(1);

If the parameter does not have a  default value, you can omit it  in  the list of the
actual passed parameters when calling a  procedure or function, but you should use
a  comma separator.
If you omit the parameter when calling the procedure, it  is  either assigned
a  default value (if any) or the Undefined value.
Procedure MyProcedure(Parameter1, Parameter2, Parameter3 = "Default")
…
EndProcedure

// When next call is  performed, in  procedure "MyProcedure",

// Parameter1 parameter value will equal 1,
// Parameter2 parameter value – Undefined,
// and value parameter Parameter3 – "example"
MyProcedure(1, , "example");

You still have to use round brackets if you do not pass any parameters during the
method, procedure or function call (an empty parameter list). Do not pass data from
the client to the server (and vice versa) and do not serialize the data with cyclic
references. In  this case an error will be shown and the session will be terminated.
When you pass string values from the client to the server and vice versa, remember
that these values should not contain characters that are invalid according to the
XML version 1.0 specification (http://www.w3.org/TR/xml/).
TIP
You can perform such validation at server side using the FindDisallo-
wedXMLCharacters() function.
1-154 1C:Enterprise 8.3. Developer Guide

4.7.4. Work with Collections of Values

Some objects in  the 1C:Enterprise script are collections of values. Most collections
have similar methods and properties like Count(), Index(), Add(), Delete(), etc.
Collection items usually act as collection properties. You can implement cycling
through a  collection using For each – Of – Do clause. In  most collections, items
can be called using [<Argument>] operator (square brackets). Usually an index
of collection items is  passed as an argument. Collection item indexing starts from
zero. It means that the index of the last item in the collection equals the total
number of items in  the collection less 1.
If collection items are deleted or modified in any way while the collection
is  cycled through, subsequent system behavior becomes undefined.
See detailed descriptions of specific objects for more information about specific
collections, their properties, methods and use.

4.7.5. Use of Numbers and Indices

Some objects in the 1C:Enterprise script use numbering for their components.
Such objects may include a  string with numbered characters, a  spreadsheet docu-
ment with numbered rows and columns, etc. To call object components, you can
use Numbers. Numbering always starts from 1.
To call collection items, you can use Indices. Indexing of collection items always
starts from 0.

4.7.6. Work with System Enumerations

The 1C:Enterprise script uses a  concept of system enumerations. These enumera-
tions define specific sets of predefined values. System enumerations are accessed
as global context properties of a name. Specific values are separated from the
system enumeration name by a period. System enumerations are generally used
to set values for system method parameters or object properties and as returnable
method values.

4.7.7. Work with Predefined Values

4.7.7.1. Object Manager
Predefined value can be retrieved at the 1C:Enterprise server side by using manager
of the corresponding object. A string that defines the attribute to be obtained looks
like the following:
PredefinedValueType.MetadataObjectName.Value
Chapter 4. 1C:Enterprise Script 1-155

Consider string components in  more detail:

„„ PredefinedValueType – the following data types can be specified (in their
plural forms) to obtain predefined values:
○○
Catalogs
○○
ChartsOfCharacteristicTypes
○○
ChartsOfAccounts
○○
ChartsOfCalculationTypes
○○
Enumerations
„„ MetadataObjectName – specify a metadata object name as it is set in the
Designer.
„„ Value – it  can be one of the following:
○○ enumeration value name for enumerations
○○ name of predefined value to be obtained as it  is  set in  the Designer
○○ RoutePoints.PointName – point in  the business process route
If you want to obtain a  route point for a  business process, the string describing the
value to be obtained will look like the following:
BusinessProcesses.MetadataObjectName.RoutePoints.RoutePointName

Example:
// Retrieve enumeration value.
Type = Enums.ProductTypes.Product;

// Retrieve predefined catalog data.

Item = Catalogs.Currency.Rouble;

// Business-process route point

Point = BusinessProcess.Match.RoutePoints.Approval;

4.7.7.2. PredefinedValue() Function

Since application objects are unavailable at the client side, predefined attributes
cannot be retrieved using object manager. Therefore, a global context method,
PredefinedValue(), is used instead. This method uses a string that describes
the predefined value to be retrieved as its parameter. To describe the predefined
value, use syntax of the query language VALUE operator (see page 1-443).
The string that defines the attribute to be obtained looks like the following:
PredefinedValueType.MetadataObjectName.Value

Consider string components in  more detail:

„„ PredefinedValueType – the following data types can be specified (in their
singular forms) to obtain predefined values:
○○ Catalog
1-156 1C:Enterprise 8.3. Developer Guide

○○ChartOfChartOfCharacteristicTypes
○○ChartOfChartOfAccounts
○○ChartOfChartOfCalculationTypes
○○Enum
○○BusinessProcess
„„ MetadataObjectName – specify a metadata object name as it is set in the
Designer.
„„ Value – it  can be one of the following:
○○ enumeration value name for enumerations
○○ name of predefined value to be obtained as it  is  set in  the Designer
○○ RoutePoint.PointName – point in  the business process route
○○ EmptyRef, if you want to retrieve an empty reference.
If you want to retrieve a  route point for a  business process, the string describing
the value to be obtained will look like the following:
Example:
// Retrieve enumeration value.
Type = PredefinedValue("Enum.ProductTypes.Product");

// Retrieve empty reference value.

EmptyRef =
PredefinedValue("Document.Invoice.EmptyRef");

// Retrieve predefined catalog data.

Item = PredefinedValue("Catalogs.Currency.Rouble");

// Business-process route point

Point = PredefinedValue("BusinessProcess.Match.RoutePoint.Approval");

If you need to get the system enumeration value, the method parameter will appear
as follows: SystemEnumerationName.SystemEnumerationValue.
Example:
ChartType = PredefinedValue("ChartType.ConcaveSurface");

4.8. SYSTEM STARTUP VERSIONS

The 1C:Enterprise system can be used in  its file mode or client/server mode or as
an external connection and Web services (see page 2-819).
The Designer can be used to configure procedures and functions of common
modules and object modules for each of the versions.
Chapter 4. 1C:Enterprise Script 1-157

4.8.1. Execution of Procedures and Functions

Use preprocessor instructions and compiler directives to allow use of procedures
and functions from various modules (for information about module types see page
1-115).

4.8.1.1. Differences Between Preprocessor Instructions

and Compiler Directives
Preprocessor instructions and compiler directives are used to leave the compiled
module with components that are required in a particular context. However,
preprocessor instructions affect module source text (i.e. remove invalid text from
the module), while compiler directives affect building blocks of the code (i.e.
methods including procedures and functions as well as variable declarations).
In practice all program modules in the system can be grouped into two major
categories:
„„ Modules that exist (and run) in  a particular context; e.g., a  managed applica-
tion module can only run at the client side (thin or web client).
„„ Modules that exist (and run) in  multiple contexts. These include managed form
modules, command modules and common modules. For example, a  managed
form module can have up to 4 instances, each of them gaining control in  the
process of operation:
○○ client-side context module
○○ server-side context module
○○ client-side out-of-context module
○○ server-side out-of-context module
Command modules and common modules cannot have context-dependent instances
(unlike form modules). Therefore, certain modules can be compiled multiple
times depending on whether the module contains code fragments that can run in  a
particular context.
Let us review what impact compiler directives and preprocessor instructions have
on the source module code while it  is  being converted to executable code.
Consider a  managed form module as an example.
When you create a form, it generates 4 module instances and runs all the
required preprocessor instructions for each instance. Then each module instance
is  processed to remove the text enclosed within preprocessor instructions.
The resulting code is  compiled in  accordance with the context and compiler direc-
tives. This  creates an executable module.
1-158 1C:Enterprise 8.3. Developer Guide

Assume the form module source code contains the following construct:
&AtClient
Procedure WorkWithFiles()

#If WebClient Then

// program code 1
// runs at the web client only
#Else

// program code 2
// runs at other clients
#EndIf

EndProcedure

The following is  performed:

„„ This procedure is  compiled at any client (as the compilation directive goes).
„„ At the same time preprocessor instructions define what text is left in the
module (i.e. compiled) at what client. In  this example the web client will only
have program code 1 available, while other clients will have program code 2
available.
However, if the form module uses the following code:
#If AtServer Then

&AtClient
Procedure Client()
EndProcedure

#EndIf

The following is  performed:

„„ Source text of the procedure is  stored at the server, but is  not compiled as the
&AtClient compiler directive prevents the procedure from being used at the
server side.
„„ The client does not even store the source code of the procedure as it  is  removed
by the preprocessor instruction, i.e. it is neither compiled nor available for
calling.
The above procedure explains interaction between directives and instructions as
well as their combined application.
Please note that methods marked with &AtClientAtServerNoContext and
&AtClientAtServer directives in the program module are included simultane-
ously in  different instances of program modules.
Chapter 4. 1C:Enterprise Script 1-159

4.8.1.2. Preprocessor Instructions

Preprocessor instructions have the following syntax:
Preprocessor Instruction
#If <Logical expression> Then
#ElseIf <Logical expression> Then
…
#Else
#EndIf
Logical expression
<Logical expression> = [NOT] <Preprocessor symbol> [<Boolean
operation> [NOT] <Preprocessor symbol> [<Boolean operation>
[NOT] <Preprocessor symbol>]…]
Preprocessor symbol
<Preprocessor symbol> = { Server | AtServer | Client |
AtClient |ThinClient | WebClient | ExternalConnection |
MobileAppClient | MobileAppServer }
Boolean operation
<Boolean operation> = {AND | OR}
„„ #If
„„ #Then
„„ #Else
„„ #ElseIf
„„ #EndIf
„„ AND
„„ OR
„„ NOT
„„ Server
„„ AtServer
„„ Client
„„ AtClient
„„ ThinClient
„„ WebClient
„„ ExternalConnection
„„ ThickClientManagedApplication
„„ ThickClientOrdinaryApplication
„„ MobileAppClient
„„ MobileAppServer
1-160 1C:Enterprise 8.3. Developer Guide

Below you can see a  list of preprocessor instructions with a  brief description:
„„ Server, AtServer – defines a  server.
„„ Client, AtClient – defines any client.
„„ ThinClient – defines a  thin client.
„„ WebClient – defines a  web client.
„„ ExternalConnection – defines an external connection.
„„ ThickClientManagedApplication – defines managed application mode
for the thick client.
„„ ThickClientOrdinaryApplication – defines ordinary mode for the thick
client.
„„ MobileAppClient – defines the client part of the mobile application.
„„ MobileAppServer – defines the server part of the mobile application.
The table below specifies preprocessor instructions defined in  various 1C:En-
terprise operation modes:

ThickClientManagedApplication

ThickClientOrdinaryApplication

ExternalConnection

MobileAppServer
MobileAppClient
Server, AtServer

Client, AtClient

ThinClient

WebClient
Mode

Client/server mode
Server side +
Thick client in  ordinary mode + +
Thick client in  managed mode + +
Thin client + +
Web client + +
External connection +
File-server version
Thick client in  ordinary mode + + +
Thick client in  managed mode + + +
Thin client + +
Server side of thin client +
Web client + +
External connection +
In a  mobile application client +
On the server side of the mobile application +
Chapter 4. 1C:Enterprise Script 1-161

If you are using a  non-global common module that is  set to be used at any client
and at server, then methods enclosed in  #If Server Then #EndIf are only
available if they are called at the server side. You cannot call these methods at the
client side.
Server and AtServer instructions are identical.
Client and AtClient instructions are also identical.
NOTE
Before a  program module is  passed to a  thin or web client, the server processes
preprocessor instruction in the module. Code in the 1C:Enterprise script that
is  not executed at the client side is  replaced with white spaces (i.e. removed).
However, line break and tab characters are retained.

4.8.1.3. Compiler Directives

Compiler directives have the following syntax.
Compiler Directives
&<Directive>
<Language construct>
Directive
<Directive> = { AtClient | AtServer | AtServerNoContext |
AtClientAtServerNoContext | AtClientAtServer | Area | EndO-
fArea

Language construct
<Language construct> = <Variable description> | <Procedure
description> | <Function description>
For a  detailed description of language constructs see page 1-128.
„„ AtClient
„„ AtServer
„„ AtServerNoContext
„„ AtClientAtServerNoContext
„„ AtClientAtServer
„„ Region
„„ EndRegion
Below you can see a  list of compiler directives with a  brief description:
„„ AtClient – method is  executed at the client side in  a form context.
A variable lives as long as the client-side form.
1-162 1C:Enterprise 8.3. Developer Guide

You can access client variables of the form module from the method.
You are allowed to call any methods.
„„ AtServer – method is  executed at the server side in  a form context.
Lifetime of a  variable lasts as long as server call execution.
You can access server variables of the form module from the method.
You are allowed to call:
○○ server methods
○○ server out-of-context methods
○○ client/server out-of-context methods
○○ methods of non-global common server modules
„„ AtServerNoContext – method is  executed at the server outside the form
context.
Variables cannot be preceded by this compilation directive.
You cannot access variables of the form module from the method.
You are allowed to call:
○○ server out-of-context methods
○○ client/server out-of-context methods
○○ methods of non-global common server modules
„„ AtClientAtServerNoContext – method is  executed both at the client and
at the server, outside the form context.
Variables cannot be preceded by this compilation directive.
You cannot access variables of the form module from the method.
You are allowed to call:
○○ server out-of-context methods
○○ client/server out-of-context methods
○○ methods of non-global common server modules
○○ methods of non-global common modules with Server and Client
(managed application) check boxes
„„ AtClientAtServer – method is executed both at the client and at the
server.
Variables cannot be preceded by this compilation directive.
You are allowed to call:
○○ server out-of-context methods
○○ client/server out-of-context methods
○○ methods of non-global common server modules
○○ methods of non-global common modules with Server and Client
(managed application) check boxes
Chapter 4. 1C:Enterprise Script 1-163

„„ Region, EndOfRegion – should not be used to specify script code execu-

tion location. These directives can be used to highlight a text fragment
that can be collapsed (similarly to procedures, functions, etc.). For further
information, please see page 2-945.
The table below demonstrates compiler directives available in various
1C:Enterprise modules:
Form Form module Command Common
module variables module module
AtClient + + + +
AtServer + + + +
AtServerNoContext +
AtClientAtServerNoContext +
AtClientAtServer +

4.8.2. Use of Objects, Their Properties and Methods

Every object, method or property in  the 1C:Enterprise script (referred to as "object"
in  this section) is  characterized by accessibility level (see Syntax Assistant) that
defines where it  can be used. Additionally the Syntax Assistant specifies auxiliary
data that can be useful to the developer.
Thin client – specifies that the object is  available at the thin client.
Web-client – specifies that the object is  available at the web client.
Server – specifies that the object is  available at the 1C:Enterprise server.
External connection – specifies that the object is  available in  external connection
mode.
Thick client – specifies that the object is  available at the thick client.
Mobile application (client) – specifies that the object is available in the client
section of the mobile platform.
Mobile application (server) – specifies that the object is  available on the server side
of the mobile platform.
IMPORTANT!
If you specify that an object is  unavailable in  one of run modes, its properties
and methods are also unavailable. Therefore, it  is  not mentioned specifically at
the property and method description step.

NOTE
If an object is unavailable in a client application, the type of this object
is also unavailable in this client application. For instance, if object
CatalogObject.Contractors is unavailable within a thin client,
Type("CatalogObject.Contractors") is  also unavailable in  a thin client.
1-164 1C:Enterprise 8.3. Developer Guide

Serializable. It specifies object values can be saved (e.g., parameters of report

and data processor forms can be saved using SaveValue() and ValueToFile()
methods) and placed into ValueStorage.
The given object may be serialized to/from XML. It specifies 1C:Enterprise data
values can be read/written from/to XML. For details see page 2-745.
Exchange with server is  possible. It  specifies values of this type can be exchanged
between the client and the server.
NOTE
In the managed run mode, exchange between the client and the server is  allowed
for objects which support XDTO serialization.
The given object may be serialized to/from XDTO. It  specifies that this type can
be mapped to XDTO data model. It  also sets a  fully qualified name (namespace
URI and type name) for a  type to which this type is  mapped. For example, for the
ValueStorage type it  is  {http://v8.1c.ru/8/data/core}ValueStorage.
The Syntax Assistant includes information about caching the results of some
1C:Enterprise methods. For example, the following information will be specified
for the global context method PredefinedValue(): Execution result is  cached on
first call till the configuration or platform version is  changed.
Chapter  5

CONFIGURATION OBJECTS
This chapter contains instructions for working with the entire configuration and
describes modes and mechanisms that are used for all configuration objects.
Creation and setup of the main configuration objects (constants, catalogs, docu-
ments, sequences, logs, enumerations, reports, data processors and registers) and
some other objects located in  the Common configuration branch (filter criteria and
styles) are described in  the documentation using an example of the object editing
window (see page 59 for more details). The  same can be done using the object
properties palette.

5.1. CONFIGURATION PROPERTIES

Configuration as a whole has its own editable properties. The properties palette
opens for the root of the configuration tree.
In addition to the general properties available for each configuration object (see
page 250), the configuration also has features described below.

5.1.1. General Property Category

Default run mode – selects a  default run mode for the system (Managed applica-
tion or Ordinary application). A new configuration always has this property set
to Managed application. The run mode can be modified for a system user (see
"1C:Enterprise 8.3. Administrator Guide"). This  property cannot be changed if the
Compatibility mode property is  set to Version 8.1.
Use purposes – specifies the purpose for which an application is used (Mobile
device or Personal computer). The property is only available if the Default run
mode property is set to Managed application. The available configuration func-
tions change depending on the selected purpose.
„„ Mobile device – supports development of an application for use on a  mobile
device (for further details, see page 2-917). A limited number of application
objects is  available to the developer (for a  list of limitations, see page 2-1247);
1-166 1C:Enterprise 8.3. Developer Guide

„„ Personal computer – supports development of an application that cannot be

used on a  mobile device and functions as a  managed application;
„„ Both options are selected (Mobile device and Personal computer) – supports
development of an application that would contain objects available both on
a  mobile device and within a  managed application on a  desktop computer.
Please note the following:
„„ If Personal computer is  not mentioned in  the purpose of use:
○○ The default run mode cannot be changed.
○○ Properties that are not used on a mobile platform are unavailable in the
properties palette (see page 1-53).
○○ Only those types of objects available on a  mobile platform can be used as
types of attributes.
„„ If configuration purposes contain the option Mobile application:
○○ The module check uses settings for the Mobile application mode. By default,
this mode is  prompted to change when the settings are edited.
○○ The configuration check uses a  separately stored setting for the executed
procedures.
○○ The Syntax assistant uses a  separately stored setting for the applied filters.
Script variant – selects the default programming language (Russian or English).
The selection defines which language is used to generate language constructs
in  modules (for example, when using the Syntax Assistant) and display information
about primitive data types. Either the Russian or the English version of language
constructs can be used regardless of the value of this property. When you change
the value, the language of already entered language constructs does not change.
Default Role – selects the default role of the configuration. The  role specified here
will be used if the configuration user list is  empty and access authorization is  not
performed when the program is launched. In this case it is assumed that user
has administrative permissions regardless of the actual Administration right setting
in the role specified as the default role. If the configuration default role is not
specified and the user list is  empty, the user will work without access right restric-
tions. Roles are specified in  the Common – Roles branch of the configuration tree
(see page 1-180).
The default run mode should match the default role as far as rights to the applica-
tions launched are concerned. For instance, if Default run mode is  set to Managed
application, and the right Thin client is  disabled for the main role, the user will not
be able to work with application with a  thin client.
Managed application module – click the Open link to open the editing window for
the managed application module (see page 1-171).
Session Module – click the Open link to open the session module editing window
(see page 1-172).
Chapter 5. Configuration Objects 1-167

External Connection Module – click the Open link to open the application module
editing window (see page 1-172).
Use managed forms in  ordinary application – specifies that managed forms need to
be used in  the ordinary application mode of the thick client. Selecting this check
box changes rules of form selection in  the thick client (for details see page 1-263)
and rules of centralized configuration check (for details see page 2-1025).
NOTE
This property is  only available if the configuration editing mode is  set to Managed
application and ordinary application.

Use ordinary forms in  managed application – specifies that ordinary forms need to
be used in  the managed application mode of the thick client. Selecting this check
box changes rules of form selection in  the thick client (for details see page 1-263)
and rules of centralized configuration check (for details see page 2-1025).
NOTE
This property is  only available if the configuration editing mode is  set to Managed
application and ordinary application.

Additional full-text search dictionaries – selects common templates or constants to

be used as additional full-text search dictionaries (see page 2-839).
Common settings storage – storage is  used to store various application settings.
The  platform does not write any settings to the storage independently. The  devel-
oper should use the storage indicated in  this property in  the 1C:Enterprise script to
save or restore user application settings.
Report settings storage – storage contains user report settings.
Report variants settings storage – storage contains report variants.
Form data settings storage – storage contains form data. You can use this storage
to save data processor attributes, for example. Please note that you can select
a  different storage for each report or data processor.
Dynamic list user settings storage – this is  the storage to store dynamic list settings.
For more details on storages and how they work see page 1-223.

5.1.2. Presentation Property Category

Command interface – click Open to open an editor to specify viewability of default
subsystems on the start page (also from the perspective role).
Start page working area – click Open to open a  setup form to specify which forms
are placed on the start page and what template will be used to create a  work area.
Main section command interface – click Open to open a  command interface setup
dialog for the main section.
Main section picture – this property can be used to change the picture of the main
section on the sections panel.
1-168 1C:Enterprise 8.3. Developer Guide

Client application interface – is  used to setup the default panel layout for the Taxi
interface. The interface will change to this if a user clicks Default in the panel
editor (see page 1-108).
Default Language – specify default language for the configuration.
Brief Information – brief information on the configuration.
Detailed Information – detailed information on the configuration (multiple lines
allowed).
Logo – select a logo. Make your selection in the standard picture selection
window:

Fig. 61.  Picture Selection

NOTE
A logo must be 64x64 pixels or smaller. Picture type may be any of those sup-
ported by the 1C:Enterprise system.
Splash – use this option to select a  splash. A splash is  selected in  the standard
picture selection window. The picture to be used as a splash must be 600x255
pixels. Transparency is  not supported.
NOTE
The splash screen picture must meet the following requirements: 305x110 pixels
in  size; you can set transparent color when selecting the picture. Picture type may
be any of those supported by the 1C:Enterprise system.
Copyright – information on the configuration author.
Vendor information address – link to the information about the configuration vendor
(specified in  the Copyright property). The  address can be set with a  schema prefix
(http://) or without it.
Configuration information address – link to information about the configuration.
The address can be set with a schema prefix (http://) or without it. The  About
1C:Enterprise window displays the following data: configuration Synonym, Config-
uration information address property, Copyright property and Vendor information
address property.
Chapter 5. Configuration Objects 1-169

Default Constants Form – select the default form for input and editing of constants
in  the configuration. This  form is  selected from among the common forms (see page
1-229) in  Common – Common forms. For details on the various forms, see page 1-263.
NOTE
This property is  only available if the configuration editing mode is  set to Managed
application and ordinary application.

The Default report form, Default report settings form and Default report variant form
properties can be used to specify the default forms that will be used by reports
without the corresponding form being specified. For example, you can create
a  default report form containing some features that should be present in  all appli-
cation forms, such as sending the report generated by e-mail. To solve such a  task,
you need to create a  default report form, implement all the necessary commands
and specify it  in  the Default report form configuration property. After this action
all reports for which a  default report form is  not specified will use the default form
you created.
Default dynamic list settings form specifies a  general form to be used to edit the
dynamic list settings in  the application. If this property is  not set, an automatically
generated settings form will be used to edit the dynamic list settings.
The property Default search form specifies a  general form to be used instead of
a  system form for a  full text search, which can be called in  the Taxi interface from
the toolbar or through a  keyboard shortcut.
5.1.3. Development Property Category
Properties in  this category describe data on configuration vendor and version (for
details see page 2-1122).
Update directory address – contains address of a resource that can be used to
update the application solution.

5.1.4. Help Content Property Category

Include in  Help Content – if this property is  set, help content is  included in  the
general description of the configuration.
Help content – click Open to open the configuration description editing window.

5.1.5. Compatibility Property Category

Data lock control mode – option of controlling data locks in  a transaction (see page
1-509).
Objects Autonumbering Mode – defines whether automatically assigned object
numbers can be re-used if they are not stored in  the database.
1-170 1C:Enterprise 8.3. Developer Guide

This property can be set to Release Automatically to ensure numbering works

in the same way as in 1C:Enterprise 8.0. Automatically assigned numbers and
codes are re-used later if the object they are assigned to is  not recorded.
You can set Do not Release Automatically for this property if you want
objects requiring continuous numbering to be assigned numbers upon recording
rather than opening a  form.
Modality usage mode – specifies whether methods to open modal windows can be
used in  the application. If the property is  set to Use, modal windows can be used
with no limitations. If the property is  set to Do not use, modal windows cannot
be used in  this application. If an attempt is  made to use such modes, an error will
be diagnosed (also during the script text syntax control). Use blocking windows
instead of the modal ones (see page 1-426). If the property is  set to Use with warn-
ings, no error will be diagnosed during the attempt to use modal windows, but
a  message box will display a  message that use of modal windows is  prohibited
in  this mode. Use of blocking windows instead of modal ones is  likewise recom-
mended in  this mode.
Interface compatibility mode – the property controls the client application interface
mode.
„„ Version 8.2 – the client application uses interface version 8.2. Switching to the
Taxi interface is  not supported.
„„ Version 8.2. Taxi allowed – interface version 8.2 is  used by default. The  user
can switch to the Taxi interface via the parameters dialog, the ClientSettings
object, or the command bar.
„„ Taxi. Version 8.2 allowed – Taxi interface is used by default. The user can
switch to interface version 8.2 via the parameters dialog, the ClientSettings
object, or the command bar.
„„ Taxi – the client application works in  the Taxi interface. Switching to interface
version 8.2 is  not supported.
If interface version 8.2 is  used, the system supports switching between the inter-
face in  separate windows and between this interface in  tabs.
If Compatibility mode is  set to a  value that exceeds Version 8.3.2 (None, Version
8.3.3, or a later version), and property Interface compatibility mode is set to
Version 8.2 or Version 8.2. Taxi allowed, a  tabbed interface will automatically be
set for any new users of the application.
Picture PictureLib.Help displays differently if the Interface compatibility mode
property is  set to Taxi or Taxi. Version 8.2 allowed and in  other cases.
Compatibility mode – this property controls the behavior of mechanisms that have
been changed in  a new version if compared with theprevious one. This  property
can have the following values: Version 8.3.2, Version 8.3.1, Version 8.2.16, Version
8.2.13, Version 8.1 and None. See page 2-1214 for details of the system’s work
with any version in  compatibility mode.
Chapter 5. Configuration Objects 1-171

Configuration operations with an unknown compatibility mode are not supported.

Unknown compatibility modes are modes which are compatible with the func-
tionality implemented in later 1C:Enterprise versions. For example, if the None
compatibility mode is  set in  version 8.3.1, it  will be regarded as unknown when
the configuration is open in version 8.2.16. And if the Version 8.2.16 compati-
bility mode is  set in  version 8.3.1, then it  will be displayed as None in  version
8.2.16. If no new compatibility mode is  set in  any particular version, the behavior
of the None mode will be the same as in  the previous version. When you attempt
to run or restore the configuration with an unknown compatibility mode, an error
message will be returned indicating the version required. Restoration of 1cv8.
dt files generated in  version 8.3.1 and later is  not permitted in  later versions of
1C:Enterprise (older than 8.3.1), except where the Compatibility mode configuration
property is  set to Version 8.2.16 in  version 8.3.1.
When configurations of 1C:Enterprise 8.1 (or older versions) are converted, the
property will have the Version 8.1 value. Generally speaking, when you open
a configuration of any later versions of 1C:Enterprise, the Compatibility mode
property will be set to a  value compatible with the previous version if such a  mode
is  selected in  the new version.
If you want to ensure that the application solution operates in  multiple versions
of 1C:Enterprise simultaneously (including versions for which a compatibility
mode is  available), it  is  recommended first to obtain the current platform version
in  different locations from where the code will be called, and then compare it  with
the compatibility mode (if necessary).
If the infobase was opened using version 8.2.14 you can transit to version 8.2.13
only if the configuration did not use new features of version 8.2.14. For a  file mode
variant, migration from version 8.2.14 to version 8.2.13 is  performed with infobase
download/upload.

5.2. MANAGED APPLICATION MODULE

A managed application module launches automatically when a configuration
is  loaded during 1C:Enterprise startup in  the following modes.
„„ thin client
„„ web client
„„ thick client in  the managed application mode
The managed application module is  used for processing tasks related to the user
session (primarily for processing session start and end events). The  managed appli-
cation module is  inaccessible to procedures working on the server. We recommend
using it  to implement event handlers only.
Procedures and functions of the managed application module, along with its vari-
ables that have the Export keyword in  their titles, can be accessed in:
„„ non-global common client modules
1-172 1C:Enterprise 8.3. Developer Guide

„„ client methods of form modules

„„ client methods of command modules
In managed application module context you can use exported procedures and func-
tions of common modules.
The managed application module is  a component of the configuration and is  stored
only in  the configuration. The  File  – Save command launches the procedure of
saving changes for the entire configuration.

5.3. EXTERNAL CONNECTION MODULE

External connection module may contain exported variables, procedures and func-
tions as well as handler procedures for OnStart() and OnExit() events used
in  external connection mode (see section "Integration and Administration Tools"
in  the 1C:Enterprise script help).

5.4. SESSION MODULE

Session module runs automatically when the configuration is loaded during
1C:Enterprise system startup.
The session module is  used to initialize session parameters and process session-
related actions. The session module is always performed in privileged mode
in  the 1C:Enterprise server cluster.
IMPORTANT!
Session modules can only contain definitions of functions and procedures.
It cannot contain exported procedures or functions. It  can use procedures from the
configuration common modules.
Session parameters are set in  the SessionParametersSetting() event handler.
The session module is  executed after the application module (external connection
module) is  launched, but before calling the BeforeStart event handler (OnStart,
for the external connection module).

5.5. COMMON CONFIGURATION BRANCH

This section describes configuration objects, such as Subsystems, Common
modules, Session parameters, Roles, Common attributes, Exchange plans, Filter,
Event subscription, Scheduled jobs, Functional options, Functional options param-
eters, Defined types, Settings storages, Common forms, Common commands,
Command groups, Interfaces, Common templates, Common pictures, XDTO pack-
ages, Web-services, WS-references, Style items, Styles and Languages. These
objects do not describe data structure and data processing mechanisms. They are
used to set rules for working with data, to describe supplementary objects used
Chapter 5. Configuration Objects 1-173

for making different forms in  the data exchange mechanism and they also contain
common modules and templates of print forms accessible from any configuration
module.

5.5.1. Subsystems
For a  description of subsystem purposes see page 1-343.
NOTE
Setting Desktop as a  subsystem name is  not recommended.
The number and nesting levels of objects at the Subsystems branch are unlimited.
To view configuration objects for a  specified set of subsystems, you can set an
object filter in  the Configuration window. Select Actions – By Subsystems in  the
Configuration window and specify a  required set of subsystems, then set additional
filter criteria, Include objects from subordinate subsystems and Include objects from
parent subsystems.

Fig. 62.  Filter by Subsystem

The subsystem list contains a  special item, <Not included in  subsystems>, which
you can use to select only those objects that do not belong to any subsystem.
NOTE
When filtering by subsystems is  set, key configuration object tree branches
without filtered objects are not shown.
The user interface defines whether configuration objects belong to a particular
subsystem.
The Subsystems configuration object property value can be accessed in the
program using the 1C:Enterprise script tools. This  provides additional options for
data filtering.
The Move subsystem command in the context menu can be used to change
subsystem subordination in  subsystem hierarchy.
1-174 1C:Enterprise 8.3. Developer Guide

Use the Content tab in  the subsystem editor to bind metadata objects to a  particular
subsystem.

Fig. 63.  Set of Subsystems

The upper part of the window displays all configuration objects that can be
assigned to individual subsystems. Placing a checkmark next to an object (e.g.,
Contractors on fig. 63) means that this object is  included into the subsystem and
is  displayed in  the lower part of the window. You can see all objects belonging to
the subsystem being edited at the bottom of the window.
If the Include in  Help Contents property is  set, the help contents will include the
branch showing help for the subsystem and all objects included in  the subsystem.
If the property is  reset, the help contents will not contain such a  branch (describing
the subsystem and included objects), but help for the objects included in the
subsystem will be available directly in  object forms.

5.5.2. Common Modules

Objects in  the Common modules configuration branch are used for storing texts of
functions and procedures that may be called from any other configuration module.
IMPORTANT!
A common module can contain definitions of functions and procedures only.
Procedures and functions of the common module that have the Export keyword
in their titles belong to the global context. Detailed information on writing
Chapter 5. Configuration Objects 1-175

procedures in  a common module can be found in  sections "Source Text Format
in  Program Modules" and "Operators" of the 1C:Enterprise script help.
To edit a  common module, click Open in  the Module property at the properties
palette of Common Modules object type in  the Configuration window. Text of the
common module is  opened in  the 1C:Enterprise text editor in  module text editing
mode.
A common module is a component of the configuration and is stored in the
configuration only.
The Global property defines if the common module exported methods belong to the
global context.
If the Global property is  set to True, the common module exported methods are
available as methods of the global context.
If the Global property is  set to False, a  property is  created in  the global context
and its name matches the common module name in  the metadata. This  property
is read-only. Value of this property is the CommonModule object. Through this
object, exported methods of this common module are exposed. Therefore, syntax
for calling a  non-global common module method looks like XXXXX.YYYYY where
XXXXX is the property name in the common module context and YYYYY is the
name of the common module exported method.
Example:
TradeEquipmentOperation.PlugInBarcodeReader();

5.5.2.1. Various Contexts and Common Modules

Using properties of common modules and preprocessor instructions, you can
arrange execution of various common module methods in  the right context.
Each property of a  common module is  responsible for compilation (and execution)
of this common module in  a particular context.
You can use the following properties that are responsible for the context where
common module methods are available:
„„ Client (ordinary application) – common module methods are only available for
the thick client in  the ordinary application mode;
„„ Client (managed application) – common module methods are available for the
thin client, web client and thick client in  the managed application mode;
„„ Server – common module methods are available at the server;
„„ External connection – common module methods are available in an external
connection.
If multiple properties are set simultaneously, it  means common module methods
are available in  multiple contexts.
1-176 1C:Enterprise 8.3. Developer Guide

If a common module has its Server property set along with another property,
it  means this module is  available at the server and the selected client. You should
keep in mind that you would have multiple variants of compiled code (for the
selected clients and the server).
If a method located in this common module is called by the client, it uses the
client copy of the module; if called by the server, it  uses the server copy. In  this
case you can use preprocessor directives (for details see page 1-159) to "protect"
the server from the code it  cannot execute.
Consider the following example. A common module that can run at both the thin
client and the server owns a  method which behaves differently depending on where
it  is  executed: the thin client or the server. Consider how you can handle this:

Procedure CommonModuleMethod() Export

// Enter important code here

#If ThinClient Then

// Display warning
ShowUserNotification("At client");
#EndIf

EndProcedure

The server-side code looks like the following:

Procedure CommonModuleMethod() Export

// Enter important code here

EndProcedure

The code on the thin client side looks like the following:
Procedure CommonModuleMethod() Export
// Enter important code here

// Display warning
ShowUserNotification("At client");

EndProcedure

You can use different methods to transfer control from the client to the server:
„„ call methods of the server-side common module;
„„ in the form or command module, call a  method preceded by compiler directives
&AtServer, &AtServerNoContext (for details on form modules see page
1-390).
Please note that server procedures do not support calls to methods of client
common module (without their Server property set) or to client methods of form
Chapter 5. Configuration Objects 1-177

and command modules. Control is transferred back to the client after the most
external call to a  server method is  complete.
This does not apply to form and command module methods preceded by compiler
directives &AtClientAtServer, &AtClientAtServerNoContext (for details see
page 1-390).
Please keep in  mind the following points:
„„ While writing code for a  common module that is  available to multiple clients,
you should consider maximum limits which might be imposed by clients or use
preprocessor instructions to "isolate" client-specific code.
„„ Preprocessor instructions are also useful if a common module has multiple
execution contexts, e.g., an external connection and a  thin client or a  client and
a  server (as is  often the case). In  this case preprocessor instructions enclose
interactive code that cannot run at the server and can be executed at the client
(see the example above).
For details on preprocessor instructions and compiler directives see page "Use
preprocessor instructions and compiler directives to allow use of procedures and
functions from various modules (for information about module types see page
1-115)." on page 1-177 and section "Execution of Procedures and Functions" in  the
1C:Enterprise script help.
To control calls to exported methods of the server-side common module in the
client code, use the Server call property. If this property is  set, exported methods of
the server-side common module can be called by the client. If this property is  not
set, you can only call exported methods from server-side methods (both methods of
server-side common modules and server methods of form and command modules).
TIP
It is  recommended to set the Server call property to False if the server-side com-
mon module contains methods that are not recommended to be called by the client
(e.g., for safety reasons).
NOTE
If the Client (ordinary application), Client (managed application), External connection
properties are set simultaneously, the Server call property is  cleared automatically.
If the Server call property is  set, the Client (ordinary application), Client (managed
application) and External connection properties are automatically cleared, provided
that they were set simultaneously.
The Privileged property can be used to disable control over access rights when
executing common module methods.
IMPORTANT!
If the Privileged property is  set for the common module, its Server property is  set
automatically and other properties are cleared (Client (ordinary application), Client
(managed application) and External connection). The  privileged common module
can only be executed at the server.
For details on the privileged mode see page 1-181.
1-178 1C:Enterprise 8.3. Developer Guide

5.5.2.2. Reuse of Return Values

If a common module is not global, its Reuse return values property becomes
available. This  property can have the following values:
„„ Do not use – return values for common module functions are not reused;
„„ During call and During session – method of data reuse definition is  used for
the common module. The essence of this method is that the system stores
function parameters and execution results after the first call. Next time the
function is called with the same parameters, the stored value (from the first
call) is  returned without the function being executed. If parameter values are
changed during execution, this method is  not used upon the next call of the
function.
Storing call results is  characterized by the following:
„„ if a function is executed on the server and is called from the server code,
parameter values and call results are stored for the current session on the server
side;
„„ if a  function is  executed on a  thick or thin client, parameter values and call
results are stored on the client side;
„„ if a function is executed on the server, but is called from the client code,
parameter values and call results are stored both on the server side and on the
client side.
Stored values are deleted:
„„ If the property is  set to During call:
○○ on the server side – when control is  returned from the server;
○○ on the client side – upon completing execution of a  procedure or function of
the 1C:Enterprise script (called by the system from the interface rather than
another procedure or function of the 1C:Enterprise script).
„„ If the common module property is  set to During session:
○○ on the server side – when the session is  finished;
○○ on the client side – when the client application is  closed.
Stored values can be deleted:
„„ at the server, thick client, external connection, thin client and web client with
regular connection speed – 20 min. after the stored value is  evaluated or 6 min.
after its last use;
„„ at the thin client and web client with low connection speed – 20 min. after the
stored value is  evaluated;
„„ if there is  not enough RAM in  a server working process;
„„ if a  working process is  restarted;
„„ if a  client is  switched to another working process.
If values are deleted, an export function is  called identically to the first call.
Chapter 5. Configuration Objects 1-179

This common module property does not affect procedure execution: procedures are
always executed.
If return values reuse is set for a common module, the list of export function
parameter types becomes limited. Parameters can only be of the following types:
„„ Primitive types (Undefined, NULL, Boolean, Number, String, Date);
„„ Any references to database objects;
„„ Structures with property values of the above types. In  this case parameter iden-
tity is  controlled based on structure content.
If the Reuse return values property is set to During session in the common
module, values returned by functions of this module can't use TempTablesManager
type values.
Where the function of a  common module with the reuse option selected is  called
from the same common module (e.g. named CommonModule), it  should be remem-
bered that if the function is  called by the MyFunction() name, the function will
be executed every time the function is  called. To make use of saved values, the
function should be called by its full name: CommonModule.MyFunction().
RefreshValuesReuse() global context method removes all reused values both
at the server side and at the client side, regardless of the method call location.
After the RefreshValuesReuse() method is executed, the first function call
is  executed afresh.

5.5.3. Session Parameters

Session parameters are mainly used in queries and conditions of data access
restriction for the current session.
Using session parameters reduces data access time by excluding linked tables.
You can set session parameters using the properties palette.
Each session parameter may have two access rights: Get and Set (see below
for details on access rights). If the Set right is  removed, session parameter may
be initialized only in  a common module with the Privileged property set or in  a
session module.
Session parameters are initialized in the SessionParametersSetting() event
handler of the session module (see page 1-172).
Prior to initialization, the session parameter is in  Not Set state. An attempt to
read this parameter calls the SessionParametersSetting() event handler first.
If after the call the parameter is  still Not Set, it  raises an exception.
You should be able to discriminate between applications of session parameters and
global variables of a  managed application module (external connection module).
The  main differences of session parameters include:
„„ Session parameters are metadata objects, meaning that 1C:Enterprise can exer-
cise a  tighter control over their use.
1-180 1C:Enterprise 8.3. Developer Guide

„„ Session parameters are typed. A list of session parameter types is  limited. Their
common feature is  inability to modify the inner state for objects of these types.
„„ To set or get a value for a session parameter, the current user should have
sufficient rights.
„„ In the client/server mode, session parameter values are stored at the
1C:Enterprise server and are available from both the server and the client.
„„ Session parameters are available both in  the 1C:Enterprise script, for example:
SessionParameters.CurrentUser = UserName()

and access restrictions, for example:

Document.Report.User = &CurrentUser

In the latter case getting a  session parameter value does not require the current user
to have corresponding rights.
NOTE
If one of the following types is set for the session parameter: FixedArray,
FixedCollection or FixedStructure, the Undefined value can be used as
a  collection element value.

5.5.4. Roles and Access Rights

5.5.4.1. Overview
Each user of the system should have free access to common information, e.g.,
common catalogs, constants or enumerations.
On the other hand, each user must have access only to the information they need
in their work, and their careless actions must not affect work of other users or
operability of the system as a  whole.
The 1C:Enterprise Designer provides developers with advanced administration
tools that can resolve this issue.
The required number of typical roles is  created together with configuration. Roles
describe rights of various user categories to access information handled by the
system. You can assign a  wide range of roles – from ability only to view a  limited
number of document types to a  full set of rights to enter, view, update and delete
any type of data.
There are two types of access rights in  1C:Enterprise – basic rights and interac-
tive rights. Basic rights are always checked regardless of how infobase objects
are accessed. Interactive rights are checked whenever interactive activities are
performed (viewing/editing forms etc.) For available access rights see page 2-1209
(or a description of the AccessRight() global context method in the Syntax
Assistant).
Chapter 5. Configuration Objects 1-181

If the View right is  set (granted) for an object with data in  a form, but the Edit
right is not set, this attribute is displayed in the form (with the attribute value
displayed in  the control associated with this object), but the value is  unavailable
for editing. If the View right is  removed (withdrawn), an attempt to open the form
displays an "Access violation!" warning, and the form fails to open.
When editing roles, note the internal right hierarchy in  the list of rights. The  hier-
archy is based on the precedence of the rights. When any right is removed,
every lower-level right associated with it is also removed and, conversely,
when a  lower-level right is  set, any higher-level rights removed are also set. So
removing the View right causes the Edit right to be removed. This  is  quite reason-
able since it  does not make sense to grant an edit right when a  control associated
with the data cannot be shown.
Generally, rights can be granted for:
„„ the entire configuration
„„ objects
„„ object attributes
„„ tabular sections
„„ tabular section attributes
„„ standard attributes
When a  new role is  created, the following access rights are set for the configura-
tion root object: ThinClient, WebClient, UserDataStorage and Output.

5.5.4.2. Privileged Mode of Operation

Code fragments can run in ordinary or privileged mode at the 1C:Enterprise
server. The  privileged mode does not require an access check at the record level or
a  rights check and allows any operation, thus accelerating module execution.
You can manage the privileged mode, i.e. enable or disable it, using the SetPrivi-
legedMode() global context method.
IMPORTANT!
In the client/server mode calling this method has no impact if you work at the
client side.
The privileged mode is  disabled by default.
The privileged mode should be enabled as many times as it  is  disabled. However,
if the privileged mode was enabled within a procedure or a function (once or
multiple times) and was not later disabled, the system disables it  automatically as
many times as it  was enabled in  the procedure or function without being disabled.
If a procedure or function calls the SetPrivilegedMode(False) method
more often than it  calls the SetPrivilegedMode(True) method, an exception
is raised.
1-182 1C:Enterprise 8.3. Developer Guide

The PrivilegedMode() function returns True if the mode is on and False if
it  is  completely off. It  does not count how many times the privileged mode has
been enabled in  a particular function.
You might need to set the privileged mode programmatically if you perform mass
operations with infobase data and do not need to check data access rights. Assume
a user is responsible for recalculation of product prices. In this case the data
processor that performs this operation can check the right of the current user to run
it, and then the privileged mode can be enabled to perform all the required actions
in  the database. The  user might have no rights to view the prices. However, since
this data processor only recalculates the prices without showing them to the user,
the task of access restriction is  also performed.
You can also start a  privileged session. In  this session, a  privileged mode is  set
from the very start of work. During operation, mode PrivilegedMode() will
always return True, and disabling the privileged mode is  not supported. To start
a  privileged mode, the user shall be assigned administrative rights (Administra-
tion rights). To launch a  session, use the UsePrivilegedMode key of the client
application launch command line, or the prmod parameter of the line used to
connect to an infobase.

5.5.4.3. Safe Mode of Operation

If you need to use unsafe code at the server, e.g., external data processors or code
entered by the user in  Execute() and Evaluate() methods, you can use the safe
mode.
In the safe mode:
„„ Privileged mode is  disabled.
„„ Transition to privileged mode is  ignored.
„„ Operations using tools that are external relative to the 1C:Enterprise platform
are not allowed:
○○ COM-mechanisms:
□□ COMObject()
□□ GetCOMObject()
□□ HTMLDocumentShell.GetCOMObject()
○○ Loading add-ins:
□□ LoadAddIn()
□□ AttachAddIn()
○○ Access to the file system:
□□ ValueToFile()
□□ FileCopy()
□□ MergeFiles()
□□ MoveFile()
Chapter 5. Configuration Objects 1-183

□□ SplitFile()
□□ CreateDirectory()
□□ DeleteFiles()
□□ New File
□□ New xBase
□□ HTMLWriter.OpenFile()
□□ HTMLReader.OpenFile()
□□ XMLReader.OpenFile()
□□ XMLWriter.OpenFile()
□□ FastInfosetReader.OpenFile()
□□ FastInfosetWriter.OpenFile()
□□ XMLCanonicalizingWriter.OpenFile()
□□ XSLTransform.LoadFromFile()
□□ ZipFileWriter.Open()
□□ ZipFileReader.Open()
□□ New TextReader()
□□ New TextWriter()
□□ New Picture(), if the first parameter is  a string
□□ Picture.Write()
□□ New BinaryData()
□□ BinaryData.Write()
□□ FormattedDocument.Write()
□□ GeographicalSchema.Read()
□□ GeographicalSchema.Write()
□□ GeographicalSchema.Print()
□□ SpreadsheetDocument.Read()
□□ SpreadsheetDocument.Write()
□□ SpreadsheetDocument.Print()
□□ GraphicalSchema.Read()
□□ GraphicalSchema.Write()
□□ GraphicalSchema.Print()
□□ TextDocument.Read()
□□ TextDocument.Write()
○○ Internet access:
□□ New InternetConnection
□□ New InternetMail
□□ New InternetProxy
□□ New HTTPConnection
□□ New FTPConnection
1-184 1C:Enterprise 8.3. Developer Guide

IMPORTANT!
When forbidden operations are performed at run time, an exception is  raised.

NOTE
External reports and data processors opened using File – Open are executed in  the
safe mode if the user has no administrative access rights.
The safe mode should be enabled as many times as it  is  disabled. However, if the
safe mode was enabled within a  procedure or a  function (once or multiple times)
and was not later disabled, the system disables it  automatically as many times as
it  was enabled in  the procedure or function without being disabled.
If a  procedure or function calls the SetSafeMode(False) method more often than
it  calls the SetSafeMode(True)method, an exception is  raised.
The configuration developer might need to set the safe mode programmatically
if he or she intends to use code that is  external relative to the configuration and
is not absolutely reliable. An example would be execution of Execute() and
Evaluate() methods when executable code comes from outside the system.
In  this case setting the safe mode before executing these methods would be a  good
practice.
// The  code to be executed is  generated
// The  code could be loaded from external sources
// or entered manually
ExecutableCode = GetExecutableCodeFromOutside();

// Enable the safe mode

SetSafeMode(True);

// Execute the potentially dangerous code

Execute(ExecutableCode);

// Disable the safe mode

SetSafeMode(False);

5.5.4.4. Data Deletion Modes

The 1C:Enterprise system enables users to delete unnecessary or obsolete informa-
tion in  two modes:
„„ direct deletion of objects when use of deleted objects in  other database objects
is  not analyzed;
„„ reference integrity control enabled when objects are first marked for deletion
and then checked for being referenced by other objects.
If the user has the right to use direct deletion mode, additional responsibility is  laid
both on the user that deletes the objects and on the system administrator who deter-
mines user rights and system operation with unresolved references. For example,
Chapter 5. Configuration Objects 1-185

specialists debugging the configuration can use system operation without reference
integrity control. If reference integrity control is not used, objects are deleted
directly (without deletion marks) and unresolved references can appear.
The most radical method of setting the reference integrity control mode is  fully
disabling the right to directly delete entire objects. This method prevents any
direct deletion of objects within a  given configuration. Users are only able to mark
objects for deletion.
Please note that you can directly delete objects using the 1C:Enterprise script tools.
Therefore, items of a  specific configuration can directly delete objects bypassing
reference integrity control. In this case a specialist who configures the system
is  responsible for data integrity.

5.5.4.5. Rules of Role Sets

Roles are usually specified for each activity. When a  new user is  added to the user
list (see "1C:Enterprise 8.3. Administrator Guide"), a  certain role or a  set of roles
is  assigned to this user. If the user has multiple roles, the access algorithm for each
object and right (e.g., Interactive Mark for Deletion) works as follows:
„„ if any of the roles has permission, access is  granted;
„„ if no roles have permission, access is  denied.

5.5.4.6. Access Rights Editor

The left part of the rights editing window contains a  configuration object tree for
all subsystems. The  right part of the same window displays a  list of rights for the
selected configuration object. If an action is  checked, it  is  allowed.
Thus, a  user with the Salesperson role can view a  GoodsReceipt document,
but cannot add it  interactively (see fig. 64).
The Set rights for new objects check box defines whether a  certain role has rights
for newly added configuration objects (it is  cleared by default for a  new role).
The Set rights for attributes and tabular sections by default check box defines
whether this role has rights for attributes (including standard attributes) and
tabular sections (including standard tabular sections) of new configuration objects
(it is  selected by default).
When you change the status of the Set rights for attributes and tabular sections by
default check box, the system prompts you to change (select or clear) access rights
for all attributes (including standard attributes) and tabular sections (including
standard tabular sections) of all configuration objects. If you reject this action, no
change is  made in  the existing objects; however, default behavior of new objects
is modified.
1-186 1C:Enterprise 8.3. Developer Guide

Fig. 64.  Editor of Role Access Rights

When a  new role is  created, the Designer sets the following for all rights:
„„ rights are not granted for objects.
„„ rights are granted for attributes (including standard attributes) and tabular
sections (including standard tabular sections).
The Independent rights of subordinate objects checkbox defines how the system
considers the parent object rights when it determines the rights for a subordinate
object. If the checkbox is checked, parent object rights are not considered. If the
checkbox is  reset, the corresponding parent object right is  analyzed to determine any
subordinate object rights. If the parent object does not have the right, the subordinate
object will also not have the right, regardless of the subordinate object right state.
Even if Independent rights of subordinate objects is  selected, the right to a  subor-
dinate object requires that the same right be held to the parent one. That means
that an attribute or a  tabular part requires the right to an object, while the tabular
part attribute requires the right to a  tabular part or an object. This  property matters
if a user is assigned several roles with rights added via "OR". That means that
if a  role has the Independent rights of subordinate objects property set, and there
is  only a  right to an attribute, while another role has the right to an object only, the
user will have the right to an attribute only when the rights of these roles are added.
When setting attribute (tabular sections) access rights for reports/processes, please
note the following: if the Independent rights of subordinate objects checkbox
is  unchecked and the Edit right is  set for the attribute (tabular section), and the
View right is  not set for the report/processes, it  will be assumed that the Edit right
is  also not set for the attribute (tabular section).
Chapter 5. Configuration Objects 1-187

If multiple roles are assigned to a  user, the parent object rights are validated before
rights per role are combined (see page 1-185).
The Independent rights of subordinate objects check box affects the following
objects:
„„ attributes (including standard attributes)
„„ tabular sections (including standard tabular sections)
„„ tabular section attributes (including standard tabular section attributes)
„„ commands
To change an access right, select a  configuration object in  the left-hand list and
select or cleat the check box for the required action in  the right-hand list. If you
need to modify access to all objects in  a branch, select it  in  the left-hand window
and make the required changes in  the access rights.
A description of each role can be displayed in  a spreadsheet or text document using
Actions – Output list.

5.5.4.7. View and Edit All Roles

If a configuration uses multiple roles, it is recommended to use the All Roles
window for convenient viewing and editing of rights. To open it, select the Roles
branch in  the configuration object tree of the Configuration window and then select
All Roles in  the context menu.

Fig. 65.  All Roles Editing Window

The window contains three table boxes. The  first (leftmost) field is  used to select
the required configuration object. The  first column of the second table box contains
a  list of rights for the selected object. The  other columns are used to specify use of
each right for every existing role.
1-188 1C:Enterprise 8.3. Developer Guide

To set or remove all the rights for any role, select or clear the permission check box
in  the first row of the table box.
To set or remove all permissions for a  certain right in  all the roles, select or clear
the permission check box in  the first row of the table box.
You are allowed to move columns corresponding to roles.
The third table box is  used to edit data access conditions at the level of separate
fields and records.

5.5.4.8. Data Access Restriction

Overview
Data access restrictions can be used to manage access rights at the level of both
metadata objects and 1C:Enterprise database objects. You can use the following
1C:Enterprise objects to restrict access to data:
„„ roles
„„ session parameters
„„ functional options
„„ privileged common modules
„„ ALLOWED keyword in  the query language
A combination of the above objects ensures maximum flexibility in  assigning data
access rights to various users with different job duties.Data access restrictions can
be applied to reading or modifying database objects. A current user is granted
a  right to read or modify a  database object only if the applied access restriction
entitles him or her to do so. Otherwise the read or modify operation of the database
object is  not performed.
Various access restrictions can be applied to operations (addition, modification or
deletion) with the following types of database objects:
„„ exchange plans
„„ catalogs
„„ documents
„„ charts of characteristic types
„„ charts of accounts
„„ charts of calculation types
„„ business processes
„„ tasks
You can apply restrictions to reading the entire object or its individual fields for the
following types of database objects:
„„ exchange plans
„„ catalogs
Chapter 5. Configuration Objects 1-189

„„ documents
„„ document journals
„„ charts of characteristic types
„„ charts of accounts
„„ charts of calculation types
„„ information registers
„„ business processes
„„ tasks
IMPORTANT!
If you call database object fields from the 1C:Enterprise script using application
object properties, it  reads the entire object rather than the value of the used field.
The  only exception is  retrieving a  presentation when field values are only read
if they are a  part of this presentation.
Access restrictions are stored in  roles, can be assigned to most metadata objects
and written in  a special language that represents a  subset of the query language.

Data access restriction language

Data access restrictions are described in a special language, which is a subset
of the query language (for a  detailed description of the query language, see page
1-442). Data access restriction language differs from the query language as follows:
„„ A data access restriction query always includes one table as a  source of data.
This  is  a table of the object to which such a  restriction is  applied (the main
restriction target).
„„ Query description is  shortened. Data access restriction language only uses the
FROM and WHERE sections of the query language. For instance, a description
in  the query language looks as follows:
<Query description>
SELECT [ALLOWED] [DISTINCT] [TOP <Count>]
<Selection field list>
[FROM <Source list>]
[WHERE <Filter condition>]
[GROUP BY <Group fields>]
[HAVING <Filter condition>]
[FOR CHANGE [<List of top level tables>]]

On the other hand, a  description in  the data access restriction query language
looks as follows:
<Query description>
[Main limitation target table alias]
[FROM <Source list>]
[WHERE <Filter condition>]
1-190 1C:Enterprise 8.3. Developer Guide

For a  description of a  list of sources, see page 1-453. For a  description of filter
conditions, see page 1-460. Please note that embedded queries used in  the data
access restriction language have a  limited set of available functions (see page
1-191);
„„ Session parameters (see page 1-192) and functional options (see page 1-192)
can be specified as condition items;
„„ Templates that simplify a  description of restrictions (see page 1-197) may
be used in  any part of a  data access limitation query.
The main component of such a restriction is a condition calculated for each
entry of the database table to which a  data access restriction is  applied. An entry
is  available if a  non-empty table is  received when a  condition is  applied to one
table entry of the main restriction target (i.e. a table that contains one or more
entries). If an empty table is  received when a  condition is  applied, the entry to
which the condition was applied is  unavailable. The  user can change a  table entry
for the main restriction target, if such an entry does not contradict the restriction set
for the right – both before the change operation, and after it.
Table fields
The following can be used in  data access limitations:
„„ Table fields of an object, for which data access limitations are described.
For example, if a  restriction is  applied to reading items of the Contractors
catalog, it  can use fields of the Contractors catalog and its tabular sections.
Thus, the simplest restriction applied to reading items of the Contractors
catalog can look like the following:
WHERE Description = "Brickworks"

Or:
WHERE Goods.Description = "Red brick"

Where Goods is  a tabular section of the Contractors catalog.

„„ Fields of object tables that can be accessed by references stored in the
main object of restriction. For example, if the ChiefManager attribute of the
Contractors catalog references the Users catalog, the access restriction can
look like the following:
WHERE ChiefManager.Code = "Jones"

Or:
WHERE ChiefManager.Person.Description = "Petrovsky"

„„ Fields of object tables associated with the main object of restriction by

certain conditions and expressions with these fields.
Chapter 5. Configuration Objects 1-191

For example, you can apply the following restriction to reading items of the
Contractors catalog:
Contractors
FROM
Catalog.Contractors AS Contractors
LEFT JOIN Catalog.Users AS Users
BY Contractors.ChiefManager.Description = Users.Description
WHERE Users.Person.Description = "Petrovsky"

This restriction uses fields of Users catalog items associated with an item
in the Contractors catalog by the value of the Description fields.
Nested queries
Nested queries are used to create a  set of entries to be used:
„„ to connect to a  table of the main restriction target;
„„ as a  comparison operand IN or NOT IN.
Nested queries may use any query language tools except for the following:
„„ IN HIERARCHY operator;
„„ TOTALS statement;
„„ Results of nested queries will not contain any tabular sections;
„„ Some virtual tables, including BalanceAndTurnovers.
The next example of a  restriction applied to reading the Contractors catalog
uses a  nested query as a  set of records for association with the main object of
restriction:
Contractors
FROM
Catalog.Contractors AS Contractors
LEFT JOIN
SELECT
Users.Description, Users.Person
FROM
Catalog.Users AS Users
WHERE
Users.Code > "Petechkin") AS Users
BY Contractors.ChiefManager.Description = Users.Description
WHERE Users.Person.Description = "Petrovsky"

Below is  an example of a  restriction applied to reading the PassportDetail-

sPersons, where a  nested query is  used as an operand in  the IN comparison
operation:
PassportDetailsPersons
WHERE
PassportDetailsPersons.Person IN
(SELECT DISTINCT
1-192 1C:Enterprise 8.3. Developer Guide

Employees.Person AS Person
FROM
InformationRegister.Employees AS Employees)

If you want to retrieve data from a tabular section in the nested query, you
should call this tabular section directly in  the FROM section of the nested query.
For example, rather than using the following:
SELECT
Ref AS Ref,
Goods.Description AS GoodsDescription
FROM Catalog.Contractors
as a  query nested in  the restriction, you should use the following:
SELECT
Ref AS Ref,
Description AS GoodsDescription
FROM Catalog.Contractors.Goods

Session parameters
Data access restriction queries may include session parameters. For example, you
can apply the following restriction to reading items of the EmailMessageGroups
catalog:

WHERE Owner.AccountAccess.User = &CurrentUser

AND Owner.AccountAccess.Administration = TRUE

Where CurrentUser is  a session parameter (see page 1-179).

Functional options
Data access restriction queries may include functional options. You are only
allowed to use functional options that are independent of parameters. For example,
if the Nomenclature catalog has a MainWarehouse attribute, a restriction
applied to reading this attribute might look like the following:
WHERE &AccountingByWarehouse = TRUE

Where AccountingByWarehouse is  a functional option (see page 1-211).

Usage features
Restrictions applied to database objects of the following types can only use some
fields of the main data object of restriction:
„„ Accumulation registers can contain dimensions of the main restriction object
only.
„„ Accounting registers within restrictions can use balance dimensions of the
main restriction object only.
Chapter 5. Configuration Objects 1-193

NOTE
If turnover register data access restrictions use dimensions that are not part of the
totals, then the stored totals will not be used when you are accessing the virtual
turnover table, and the request will be based on the record table only.

Access Restriction Actions

Access restrictions are checked every time an operation is  performed on database
objects (in the dialog boxes, 1C:Enterprise script or queries) and can operate in  one
of two ways:
„„ All. The  "All" approach means that an operation on data (in the dialog boxes,
1C:Enterprise script or queries) should be performed on all database objects
the operation includes. If this operation means reading or modifying database
objects and the corresponding access restrictions are not met, the operation fails
due to access rights violation.
„„ Allowed. With the "Allowed" approach, an operation on data only reads data-
base objects if they meet relevant access restrictions. Database objects that do
not meet access restrictions are considered as missing during the operation and
have no effect on the result.
Data access restrictions are applied to database objects when 1C:Enterprise calls
the database. In  the client/server mode of 1C:Enterprise restrictions are applied at
the 1C:Enterprise server.
The approach to applying restrictions selected for each operation on data
is determined by the purpose of the operation and severity of its results. Thus,
the "Allowed" approach is  used to display dynamic lists and perform other inter-
active actions. The  "All" option is  used to perform all operations on application
objects in the 1C:Enterprise script including all changes to database objects.
Therefore, it can cause difficulties in generating a selection for the Select()
method of catalog, document or other managers with subsequent result iteration
if a  corresponding object has a  relatively complex restriction since some access
rights restrictions cannot be represented correctly in  a selection for the Select()
method.
You can manage the approach to access restrictions in queries. To do so, you
can use the ALLOWED keyword of the query language. If a  query does not contain
ALLOWED, restrictions are assigned the All approach. If ALLOWED is  specified, the
Allowed approach is  applied.
It is  important to note that queries with the ALLOWED keyword should only have
selections that match all restrictions applied to reading database objects used in  the
queries. If the query uses virtual tables, the corresponding selections should also be
applied to the virtual tables.
1-194 1C:Enterprise 8.3. Developer Guide

Example:
SELECT
ContactInformationSliceFirst.Presentation
FROM InformationRegister.ContactInformation.SliceLast(, Type = &Type)
AS ContactInformationSliceFirst
WHERE
ContactInformationSliceFirst.Type = &Type

If an object-oriented approach is  used, getting access to data in  the ALLOWED mode
is not supported. Object techniques are intended for critical operations on data
including data modification. To retrieve data using object techniques, regardless of
the restrictions set, you should perform the required actions in  a privileged module
or as a  user with full access rights. There are no methods of retrieving allowed data
only within the object techniques.
Mechanism of Applying Restrictions
In 1C:Enterprise any operation with data stored in the database eventually calls
the database requesting to read or modify data. When queries to the database
are executed, 1C:Enterprise internal mechanisms restrict access. The following
is performed:
„„ A list of rights (read, insert, update, delete), database tables and fields used
in  the query is  generated.
„„ Data access restrictions applied to all rights, tables and fields used in  the query
are selected in  all roles of the current user. If any of the roles has no data access
restrictions applied to a  table or field, it  means values of the required fields
are available in  any record of the table. In  other words, when no data access
restrictions are applied, it  means the WHERE True restriction.
„„ Current values of all session parameters and functional options that contribute
to the selected restrictions are obtained.
To obtain a  session parameter value from the current user, you do not need to have
the right to obtain this value. However, if any session parameter value has not been
set, an error will occur, and a  database query will not be executed.
Obtaining functional options depends on the way in  which the Privileged mode for
obtaining property of the functional option is  set (see page 1-211). If the property
is  reset, the current user will possess read rights for the object where the functional
option is  stored.
„„ Restrictions retrieved from a  single role are grouped using AND.
„„ Restrictions retrieved from different roles are grouped using OR.
„„ Generated conditions are added to SQL queries used by 1C:Enterprise to
call the DBMS. When data are retrieved (from metadata objects or database
objects), access restriction conditions do not validate rights. The mechanism
of adding conditions depends on the selected approach to applying restrictions:
All or Allowed.
Chapter 5. Configuration Objects 1-195

"All" Approach
If restrictions are applied using the "All" approach, conditions and fields are added
to SQL queries so that 1C:Enterprise could obtain information on any data in  the
database query even though it  is  not allowed for the current user. If restricted data
are used, the query fails. An outline of applying restrictions with the help of the
"All" approach is  shown on fig. 66:

Fig. 66.  "All" Approach

"Allowed" Approach
If restrictions are applied using the Allowed approach, conditions are added to
SQL queries so that records unavailable to the current user have no impact on the
query result. In  other words, if restrictions are applied using the Allowed approach,
records unavailable to the current user are considered missing. An outline of this
approach is  represented on fig. 67:

Fig. 67.  "Allowed" Approach

Other Objects Associated With Data Access Restrictions

If you develop configurations using data access restrictions, metadata objects, such
as session parameters, functional options and common modules with the Privileged
flag, might prove useful.
1-196 1C:Enterprise 8.3. Developer Guide

Session Parameters
You can use session parameters in  data access restrictions in  the same way you
use query parameters in  queries.
Functional Options
You can use functional options that are independent of parameters in  data access
restrictions in  the same way you use query parameters in  queries.
Privileged Common Modules
If a  common module has its Privileged flag set, execution of procedures and func-
tions in  this module takes on important characteristics:
„„ In 1C:Enterprise client/server mode a  privileged module runs at the server only.
„„ When procedures and functions of a  privileged module or any objects they call
are executed, the rights restriction system is  disabled (both for metadata objects
and for data). Therefore, in  the privileged module, you can perform any opera-
tion on any objects even if the current user is  not granted the required rights.
Privileged modules are used to set initial values of session parameters used in  data
access restrictions. Additionally common modules allow users with restricted rights
to perform consistent actions with data. For example, if the user is  responsible for
entering and posting documents, but should have no access to data impacted by
document posting, the posting operation can be transferred to a  privileged module.
In  this case the user can post documents without being granted rights to any other
data (e.g., registers).
Privileged Mode
When working with data, you can set the privileged mode programmatically.
You might need to set the privileged mode programmatically if you perform
mass operations with infobase data and do not need to check data access rights.
For a  description of the privileged mode see page 1-181.
Using preprocessors
Preprocessor instructions can be used when editing data access restriction text.
The  following instructions are available:

#IF <Expression> #THEN

#ELSEIF <Expression> #THEN
#ELSE
#ENDIF

<Expression> – is  an arbitrary logical expression in  the script with a  Boolean
type result. The  expression may contain the following:
„„ Comparison operations <, >, <=, >= , =, <>.
Chapter 5. Configuration Objects 1-197

„„ Logical operations AND, OR, NOT.

„„ Session parameters with syntax &Parameter, where Parameter is the name of
the session parameter.
If a  #OR or #ELSEIF instruction expression results in  True, the resulting text of
the access restriction instruction contains the text that follows #THEN keyword.
When an expression results in  False, the text following #THEN keyword will not
be included in  the access restriction instruction text. The  text following #ELSE will
be added to the resulting access limitation text if none of the earlier criteria is  met.
NOTE
If the data access limitation text contains preprocessor instructions, the syntax
of such a  restriction is  not checked during editing and cannot be changed via
Designer.

Example:
#IF &CurrentUser <> "Klimova" #THEN
<access limitation text>
#ENDIF

Where CurrentUser – is  a session parameter of type CatalogRef.Users.

This construct means that a  condition to set access restrictions will be checked for
all users from the catalog, except for Klimova.
Access restriction description templates
A role may contain a  list of access restriction templates described on the Restric-
tion Templates tab of the role form. Such access restriction templates may be edited
in  the group editor for access restrictions and templates (see page 1-202).
Every access restriction template has a  name and contains text. The  template name
is  compliant with the standard naming conventions for 1C:Enterprise system.
Part of the template text uses data access restriction language. Template text can
also contain parameters marked by the "#" character.
The "#" character may be followed by:
„„ One of the following keywords:
□□ The Parameter keyword followed by the parameter’s number in the
template in  brackets;
□□ CurrentTable – means the full name of the table for which a  restriction
is  created is  inserted into the text;
□□ CurrentTableName – means the full name of the table (as a  string value,
in quotes) to which an instruction is applied is inserted into the text
in  the current variant of the script;
□□ CurrentAccessRightName – contains the name of the right to which the
current restriction applies: READ, INSERT, UPDATE, DELETE;
1-198 1C:Enterprise 8.3. Developer Guide

„„ Template parameter name – means inserting a  restriction for the corresponding

template parameter into the text;
„„ "#" character – means inserting one "#" symbol into the text.
The access restriction expression may contain the following:
„„ Access restriction template in the following format:
#TemplateName("Template parameter value 1", "Template param-
eter value 2", …). Each template parameter is contained in double
quotation marks. If the parameter text contain a  double quotation mark, two
double quotes should be used.
„„ Function StrContains(SearchWhere, SearchWhat). This  function is  used
to search for SearchWhat string occurrences in  SearchWhere returns True if
occurrences are found, and otherwise False.
„„ "+" operator for string concatenation.
To facilitate template text editing on the Restriction Templates tab in  the role form,
click the Set the template text button. Type template text in  the dialog that opens
and press OK.
1C: Enterprise performs a  syntax check for the template texts, templates use and
macrosubstitution of role access restriction template text in  query text.
Template macrosubstitution consists of the following:
„„ replacing parameters’ occurrences in  template text with parameter values from
the template use expression in  restriction text;
„„ replacing the template use expression in  query text with the resulting template
text.
When a  query designer is  called for the condition that contains access limitation
templates, a  warning about replacing all templates is  displayed.
Sample restriction templates follow below:
Template name Template
Template body Total = #Parameter(1)
Usage Where #Template("10")
Result Where Total = 10

Template name Template1 (DocumentKind)

Template body DocumentKind = #DocumentKind
Usage Where #Template1(""Invoice"")
Result Where DocumentKind = "Invoice"

Template name Template2

Template body DocumentKind = #Parameter(1) ## #Parameter(2)
Usage Where #Template2(""Invoice"", "1"")
Result Where DocumentKind = "Invoice # 1"
Chapter 5. Configuration Objects 1-199

Template name Template3

Template body DocumentKind = #Parameter(3)
Usage Where #Template3("","",""Invoice"")
Result Where DocumentKind = "Invoice"

General Recommendations on Rights Restriction

For flexible control of user access to data and compliance with user duties, you are
recommended to use the following guidelines when restricting data access:
„„ Select a  set of data (possibly dependent on the current user) that could require
preparation. On the one hand, the selected data should streamline data access
restriction; on the other, its size should not be too big. Allocate the data by
session parameters.
„„ Set values for the session parameters in  the SessionParametersSetting()
handler of the session module.
„„ Set access restrictions for data that require it the most (data are sensitive or
critical to maintaining system integrity). Please note that access restrictions can
result in  slower handling of these data. Excessively complex restrictions can
also affect performance adversely.
„„ If you need to allow a  limited set of operations with data for a  user who does
not need full data access rights, transfer these operations to a  privileged module
or explicitly enable and disable the privileged mode in  the right points of the
code (see page 1-181).
„„ When objects are recorded and the system performs appropriate checks, data are
accessed in  the privileged mode (see page 1-181). In  this case you can leave
rights restrictions enabled at the level of records for the relevant fields if these
data are used in  the configuration in  the managed mode only:
○○ when parent, owner and code uniqueness is  checked for catalogs;
○○ when code uniqueness is checked for documents, business processes and
tasks;
○○ when code uniqueness is  checked for exchange plans, it  is  disabled;
○○ when parent and code uniqueness is checked for charts of accounts and
charts of characteristic types.
When you create a  data restriction request, you should note the following:
„„ If data access restrictions are set for the object table and the data access query
includes a  merge with such a  table, connection conditions (the UNTIL query
section) can't contain the object tabular section with the set access restriction.
„„ If the query contains a  table which does not use any type of field in  its query,
all data restrictions are applied to the table. For example, the SELECT QUAN-
TITY (*) FROM Catalog.Contractors query will be run with all access
1-200 1C:Enterprise 8.3. Developer Guide

restrictions set for the Test catalog. Restrictions are applied as "OR", i.e., all
records available by at least one condition will be available. If conditions are
not set for some of the fields, the query will be run for all table records.
If the query uses a  top-level table, any restrictions set for nested tables columns
are not applied.
If the query uses a  nested table, all restrictions are applied both for the nested
table and the top-level table. For example, the SELECT QUANTITY (*) FROM
Catalog.Contractors.Agreements query will be run with all the restric-
tions for the Contractors catalog and all the restrictions for the Agreements
tabular section.
„„ If access to the fields required to get a  metadata reference object's representa-
tion is  disabled using data access restrictions or object access is  disabled at the
access rights level, then getting the object's representation will not affect the
current transaction.

Data Access Restriction Wizard

To open a  wizard, in  the Access Restriction column in  the Data access restric-
tions table box, click the selection button. Then, in  the Restrict access window,
click Query Builder.
A wizard form will open:

Fig. 68.  Tables and Fields Tab in  Restrictions Wizard

Use the wizard to specify conditions for data access restriction.

Select the required objects in the Tables and fields tab and move them to the
Tables and Fields section. The  wizard will also have the Links tab if you specify
several tables.
Chapter 5. Configuration Objects 1-201

Fig. 69.  Links Tab in  Restrictions Wizard

The Links tab enables you to specify the criteria for the links between the fields of
the tables. Click Add to enter a  new condition and select one of the tables from the
Table1 column. Select another table with fields linked to the fields of the first table
from the Table2 column. Controls that are used to create table link conditions are
located below the criteria list.
If a simple type of condition is selected, choose the linked fields of the tables
in  Field1 and Field2 and set the comparison condition. If the selected fields are not
compared, the condition list line will display the following error message in  the
Link condition column: Incorrectly completed condition.
Specify conditions for source data filtering at the Conditions tab.

Fig. 70.  Conditions Tab in  Restrictions Wizard

For each selected field, choose the type of condition and specify the parameter
name. You can use a  session parameter as the parameter. You can specify multiple
conditions. In  this case the Condition column of the table box displays the condi-
tion text in  multiple rows.
You can view the query text anytime while generating the query by clicking the
Query button.
1-202 1C:Enterprise 8.3. Developer Guide

Batch Editing of Access Rights Restrictions

The batch editing mode for access rights restrictions is  enabled by using the All
access restrictions command in  the context menu of the Roles branch. The  form
that opens contains two tabs: Access restrictions and Restriction Templates.

Fig. 71.  All Access Rights Restrictions

This mode can be used to view all the entered access restrictions in  a single list (by
all roles, objects, rights and field combinations).
You are allowed to add access restrictions for multiple roles, objects, rights and
field combinations.
You can also filter the lost using different criteria.

Fig. 72.  Filtering Access Restrictions

In the batch editing mode you can remove the restrictions marked in  the list.
You can also edit the selected restrictions. While doing so, you can replace a  set of
fields and/or access restrictions.
Chapter 5. Configuration Objects 1-203

Additionally the batch editing mode can be used to copy the selected restrictions to
other roles.

Fig. 73.  Copying Restrictions

The Restriction Templates tab shows all access restriction templates that are
included in the application. But only the first 10 strings ending with ..., if the
template text contains more than 10 strings, are shown. The template editing
window shows the full template text.

Fig. 74.  All Access Restrictions Templates

You can add the access restriction template for multiple simultaneous roles.
You can select the templates you need with a  set of criteria and according to the
value of the current column.

Fig. 75.  Filtering Access Restrictions Templates

1-204 1C:Enterprise 8.3. Developer Guide

If necessary, you can copy one or more templates to other roles.

Fig. 76.  Copying Restrictions Templates

The editor also allows you to edit selected templates. You are allowed to change
the template name and text if needed.

5.5.5. Common Attributes

A common attribute is  an attribute that is  added to all or multiple configuration
objects. A common attribute can be used in  two scenarios:
„„ As a  common attribute, i.e., to simplify the specification of an attribute that
is included in all (or several) configuration objects in which the attribute
retains its meaning and type. An example of such a scenario is an arbitrary
comment field in  application documents.
„„ As a part of data separation – a special application that is used to divide
all stored data and application workflow on different parts. Data separa-
tion is enabled for the common attribute. An example of this scenario, the
subscriber notion is used, when several data "owners" can work in a single
physical infobase, while application users will think that the infobase contains
only their data. For details on data separation, see page 2-895.
To create a  common attribute, you need to create a  Common attribute configura-
tion object. You can do this the usual way in the Designer mode, i.e., select
Common – Common attributes in  the configuration window and add a  new object.

Fig. 77.  Creating a  common attribute

Chapter 5. Configuration Objects 1-205

This will result in a Common attribute configuration object that can be used to
include common attributes in  necessary configuration objects.
Common attribute behavior is set with the Data split property. If this property
is set to Do not use, the configuration object created will be used only as an
attribute included in  several (or all) of the configuration objects. If the property
is  set to Split, the common attribute will use a  data separator (see page 2-895).
A list of configuration objects in which a common attribute is included is set
using the Content and Auto-use properties (or in  a corresponding tab in  the More
window (see page 1-56)).

Fig. 78.  Common attribute without separation

If the Auto-use property is  set to Use, the common attribute created will be auto-
matically added to all existing configuration objects (for which common attributes
can be used) and it  will be automatically added to all new configuration objects.
If the Auto-use property is set to Do not use, the attribute will not be added
automatically, and you should use the Content property to select objects in  which
common attributes will be included.
The same property should be used when the common attribute is  used automati-
cally and there are objects to which the attribute should be added (see fig. 79).
The common attribute content editing window is  divided into two parts:
„„ The upper part shows all the configuration objects that can be included in  a
common attribute.
„„ The lower part shows objects with non-default settings that are set with the
Auto-use common attribute value:
○○ If the property is  set to Use, the lower side will contain a  list of objects not
included in  the common attribute.
○○ If the property is  set to Do not use, the lower side will contain a  list of
objects included in  the common attribute.
1-206 1C:Enterprise 8.3. Developer Guide

Fig. 79.  Common attribute content

You can edit data both in  the upper and lower sides, and the edited configuration
object will be moved between the window sides regardless of the Use column
value.
The Use column can have one of three values for every configuration object:
„„ Automatic – this value means that assigning the configuration object to
a  common attribute will depend on the common attribute’s Auto-use property:
○○ The Use value specifies that the configuration object is included in the
common attribute.
○○ The Do not use value specifies that the configuration object is  not included
in  the common attribute.
„„ Use – this value specifies that the configuration object is included in the
common attribute regardless of the Auto-use property value.
„„ Do not use – this value specifies that the configuration object is  not included
in  the common attribute regardless of the Auto-use property value.
So you can use the Content property, for example, to selectively exclude some
objects from a  common attribute event if autousage is  enabled for the attribute.
A common attribute (without the data separation mode) can include the following
configuration objects:
„„ Catalogs
„„ Documents
„„ Document journals
„„ Charts of characteristic types
Chapter 5. Configuration Objects 1-207

„„ Charts of accounts
„„ Charts of calculation types
„„ Business processes
„„ Tasks
„„ Information registers
„„ Accumulation registers
„„ Accounting registers
„„ Calculation registers
„„ Exchange plans
„„ External data sources
When a  document is  recorded, the log’s common attribute gets the value of the
document’s common attribute or NULL if the document is  not a  part of the common
attribute.
A common attribute can be used in  data access restrictions (see page 1-188).
It is  a good idea to add external data sources to the common attribute only if the
common attribute is  a separator (see page 2-895). Detailed information on how to
use an external data source that is  part of the separator can be found in  the section
on this (see page 2-871).
A common attribute can be composite.
TIP
Do not use common attributes to describe data that is  related to specific object
business logic.
Common attributes are shown in  the form editor when you edit common attribute
object forms, and they can be placed on a  form.

5.5.6. Exchange Plans

Exchange plans are used to implement data exchange procedures. An exchange
plan:
„„ Contains information about nodes that can be used in  data exchange;
„„ Defines what data are to be exchanged;
„„ Specifies whether the exchange should use the distributed infobase mechanism.
A single application solution can have multiple exchange plans, each of them
describing a particular procedure of data exchange. For example, when you
exchange data with remote warehouses or offices, you are most likely to use two
exchange plans (one for the exchange with warehouses and another – for the
offices), since the data set you exchange with the warehouses is  much narrower
compared to the data set you exchange with the offices.
For a  description of data exchange procedures see page 2-745.
1-208 1C:Enterprise 8.3. Developer Guide

5.5.7. Filter
Filter criterion objects are components of the information filtering mechanism.
A system configuration specialist uses them to create predefined filtering rules.
In  the 1C:Enterprise mode these criteria will be used for filtering information from
lists.
Specify the name, synonym and comment in the Filter criterion object editing
window.
Filter criteria may be of any standard type or of any type defined as configuration
tree object. You can include composite-type attributes such as CatalogRef, Docu-
mentRef, etc. and composite-type attributes with a  defined chart of characteristic
types (Characteristic…).
Specify the types for filtering when you create a  type of filter criteria. The  Content
tab for this type will contain a  list of configuration objects containing data of the
type that is included in the filter criteria type. Check the attributes that will be
used as a  filter.
For the criteria to perform their functions, create a  list of attributes of catalogs and
documents in the Designer (Content tab). There are virtually no limits imposed
on the contents of the list: for example, unlike a  journal column, you can select
several attributes of a  document or its tabular section for the filter criteria.
There may be any number of filter criteria and each criterion may have more
than one form of displaying results. This procedure can be useful when you
look for various information. For example, you want to filter all documents that
use a certain contractor (in attributes and tabular sections). You can also set
other information filtering criteria (e.g., you can search posted documents only or
a  specific date range, etc.).
NOTE
When you open a  filter form, the Filter parameter with the filter value set (the
Value element) will be transferred to it. For more details on the form parameters,
see page 1-384.
Filter criterion may have any number of forms for displaying results. For quick
retrieval of filtered information you can place the form call in  the user menu or on
the toolbar.
If there are multiple filter criteria forms, specify the default form in  the Default
Form property.
If the configuration has multiple subsystems, select the subsystem where the crite-
rion belongs. You can specify several different subsystems.
To call a  filter criteria form, the system places the corresponding command in  the
form navigation panel.
Chapter 5. Configuration Objects 1-209

5.5.8. Event Subscription

You can use event subscriptions to assign event handlers for an object or a  group
of objects in  the 1C:Enterprise script.
When you add a  new event subscription, in  addition to the common configuration
object properties you should also specify an event source, an event for the assigned
handler and a  procedure that handles the event.
Event sources can be application objects and register record sets defined in the
configuration. You are allowed to select objects as sources for multiple events or
select all objects of the same type (e.g., all documents).
You should select an event in the drop-down list that contains events that are
present in  all selected objects. Otherwise the list will be empty.
The event handler can be selected in  the window containing procedures that can be
assigned as event handlers. These procedures should meet the following require-
ments:
„„ The procedure should be stored in  a common module;
„„ The common module containing the procedure should have the following prop-
erties set:
○○ Global box is  unchecked;
○○ Client (ordinary application) box is  checked;
○○ Client (managed application) box is  unchecked;
○○ Server box is  checked;
○○ External connection box is  checked.
„„ The number of procedure parameters should be one more than the number of
parameters for the selected event handler (since in  addition to parameters, the
event's source object is  also passed to the event handler).
When the specified event occurs, the following action sequence is  performed:
„„ the event is  first processed in  the object and calls the handler defined in  the
object or record set module;
„„ if the handler is  performed while the Cancel parameter is  set to True or an
exception is  raised, the action is  aborted;
„„ then external event handlers assigned to the event are called in  random order;
„„ if the assigned handler is  performed while the Cancel parameter is  set to True
or an exception is  raised, the action is  aborted.
The object (record set) that has called the event is  passed to the assigned handler as
a source.
The assigned event handlers are called in  the same context as the action that has
called the event. If you need to run the assigned handler at the server, you should
include a call to the common module procedure performed at the server in the
handler code.
1-210 1C:Enterprise 8.3. Developer Guide

You can also assign event handlers by using the 1C:Enterprise script. Use the
AddHandler and DeleteHandler operators for these purposes.
Objects that can become sources of events have the AdditionalProperties prop-
erty of the Structure type. This  property can store information between event
calls, e.g., information on whether the object is  new or old.

5.5.9. Scheduled Jobs

5.5.9.1. Main Features of Jobs
Jobs have the following main features:
„„ Defining scheduled procedures at the stage of system programming;
„„ Performing specified actions in  compliance with a  schedule;
„„ Calling a  specified procedure or function asynchronously, i.e. without waiting
its completion;
„„ Monitoring job progress;
„„ Managing jobs (cancelling, locking execution, etc.);
„„ Waiting for completion of a  single or multiple jobs.

5.5.9.2. Background Jobs

Background jobs are implemented through the 1C:Enterprise script tools. Back-
ground jobs are used to perform application tasks asynchronously. They can
generate child background jobs, e.g., to run complex calculations concurrently at
different working servers of the cluster in  the client/server mode.
You can restrict background jobs with identical methods based on an application
characteristic. You can create and manage background jobs programmatically
within any user connection to the 1C:Enterprise infobase. A background job
is  performed under the account of the user that created the job.

5.5.9.3. Scheduled Jobs

Scheduled jobs are an integral part of any application solution. They are described
at the configuration stage (see fig. 80).
Each scheduled job can be assigned a  schedule that will be used to launch the job
automatically. 1C:Enterprise supports one-time and recurring schedules. You can
set the start and end date; daily, weekly or monthly schedules. Schedules can be set
up both at the configuration stage and at run time (in 1C:Enterprise mode).
When launched, a  scheduled job generates a  background job that is  responsible
for the actual processing. A scheduled job can run under the specified user account
and can be re-launched (e.g., in  case of unexpected shutdown).
Chapter 5. Configuration Objects 1-211

Fig. 80.  Background Job Schedule

In the client/server mode you can use the administration utility to disable automatic
execution of scheduled jobs for a  particular infobase.

5.5.9.4. Execution of Scheduled Jobs

In the client/server mode scheduled jobs are launched by the cluster manager.
It  means scheduled jobs run even if there is  no client connection to the infobase
(if the jobs are not disabled for this particular infobase).
For peculiarities of background tasks in file and client/server variants, see page
2-831.

5.5.10. Functional Options and Their Parameters

5.5.10.1. Purpose
A developer can use functional options to describe configuration functionality that
can be quickly enabled or disabled at the implementation stage or during system
operation. For example, you can isolate use of additional merchandise properties
as a  separate functional option. In  this case disabling this functionality hides all
functions associated with additional merchandise properties in the configuration
interface.
The system can automatically adjust to the modified settings by hiding disabled
functionalities and making the interface more transparent and user-friendly.
At the development stage you might want to make a  functional option value depen-
dent on specific parameters, e.g., some organizations do not use foreign currency
accounting. This can be implemented through Functional option parameters, an
object that parameterizes functional options.
1-212 1C:Enterprise 8.3. Developer Guide

5.5.10.2. What Do Functional Options Impact?

Functional options can influence the following:
„„ User interface: If some functional options are disabled, the system hides all
associated items of the user interface. The following interface items are
affected:
○○ Global command interface
○○ Form attributes (including attribute columns of ValueTable or ValueTree
type)
○○ Form commands
○○ Reports implemented through the data composition system
IMPORTANT!
If the client application works with a  file mode infobase version via a  web server,
changing the functional option will change the user interface only after the web
server restarts (restarting the client application will not change the user interface).
„„ Algorithms written in  the 1C:Enterprise script: You can retrieve values of
functional options programmatically and use them in  various situations, e.g. to
decrease the amount of calculation.
IMPORTANT!
Functional options and their parameters do not affect the database structure. All
tables and fields remain in  the database regardless of the functional options.

Global Command Interface

In the global command interface functional options make the system hide
commands for all objects associated with the disabled options. For example, if the
Purchases functional option is  set to False, it  hides commands of opening the
Purchases section, creating a  GoodsReceipt document, opening a  GoodsRe-
ceipt list, etc.
At the same time the Purchases option might be dependent on the parameter value
of the Organization functional option. Modifying this parameter value in the
1C:Enterprise script, you can change the state of the functional option, i.e. visibility
of the interface item.
The following should be considered when creating the command interface:
„„ The command will be excluded from the command interface if the functional
option has disabled the attribute which is  a parameter of that command.
„„ The command will be excluded from the command interface if the functional
option has disabled the command parameter type. If the command parameter
type is a compound one, the command will become unavailable when all
parameter types are disabled.
Chapter 5. Configuration Objects 1-213

Form
Functional options can affect form attributes and commands, as a consequence,
changing visibility of associated form elements (fields and columns for form attrib-
utes and buttons for form commands). Please take note of the following system
behavior features when developing a  form:
„„ The form attribute of the reference type will be disabled if the functional option
disables the configuration object forming this type. The complex type form
attribute will be disabled if the functional options disable all complex types.
„„ The <Type>Object form attribute (e.g., the main form attribute) will be disa-
bled if the functional option disables the configuration object forming this type.
„„ The form table will be disabled if it  displays the data of a  form attribute disa-
bled by a  functional option.
„„ Types are not available in  the type selection dialog (e.g. for text boxes linked
with complex type attributes) if the functional option disables configuration
objects forming this type. Information regarding the types disabled by func-
tional options is  cashed on the client side and cleared in  20 minutes or when
the RefreshInterface() method is  called.
IMPORTANT!
Unlike the command interface, parameter values of functional options are set for
a  specific form instance only.

Data Composition System

The data composition system is  mainly used to generate reports. Functional options
affect data sets output in  the report and the list of report settings available to the
user. For example, if the Foreign currency accounting functional option is  disabled,
the report outputting a  Goods Receipt document register will not contain Currency
and Currency amount columns and filtering, grouping, sorting and performing other
actions based on the Currency field will not be available.
For details on how functional options affect availability of fields in  a report gener-
ated in  the data composition system, see page 1-633.

Characteristics
Functional options affect the visibility of form fields that display object char-
acteristic values. To make such changes, you need to add an attribute with
a  characteristic value to a  functional option.
Consider the following example. Characteristics are used for the Products catalog,
characteristic types are stored in  the plan as Characteristics and their values
are stored as a  CharacteristicValues information register resource. A resource
is included in the CharacteristicsAccounting functional option.
1-214 1C:Enterprise 8.3. Developer Guide

Fig. 81.  Influence of functional options on characteristics

If you disable the CharacteristicsAccounting functional option, field visibility

is  disabled in  forms (the Value column and Value field), thus displaying character-
istic values as shown in  fig. 81.

5.5.10.3. General Workflow

Use of functional options involves two metadata object types: Functional option and
Functional option parameters.
A functional option is  a metadata object that can directly influence the applica-
tion interface (if the option stores its value in  a Boolean type attribute). You can
use objects of this type to hide items associated with unavailable functionality.
For example, the Multicurrency accounting can hide the Currencies catalog, the
Currency field in  documents or the Currency amount in  reports. The  source of
the functional option value is  a metadata object selected as the Location property;
it  can be a  constant, for example.
If a functional option value is stored in a catalog attribute or an information
register resource, additional information is required to specify the exact way of
selecting the option value. This  is  where the Functional option parameters meta-
data object is  used.
Functional option parameters can be compared to axes of reference in  a space of
functional option values. A single parameter of functional options can define its
own axis value for a  subset of functional options.
Consider the following example. Assume that the sum total depends on a  ware-
house owned by a  particular organization (see fig. 82). The  infobase can maintain
accounting for various organizations at multiple warehouses.
Chapter 5. Configuration Objects 1-215

Fig. 82.  Parameterized Functional Option

To store values of functional options, create an information register with the

following dimensions (axes of reference):
„„ Organization (of appropriate type),
„„ Warehouse (of appropriate type).
A resource of the information register will be a  value of a  quantitative accounting
functional option.
Then the general configuration structure will look like the following:
„„ Information register SumTotal:
○○ Organization dimension;
○○ Warehouse dimension;
○○ SumTotal resource of Boolean type.
„„ Organization functional option parameter. The  Use property references the
Organization dimension of the SumTotal information register.
„„ Warehouse functional option parameter. The Use property references the
Warehouse dimension of the SumTotal information register.
„„ SumTotal functional option, Location property references the SumTotal
resource of the SumTotal information register.
As a  result, if you want to define whether quantitative accounting is  required, you
need to specify values for functional option parameters (Organization and Ware-
house) in  each particular case and retrieve values of functional options.
Thus, in the example on, sum total is allowed for Organization 1 and Warehouse 1,
but is not allowed for Organization 2 and Warehouse 1.

5.5.10.4. Interaction with Other Objects

Functional options can be assigned to the following configuration options:
„„ subsystems
„„ common commands
„„ constants
„„ filter criteria
1-216 1C:Enterprise 8.3. Developer Guide

„„ catalog
„„ document
„„ journal
„„ chart of accounts
„„ chart of characteristic types
„„ chart of calculation types
„„ business process
„„ task
„„ exchange plans
„„ report
„„ data processor
„„ accumulation register
„„ information register
„„ accounting register
„„ calculation register
„„ command
„„ metadata object attribute
„„ tabular section
„„ tabular section attribute
„„ accounting flag
„„ extra dimension accounting flag
„„ addressing attributes
„„ register dimension
„„ register resource
Functional options can also affect visibility of form elements.
5.5.10.5. Creation
Creation of Functional Options
To create a  functional option, you need to create a  Functional option configuration
object. You can do it  the usual way in  the Designer mode, i.e. select Common –
Functional options in  the configuration window and add a  new object (see fig. 83).
It will result in  a Functional option configuration object that can be used to assign
functional options to other metadata objects (see fig. 84).
In addition to the name field, the object has another required field – Location.
In  the editor you can select one of the objects that will serve as a  source for the
option value. The  list of available objects includes:
„„ Constants
„„ Catalog attributes
„„ Information register resources
Chapter 5. Configuration Objects 1-217

Fig. 83.  Creating a  Functional Option

Fig. 84.  Location of Functional Option Value

The source of the option value can be any type, without restriction; however, for
interface management purposes you can only use functional options that store their
values in  attributes of the Boolean type. Functional option values of other types
are only available for analysis in  the 1C:Enterprise script.
The PrivilegedGetMode property specifies how the functional option value
is  received (and cached).

Fig. 85.  Privileged mode when getting the functional option value
1-218 1C:Enterprise 8.3. Developer Guide

If this property is set, the functional option value is performed in privileged

mode. The  received value is  cached for all sessions related to this infobase.
If the PrivilegedGetMode property is reset, the functional option value
is  performed in  normal mode. Caching is  performed for the current session. Both
the value (if it  was received) and the flag indicating that the value can't be received
are cached.
The cache is  reset if the session parameter values are changed.
TIP
Setting the PrivilegedGetMode property is  recommended in  all cases when
a  functional option value does not contain sensitive information.

Creation of Functional Option Parameter

To create a functional option parameter, you need to create a  Functional option
parameter configuration object. You can do it the usual way in the Designer
mode, i.e. select Common – Functional option parameters in the configuration
window and add a  new object.
In addition to its name, the object has another required property – Use. This  prop-
erty indicates a  set of objects that define how a  functional option value is  selected.
The  list of available objects includes catalogs and information register dimensions.
You can select a  catalog (out of the entire catalog list) and a  dimension in  each
information register for every functional option parameter on the list.
IMPORTANT!
You cannot use the same metadata object in  multiple functional option param-
eters.

5.5.10.6. Use
Assignment to Metadata Objects
A metadata object (e.g., a catalog) can be assigned to one or more functional
options. To do so, you can use the Functional options property that stores references
to the functional options created in  the configuration (see fig. 86).
The list of available options is limited to the options that have an object of
Boolean type in  their Location property.
IMPORTANT!
If an object is  not assigned any functional options, it  is  always visible. Otherwise
the object is  visible if at least one of its assigned functional options is  enabled
(i.e. functional options are grouped by OR).
Chapter 5. Configuration Objects 1-219

Fig. 86.  Assigning a  Functional Option to an Object

Assignment to Form Attributes and Commands

Objects that belong to a  form (Attributes and Commands) can also be used in  func-
tional options.

Fig. 87.  Assigning a  Functional Option to a  Command

You can do so in  the form editor by setting the Functional options property for the
required object.
1-220 1C:Enterprise 8.3. Developer Guide

The state of functional options affects visibility of form objects in  the same way
it  affects metadata objects. For example, if a  command is  disabled using a  func-
tional option, all associated buttons are hidden.
If a  form attribute or command has no functional options assigned, it  is  always
visible. Otherwise the form attribute or command is  visible if at least one of its
assigned functional options is  enabled.
Use in  Data Access Restriction
You can use Functional options within data access restrictions (see page 1-188)
in  the same way as Session parameters (see page 1-179). You are only allowed to
use options that are independent of parameters, i.e. are bound to constants.
IMPORTANT!
The system checks name uniqueness for session parameters and functional
options.

Definition of Functional Option Value

A functional option value is  defined by the object indicated in  the Location prop-
erty. With constants, their values are used. With options that are associated with
catalog attributes or information register resources, values stored in  these objects
are used. To find the specific object that stores the functional value parameter, you
need additional information – a  set of parameter values for functional options.
If an option is stored in a catalog attribute, the parameter should reference this
attribute. If an option is  stored in  an information register resource, values for all
register dimensions should be specified. In this case each dimension should be
characterized by its own parameter.
If some parameters are missing for a  functional option of Boolean type, all values
with unspecified parameters are grouped by OR. For example, if a functional
option is  stored in  an information register with Organization and Warehouse
dimensions, but you only set the Organization dimension, the functional option
value is  set to True if at least one warehouse listed in  the Warehouse dimension
has a  functional option value set to True.
However, if a  functional option type is  different from Boolean and some param-
eters are not specified, it  raises an exception.
Methods of the 1C:Enterprise script allow you to retrieve an option value depending
on the passed parameters and for the parameters set for the command interface or
a  specific form.
If a  functional option is  bound to a  resource of a  periodic information register,
the system uses the Slice Last to retrieve the option value. If you want to retrieve
an option value for a  different date, you should specify a  value for the Period
parameter of Date type that is  then used as a  date for slice retrieval. You do not
need to create this parameter in metadata. It is automatically provided by the
system.
Chapter 5. Configuration Objects 1-221

When using parameterized functional options, you should keep in mind the
following:
„„ In list forms an attribute column associated with the parameterized functional
option is  displayed if the infobase stores and least one enabled value for this
functional option.
„„ If you want all attributes associated with functional options to be disabled by
default when you open a  form, you should set values of these parameters to
those missing in the infobase (an empty reference for catalogs or values of
dimensions with no records for information registers). In this case the func-
tional option is  set to False.
„„ If a  reference to a  group (if the type of a  functional option parameter allows
group creation) instead of a  reference to an element is  specified as the param-
eter, the system will behave as follows:
○○ If an attribute that stores a functional option value is used both for the
element and the group, the value of the functional option will be defined by
the value of this attribute.
○○ If an attribute that stores a  functional option value is  not used for a  group,
NULL is returned when a functional option value is obtained with the
following methods: GetFunctionalOption(), GetFormFunctionalOp-
tion(), and GetInterfaceFunctionalOption(). If a  functional option
that has been parametrized impacts the user interface, the system will
perceive it  as disabled (the functional option will be set to False).
„„ You can set a  snap to a  parameterized functional option for metadata objects
used as a  basis for commands. Commands for these objects are only displayed
in the command interface if there is at least one combination of functional
option parameters that makes the functional option value True. However,
you can use the SetInterfaceFunctionalOptionParameters() method
to set specific parameter values for functional options. In  this case command
visibility is  defined by the parameters you specify.
„„ A dynamic list automatically uses functional options used by the form. If the
attributes used in  the dynamic list query are disabled for the specified combi-
nation of functional option parameters, the corresponding data are not selected
and displayed in  the dynamic list and the attribute is  removed from the lists
of available attributes in  the Dynamic List Data Display Settings dialog box
(in 1C:Enterprise mode).

5.5.10.7. Use of Functional Options in  1C:Enterprise Script

Global context methods GetFunctionalOption() and GetInterfa-
ceFunctionalOption() return a  functional option value. The  difference is  that
the first method allows you to specify a  set of functional option parameters, while
the second method returns a  functional option value depending on the parameters
specified for the command interface.
1-222 1C:Enterprise 8.3. Developer Guide

Forms have their own method that returns an option value for parameters specified
within a  particular form – GetFormFunctionalOption().
If a  functional option value changes in  the database, the global command interface
and currently open forms are not automatically updated.
To update the global command interface, you should explicitly call SetIn-
terfaceFunctionalOptionParameters(). The command interface is updated
with regard to the new state of the functional options.
NOTE
If a  functional option value changes in  the database, the global command inter-
face and any currently open forms are not automatically updated. You should use
the RefreshInterface() method after writing the functional option values to
the database.
Note that setting functional options parameters (and running the RefreshIn-
terface() method) have the following consequences:
„„ For every form closing of all auxiliary forms is  called (and the corresponding
handlers are called).
„„ Forms that are denied closing are not closed.
„„ Main form elements are refreshed.
„„ If the main form was active at the moment of interface refresh, the main form
is  shown with new elements.
„„ If an auxiliary form was active at the moment of interface refresh, then:
○○ the open auxiliary form command will be executed, if this is  available when
the interface is  refreshed.
○○ otherwise, the main form elements are refreshed and the form is  displayed.
„„ If an auxiliary form opened with a  command that is  not related to the form
navigation panel was active at the moment of interface refresh, the main form
elements will be updated instead and the main form will be shown.
To refresh a  specific form you should reopen the form or call the SetFormFunc-
tionalOptionParameters() method. The steps above will work only for the
form, in  the context of which form setting the functional option parameters was
initiated.
You do not need to specify all parameters at once; you can change a value for
a  specific parameter or a  set of parameters. However, setting a  group of values
in  a single call is  more efficient.
To retrieve parameter values, you should call an appropriate function
(GetInterfaceFunctionalOptionParameters() or GetFormFunctionalOp-
tionParameters()) that returns the specified parameters as a  structure with the
parameter name used as a  key.
When opened, the form automatically uses parameters of the functional options set
for the command interface.
Chapter 5. Configuration Objects 1-223

5.5.11. Defined types

A defined type is a  special configuration object for defining a  type of data for
a  frequently used entity, or there is  high probability that it  will change when an
application is  implemented. A generic subsystem used to store contact information
may be used as an example. This  subsystem includes an information register that
stores this information. This  register contains a  dimension that specifies the object
for which such contact information is stored. A contractor, owner organization,
physical entity, etc. can be used as a dimension value. A type (named Cata-
logOfOrganizationsAndIndividuals) that describes this storage object does
not necessarily have to be a register dimension type. The contents of this type
may be changed in  the process of application implementation: new catalogs may
be added and the types that are no longer required may be excluded. If a  composite
type is used instead of the CatalogOfOrganizationsAndIndividuals type,
in  each instance where such an entity is  used the contents of types will have to
be changed everywhere. It  is  complicated, and there is  always a  chance that an
attribute with the required composite type will be forgotten. If a  composite type
is  used, it  is  only necessary to edit the composite type definition in  the applica-
tion customization process (and, of course, all application code fragments that
use this type). All attributes that have the CatalogOfOrganizationsAndIndi-
viduals type specified as their type will be changed automatically.
A defined type is  characterized by the following:
„„ It can be a  composite type.
„„ It cannot be part of a  chart of characteristic types value type.
„„ It cannot be part of a  composite data type of another attribute.
To describe a type with a script, use the DefinableType.<NameOfDefi-
nedType> construct.
NOTE
If you need to use an application with 1C:Enterprise legacy versions (under 8.3.3),
delete all definable types from the configuration.

5.5.12. Settings Storages

To save information about user settings that need to be saved between the sessions,
the platform offers you settings storages.
There are two types of settings storages:
„„ Standard storage is  used by the system by default and stores data in  system
tables of the infobase.
„„ Settings storages are special metadata objects that describe how data are stored
in  an infobase object. For example, this object could describe how to work with
settings stored in  a catalog.
1-224 1C:Enterprise 8.3. Developer Guide

The platform uses the following storages:

„„ System storage is a storage where the system stores all settings required to
operate the platform. These settings include settings of form sizes, print settings
of spreadsheet documents, etc. For a complete list of settings stored in the
system storage, see page 2-1199. A standard settings storage is always used
as a system settings storage. It means that data from the system storage are
always saved in  the system table of the infobase.
„„ Common settings storage is used to store various application settings.
The  platform does not write any settings to the storage independently. A devel-
oper should use this storage in  the 1C:Enterprise script, to save or restore user
application settings.
„„ Reports user settings storage contains reports user settings.
„„ Reports variants storage stores report variants.
„„ Form data settings storage stores form data. You can use this storage to
save data processor attributes, for example. Please note that you can select
a  different storage for each report or data processor.
„„ Dynamic list user settings storage is a storage system for storing the user
settings of dynamic lists.
When developing a  configuration, you can define custom settings storages of all
types, except the system storage. To do this, create a  settings storage object in  the
appropriate branch of the metadata tree and then select it  in  the required configu-
ration property. Properties of the Configuration object have the same names as the
storages listed above.
Storage data can be stored in  either the infobase system table or a  special infobase
object, e.g., a catalog or an information register. For example, you can create
a settings storage object in the configuration and use a configuration property
to indicate that this storage stores report settings. It  means that report settings are
saved in  an object, e.g. a  catalog, rather than in  the system table. In  this case you
can use common report settings or implement a  system of rights and exchange of
settings, etc.
A custom storage makes sense when you need to create a  special structure to store
settings or special procedures of settings management or else arrange settings
exchange inside the distributed database (see page 2-745) and in other similar
cases.
NOTE
It is  recommended to save settings in  objects that support an identification
method in which the identifying attribute can be converted into a string and
backwards with no data loss. An example would be a  catalog and the standard
Code attribute that is  unique in  the entire catalog.
Chapter 5. Configuration Objects 1-225

5.5.12.1. General Principles of Settings Storage Operation

SettingsStorage metadata object is used to store application settings of the
configuration. By implementing event handlers and creating object forms, you
can change the way you work with the settings, i.e. modify the storage location
(use developer-generated configuration objects instead of system tables) and visual
mechanisms of working with the settings.
Any number of settings storages can be defined in  a single configuration.
Settings storages can be used for both the programmed operations and programmed
and interactive operations. In  the first case the required functionality is  provided
through mandatory implementation of the SettingsStorage object module by the
handler:
„„ SaveProcessing contains an implementation of the Save() method.
This  handler has to save a  setting in  an object, e.g. a  catalog item.
„„ LoadProcessing contains an implementation of the Load() method.
This  handler has to retrieve settings from an object, e.g. a  catalog item.
IMPORTANT!
If a  required handler is  not implemented, the action it  performs is  unavailable.
For example, if you do not implement the SaveProcessing handler, you cannot
save settings.
When developing a storage, the developer determines how the storage object
is  identified, thus defining the parameter type. For example, if settings are saved
in  a catalog, you can use the Code field or the Ref value (of a  catalog item) as the
setting key.
If you want to work with the settings interactively (use forms to save and restore
the settings), you need to implement these forms and fill in the corresponding
properties of the SettingsStorage object (Save form and Load form).
IMPORTANT!
Implementation of forms for saving and restoring settings is mandatory for
interactive operations. You can also save and restore settings programmatically
without implementing these forms.
When a  user chooses to save or load the settings, the system gets a  corresponding
form for the settings storage object and displays it on the screen. For example,
when you save report settings, the system uses a  form to save a  metadata object
selected as the report settings storage (for a  particular report or the entire configu-
ration). The parameters passed to the form are described in more detail in a
description of the SettingsDescription object in  the Syntax Assistant.
If a  form is  created through a  wizard, the required parameters are automatically
added to the list of form parameters.
1-226 1C:Enterprise 8.3. Developer Guide

Forms should use the passed parameters and filter the settings list appropriately.
Thus, you should only display the settings for the setup object (e.g. a  report) speci-
fied in  the ObjectKey parameter.
If you select a  setting, the result of the form activities should be a  value of the
SettingsSelection type. The  SettingsKey of this value must contain a  key for
the selecting setting (e.g., a  catalog item code or another parameter that identifies
the setting), while the AdditionalProperties property should store additional
information possibly specified in  the form by the user:
Close(New SettingsSelection(SavedSettingKey));

IMPORTANT!
A setting cannot be saved in  the standard settings storage if the object key length
exceeds 256 characters or the settings key is  more than 128 characters long, or
the user name has more than 64 characters.

5.5.12.2. Creation of Metadata Object

If you want to create a  Settings storage, create a configuration object with the
same name. You can do it  in  the Common branch by selecting the Settings stor-
ages item.

Fig. 88.  Creating a  Settings Storage

5.5.12.3. Standard Settings Storage

In the 1C:Enterprise script a standard settings storage is represented by the
StandardSettingsStorageManager object. Having the same set of methods as
the SettingsStorageManager object, this object also implements the following
additional methods:
„„ GetList() – a  method that retrieves a  list of settings for the selected settings
object;
Chapter 5. Configuration Objects 1-227

„„ Delete() – a method that deletes a specific setting of the selected settings

object.
The standard storage save settings in  the system tables of the infobase.
The system settings storage takes a  string as a  settings object key and a  setting key.
It also takes any values that can be placed into a  value storage as settings.
NOTE
When you use the Save(), Delete() and SetDescription() methods of the
StandardSettingsStorageManager object, note that if the object to which
settings are related (e.g., a  form) has already been used in  the current session,
changes will be applied only in  the next session.

TIP
If you significantly change settings programmatically (for example, when you
copy the settings of one user to another user), it  is  recommended to prompt the
users to restart the client application.

5.5.12.4. How to Save Form Settings

A developer can control how form data are saved in  the settings. The  following
form properties should be used for this purpose when developing a  form:
„„ Save form data in  the settings: This property helps the form developer
enable a  functionality to save form data (a setting where data are saved can
be selected). If a  form has its save functionality enabled, it makes available
commands for saving or loading settings.
„„ Autosave form data in  the settings: This  property indicates settings are to be
auto-saved when the form is closed and restored when the form is opened.
It  is  irrelevant whether the settings list is  used or not.
If data saving is  enabled in  the form, you need to specify what form attributes are
to be saved (Save column at the Attributes tab of the form editor).
When settings are save, the full form name is  used as an object key. An object of
the Map type is  saved in  the settings. It  stores paths to the saved attributes as keys
and attribute values as values.

5.5.12.5. How to Save Report Settings

Report and external report objects have the following metadata properties: Variants
repository and Report variants storage. These properties indicate what storages
should be used to save report variants and settings, accordingly. If the storages
are not specified, storages indicated in the configuration properties are used. If
configuration properties do not indicate specific SettingsStorage objects either,
the system storage is  used.
A report form contains commands for saving and loading report variants and
settings.
1-228 1C:Enterprise 8.3. Developer Guide

If you need to save additional information in data composition settings or data

composition user settings, you can use AdditionalProperties properties of the
DataCompositionSettings and DataCompositionUserSettings objects.
The  AdditionalProperties property is  an object of Structure type.

5.5.12.6. Storing dynamic list settings

The user settings of dynamic lists are stored in  the storage specified in  configu-
ration properties (DynamicListsUserSettingsStorage). If configuration
properties do not specify a  settings storage, the system storage is  used.
The Auto save user settings property of an attribute that refers to a  form of type
DynamicList controls the function to automatically save the user settings of
a  dynamic list. If the property is  set to True, user settings are automatically saved
when the form is  closed and are loaded when it  is  opened.
A dynamic list form provides the user settings save and load commands.
A dynamic list also provides a command to specify standard settings. If this
command is executed, the dynamic list will include settings from property
List.SettingsComposer.Settings.
The OnUpdateUserSettingSetAtServer event can be called for a  dynamic list
in  the following cases:
„„ When a  dynamic list form is  opened.
„„ When the user settings editing is  concluded (if the settings have been changed).

5.5.12.7. Settings Storage Development Procedure

Below is  a recommended procedure of developing a  settings storage:
1. Determine the type of storage to be used (see the beginning of the section). For
example, you want to implement a  settings storage for configuration form data.
2. Make a  list of metadata objects that will use the storage and a  list of data to be
stored, define the data structure and types. This  information helps you select an
appropriate metadata object to store the settings.
3. Use information from step 2 to create an object (and its structure) for storing
settings. Let us assume the settings will be stored in  catalog items. Since in  this
case the structure of data to be saved is  heterogeneous, it  is  inconvenient to
implement separate sets of attributes to store settings from each form; therefore,
the settings will be stored in  a catalog attribute of ValueStorage type.
4. Create an object of ValueStorage type and implement save and load forms for
it. This  ensures you can use interactive operations when saving and restoring
the settings.
5. Implement event handlers associated with saving and restoring the settings for
the newly created ValueStorage object. If you do not perform this action,
Chapter 5. Configuration Objects 1-229

settings read/write operations will fail. To solve this issue, implement Save-
Processing and LoadProcessing event handlers in  the module of the newly
created ValueStorage object.
6. The objects selected at step 2 (or in the configuration properties) have their
properties filled in, thus indicating what storages will be used to save the
settings. In this example you need to fill in the Form data settings storage
configuration property with a  reference to the object created at step 4.
7. Events handlers associated with saving and restoring settings in application
objects are implemented, if necessary.

5.5.12.8. Working with Settings Storage from the Script

This example reviews how the current user’s settings can be copied by other users
of the system. SystemSettingsStorage is  used as a  source of settings.
NOTE
The example below is  not complete. It  simply demonstrates how to work with
standard settings storage.
A list of user names is transferred as an array with the help of the CopySet-
tings() procedure parameter.

Procedure CopySettings(ListOfUsers)

SettingsDescription = New SettingsDescription;

SettingsSelection = SystemSettingsStorage.Choose();
While SettingsSelection.Next() Do

For Each User From ListOfUsers Do

SettingsDescription.Presentation = SettingsSelection.Presentation;
SettingsStorage.Save(SettingsSelection.ObjectKey,
SettingsSelection.SettingsKey, SettingsSelection.Settings, SettingsDescription, User);

EndDo;

EndDo;

EndProcedure

5.5.13. Common Forms

The common forms mechanism makes it  possible to use forms accessible from any
module of the current configuration. For details on how the form editor works see
page 2-937.
If you want to include a command that would open a common form in the
command interface, you can do this by using the Use standard commands property.
1-230 1C:Enterprise 8.3. Developer Guide

The  command opening a  common form will be included in  the command inter-
face of the subsystems that own the common form.
If a  common form is  included in  a functional option and the option is  disabled,
the common form standard command will not be shown in  the command interface.
If you create a  common form that will be used as a  report form, a  report or variant
settings, setting the Use standard commands property for this form is  not recom-
mended.

5.5.14. Common Commands

A developer can use this branch to create commands that are not object-specific
and are used to perform actions on objects which do not use standard commands.
For a  description of the command interface see page 1-83. For a  description of
commands see page 1-266.

5.5.15. Command Groups

A developer can use this branch to create custom command groups. Location of
the created group in the command interface is defined by the command Group
property. A command group can be located:
„„ In the navigation panel
„„ In the form navigation panel
„„ In the actions panel
„„ In the form command bar
For a  description of the command interface see page 1-83. For a  description of
commands see page 1-266.

5.5.16. Common Templates

The common templates mechanism (print forms, report forms, references, etc.) can
be used to create print form templates accessible from any module of the current
configuration.
For details on how the spreadsheet document editor works see page 2-996.

5.5.17. Common Pictures

The Designer makes it  possible to use graphic images or pictures in  a configura-
tion. Pictures may be used in  some controls, forms and templates. They may also
be called using the 1C:Enterprise script.
If a picture is used as an icon in a menu, toolbar, spreadsheet document, etc.,
it is important to specify proper dimensions for the picture so that it displays
correctly.
Chapter 5. Configuration Objects 1-231

The following picture sizes are recommended:

„„ Max 16x16 pixels for icons
„„ Max 14x14 pixels for table boxes
„„ Max 9x9 pixels for pictures of an edit field selection button
„„ Max 48x48 pixels for pictures used as subsystem presentations
TIP
If a  picture is  to be used in  several places, its size should be as small as possible.
Use the Configuration Picture Library window to work with pictures. Select
Common pictures in  the Configuration window and then select All Images from the
context menu.
The picture list maintenance window will open (see fig. 89).

Fig. 89.  Picture Library

To add a  new picture, press the Add button. A new window will open, where you
can select a  picture from a  file or open the picture editor and create a  new picture.
You can also use this window to select or change the transparent background for
a  picture. To select an existing picture, press the Select from file button and select
the file containing the existing picture. In  the 1C:Enterprise system, you can use
BMP, GIF, JPEG, PNG and TIFF picture formats, as well as icons and metafiles
(WMF, EMF).
TIP
For pictures used as interface icons (for the recommended picture sizes, see the
beginning of the section), it  is  recommended to use formats that support lossless
compression (PNG and GIF), prevent distortion and minimize client/server traffic.
Specify the name that will be used to select this picture by means of the
1C:Enterprise script.
1-232 1C:Enterprise 8.3. Developer Guide

Fig. 90.  Picture Properties

It is recommended to use transparent background for a picture to fit well into

a  control or a  form. To do this, when editing the picture select any color that is  not
used in  the picture as a  background color, create an image and save the picture.
You can specify any color for an existing picture. If the color is  transparent, you
can see components of the form that are covered by the picture.
To set a transparent background, click the Set transparent background button.
The  mouse cursor will change its appearance. Move it  to the component of the
picture that you want to make transparent and left-click it. The selected color
becomes transparent.
To remove transparency, click the Remove transparency button.
The Set transparent background and Remove transparency buttons are only avail-
able for the following picture formats: BMP, JPEG and TIFF. They are not available
for pictures of other formats.
You can also perform similar actions using the Select link in  the Picture property.
The  picture selection window will open.

Fig. 91.  Picture Selection

Chapter 5. Configuration Objects 1-233

Click the Edit button to edit the picture. The  picture editor will open (for details see
page 2-1012).

5.5.18. XDTO Packages

The XDTO mechanism is  a universal data presentation method that interacts with
various external data sources and software systems. For details on how to use the
XDTO mechanism see page 2-789.

5.5.18.1. Import of XML Schemas Into XDTO Global Factory

In order to import an XML schema from an .xsd file into the XDTO global factory,
select the XDTO branch in  the configuration tree and click Import XML Schema
in  the context menu.

Fig. 92.  Import XML Schema

Once the required .xsd file has been specified, the availability of the XDTO pack-
ages must be checked in the configuration tree, with the namespaces matching
those imported from the file. If these packages are available, a  list will be displayed
and you will be prompted to specify the packages to be updated (the existing pack-
ages are not updated by default).

Fig. 93.  Namespace Selection

1-234 1C:Enterprise 8.3. Developer Guide

The import procedure is  then executed, resulting in  the addition of new XDTO
packages to the configuration tree, while packages specified for update will be
updated.

5.5.18.2. Export of Configuration XML Data Schemas

To export an XML schema corresponding to configuration data types (without
consideration of the XDTO packages created in  the configuration tree) to an .xsd
file, specify the XDTO branch in the configuration tree and execute the Export
configuration data XML Schema command in  the context menu.

Fig. 94.  Export of Configuration Schema

Once the directory has been selected and the file name specified, the XML schema
is  exported to the specified file.

5.5.18.3. Export of XDTO Package XML Schema

To export an XML schema corresponding to the existing XDTO package to an .xsd
file, select the relevant XDTO package in  the configuration tree and click Export
XML Schema in  the context menu (see fig. 95).
The dumped XDTO package will be checked. If any errors are detected, the rele-
vant messages will be displayed in  the message window and the export procedure
will be interrupted.
If the check is  successful, you will be prompted to choose the directory and .xsd
file name and then the XML schema will be exported to the specified file.
Chapter 5. Configuration Objects 1-235

Fig. 95.  Export of XDTO Package XML Schema

5.5.18.4. Check of XDTO Packages

To check an XDTO package, specify the relevant XDTO package in  the configura-
tion tree and execute the Validate package command in  the context menu.
As a  result, the XDTO package model will be checked (for a  description of check
rules see page 2-808).
If any errors are detected, the relevant messages will be displayed in  the message
window.

5.5.18.5. XDTO Package Editing Window

XDTO packages can be edited in  the XDTO package editing window.

Fig. 96.  XDTO Package Editing Window

1-236 1C:Enterprise 8.3. Developer Guide

When a new XDTO package is added to the configuration tree, the XDTO
package editing window opens automatically.
To open the editing window for an existing XDTO package, specify the relevant
XDTO package in  the configuration tree and execute the Open package command
in  the context menu.
XDTO Package Hierarchical Structure
The XDTO package editing window contains the hierarchical tree of the XDTO
package.
The XDTO package ID containing the corresponding namespace URI is  located at
the tree's root.
The first hierarchy level can include the following package elements:
„„ Import directives – a  list of import directives. An import directive is  a reference
to another package containing the types referenced by this package. When you
are using the 1C:Enterprise script to work with this XDTO package, this list
of import directives will be available as a  XDTOPackageCollection object
stored in  the Dependencies property of the XDTO package;
„„ Value types – a  list of XDTO value types stored in  the XDTO package.
„„ Object types – a  list of XDTO object types stored in  the XDTO package.
„„ Properties – a  list of XDTO package properties. It  represents declarations of
objects/values that can be the root items of XML documents, belonging to the
namespace URI of this XDTO package.
„„ Each XDTO value type is described by the hierarchical structure and can
contain the following items:
○○ Pattern describes one XDTO facet of the Pattern type.
○○ Enumeration describes one XDTO facet of the Enum type.
Each XDTO object type is described by the hierarchical structure which can
contain a  set of object properties.

XDTO Package Properties

XDTO package properties are edited in  the properties palette.
If the properties palette is  open for an XDTO package specified in  the configu-
ration tree, it will contain the following properties: Name, Synonym, Comment,
Subsystems and Namespace URI. In  addition, the properties palette will contain
the Package reference which can be used to switch to the XDTO package editing
window (see fig. 97).
If the properties palette is open for the XDTO package specified in the XDTO
package editing window (root item), it  will only contain the Namespace URI prop-
erty. This  property defines the namespace URI for the XDTO package which owns
all types defined in  this package.
Chapter 5. Configuration Objects 1-237

Fig. 97.  XDTO Package Properties

Import Directive Properties

Import directive properties are edited in  the properties palette. For import direc-
tives, the properties palette only contains the Namespace property. This  property
sets the namespace URI for the imported package.

Fig. 98.  Import Directive Properties

XDTO Value Type Properties

XDTO value type properties are edited in  the properties palette.

Fig. 99.  XDTO Value Properties

1-238 1C:Enterprise 8.3. Developer Guide

For XDTO value types, the properties palette contains the following properties:
„„ Name – a  name of the type for a  XDTO value;
„„ Base type – a  base type for this type of XDTO value;
„„ Variant – a  simple type variant (primitive type, list, union). If a  value is  set,
it  has to match the Item Type and Union Types values;
„„ Item type – a  list item type in  cases where the XDTO value type is  defined by
the list. All facets and Types of Subordinates must be null;
„„ Merger types – a  list of types making up a  union, in  cases where the XDTO
value type is  defined by a  union. Only XDTO value types can become unions.
All facets and the Item Type property must be null;
„„ Length – the length facet;
„„ Minimum length – minimum length facet;
„„ Maximum length – maximum length facet;
„„ Space characters – white space facet;
„„ Minimum including border – facet of the minimum, including limit;
„„ Minimum excluding border – facet of the minimum, excluding limit;
„„ Maximum including border – facet of the maximum, including limit;
„„ Maximum excluding border – facet of the maximum, excluding limit;
„„ Total digit number – facet of the total number of digits;
„„ Number of fraction digits – facet of the number of fraction digits.

XDTO Object Type Properties

XDTO object type properties are edited in  the properties palette.

Fig. 100.  XDTO Object Properties

For XDTO object types, the properties palette contains the following properties:
„„ Name – a  name of the XDTO object type.
„„ Base type – a  base type for this XDTO object type. It  can only be an XDTO
object type.
Chapter 5. Configuration Objects 1-239

„„ Open – this flag specifies if the XDTO object type is  open. This  property indi-
cates whether the XDTO object instance can contain additional properties not
defined in  its type.
„„ Abstract – this flag specifies if the XDTO object type is  abstract.
„„ Mixed – this property indicates whether the corresponding XDTO object
contains mixed contents. If the Mixed property is set to True, then the
Sequenced value will always be True, because mixed contents cannot be
modeled without using an XDTO sequence.
„„ Ordered – this flag specifies if the order of items that represent property
values strictly corresponds to the order of properties in  the XDTO object type.
If the Ordered property is  set to False, then the input sequence order of XML
elements is not controlled and the output is defined by the sequence order
of properties, provided that the value of the Sequenced property is  not True.
„„ Sequenced – this property shows if an instance of the relevant XDTO object
contains an XDTO sequence. This flag has the True value in those cases
where the sequence order of the nested XML elements cannot be unequivo-
cally defined by the sequence order of the properties in  the type or the relevant
XDTO object has mixed contents. Use the XDTO sequence to expressly set
the order of items in the way they are represented in the XML document.
The  order of the nested items corresponds to the order of properties for objects
of the types, for which the Sequenced property is  set to False.

Properties of XDTO Object Type Properties

Properties of XDTO object type properties are edited in  the properties palette.

Fig. 101.  XDTO Type Properties Palette

For XDTO object types, the properties palette contains the following properties:
„„ Name – a property name. Property names should be unique within a single
XDTO object type;
1-240 1C:Enterprise 8.3. Developer Guide

„„ Type – a  property type. It  can be both a  XDTO value type and XDTO object
type;
„„ Minimum number – a  minimal number of property values. The  minimal number
of property values can take values >= 0. Naturally, the Minimum number value
must be less than or equal to the Maximum number value (provided that the
Maximum number is  not equal to -1);
„„ Maximum number – properties of the XDTO object type can be defined as
containing single or multiple values. A property is considered to contain
a  single value if the Maximum number property is  equal to 1. If the value of the
Maximum number property is  greater than 1, it  is  considered that this property
can contain multiple values. These properties are modeled as lists in  the object
structure. The Maximum number property shows the maximum number of
property values. Maximum number > 1 can be set only for properties represented
in  XML element form;
„„ Can be empty – indicates whether the property can take an Undefined value.
The  Can be empty property equal to True can be defined only for properties
with the Item form of representation. If Maximum number > 1, an Undefined
value is  allowed for the property values list item;
„„ Fixed – specifies if the property value is  fixed. If this is  set to True, the fixed
value itself can be obtained through the Default property;
„„ Default – a  default property value. The  default value type can only be a  XDTO
value type. In  terms of types, this value must be compatible with the property
type (i.e. be of the same type as the property or of the inherited type). If a  single
value is  allowed for the property when an XDTO object is  created, it  takes the
default value. For properties with multiple values, a  list of values is  initially
empty, irrespective of the fact that the default value is  defined;
„„ Form – is the form of property presentation in XML. It can be Text, Item
or Attribute. If the form of presentation is  Attribute or Text, the value of the
Maximum number property cannot exceed 1. If the property has the Text value,
then the value of the Minimum number property will also be equal to 1. Only
one property of a  separate type can have its form of presentation set to Text,
while all other properties must have their form of presentation set to Attribute;
„„ Local name – a  local name used for property presentation. For properties with
the Text presentation form it  is  an empty string.
Global Property
Properties of a  global property are edited in  the properties palette (see fig. 102).
The properties palette for a  global property contains the following properties:
„„ Name – a global property name. Global property names should be unique
within a  single XDTO object type.
„„ Reference – a  reference to a  root definition of a  package property.
„„ Type – a  global property type.
Chapter 5. Configuration Objects 1-241

„„ Minimum number – a  minimal number of property values. If Minimum number

is  0, the property value might not be set.
„„ Maximum number – a maximum number of property values. If Maximum
number is  -1, the number of property values is  unlimited.
„„ Can be empty – indicates whether the property can take an Undefined value.
„„ Fixed – specifies if the property value is  fixed.
„„ Default – a  default property value. The  lexical representation of the property
value must follow the rules of the property type check.
„„ Form – is  the form of property presentation in  XML. It  can be Text, Item or
Attribute.
„„ Local name – a  local name used for property presentation.

Fig. 102.  Properties Palette for a  Global Property

5.5.19. Web-services
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.
For details on how to use the Web service mechanism see page 2-819.

5.5.19.1. Addition of Web Services

To add a  Web service to the configuration tree, select Common  – Web-services
and click Add in  the context menu.
This command opens a  Web service editing window (see page 1-59).
Specify the following parameters at the Other tab of the Web service editing window:
„„ 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 to
which it  belongs;
1-242 1C:Enterprise 8.3. Developer Guide

„„ XDTO packages – a  list of XDTO packages with the types that can be used as
returned value types for operations and parameter types of Web service opera-
tions;
„„ Publishing file name – a  name of the Web service description file located at
the Web server (for details on Web service publication see "1C:Enterprise 8.3.
Administrator Guide").
To get access to a web service, you need to use the address in the following
format: <Web server host name>/<Virtual directory name>/ws/<Web service name>
or <Web server host name>/<Virtual directory name>/ws/<Web service address>.
So if a  virtual directory is  named DemoWS, the web service is  named DemoOper-
ationWS in  the Designer while the address is  DemoWorkWS, and this web service
can be accessed using two addresses simultaneously (from a  local machine): http://
localhost/DemoWS/ws/DemoOperationWS or http://localhost/DemoWS/ws/DemoWorkWS.
The tab also contains the Module button that opens a Web service module for
editing.

5.5.19.2. Web Service Hierarchical Structure

Every Web service described in the configuration tree can contain a set of
operations. Each operation must have a  corresponding export procedure, described
in  the Web service module.

Fig. 103.  Web Service Description

Additionally each operation can contain a set of parameters with names corre-
sponding to the names of the procedure parameters describing this operation.
Chapter 5. Configuration Objects 1-243

5.5.19.3. Web Service Operations

Use the Operations tab to add Web service operations. Use the properties palette to
edit the operation properties.

Fig. 104.  Web Service Operation Property

Return value type – a  value type returned by the Web service operation. It  can be
an XDTO value type or XDTO object type.
Value can be blank – indicates whether the returned value can have an undefined
value.
In transactioned – indicates whether or not the code of the Web service module
will be executed in  the transaction. If the property is  set, the transaction will start
automatically when the Web service is  called and upon completion, the transac-
tion will be 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 – a  name of the Web service module procedure that will be executed
when this property is  called.

5.5.19.4. Operation Parameters

Use the Operations tab to specify parameters for a  Web service operation. Use the
properties palette to edit the parameter properties (see fig. 105).
Value type – a  value type of the Web service operation parameter. It  can be an
XDTO value type or XDTO object type.
Value can be blank – indicates whether the operation parameter value can take an
undefined value.
1-244 1C:Enterprise 8.3. Developer Guide

Fig. 105.  Operation Parameter Properties

Transfer direction – defines the direction of data transfer using this parameter.
Available values:
„„ Input – means that the parameter can be used for data transfer to the Web service
only;
„„ Output – means that the parameter can be used for both transfer and retrieval of
data to/from the Web service.

5.5.19.5. Selection of System-Defined Types

If you want to use types defined by the 1C:Enterprise system in  the Web services
(e.g., in  the parameters and values returned by the operations), you need to define
XDTO packages in  the configuration and specify a  set of platform packages that
contain these types, in  the relevant lists of imported packages (the Import directives
property). You can find namespace URI to specify a  particular type in  the relevant
article on an object of this type in  the Syntax Assistant.

5.5.19.6. Web Service Publication

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

5.5.20. WS-references
1C:Enterprise can use third-party Web services by using static references created
in  the configuration tree.

5.5.20.1. Addition of WS References

To add a  static reference to an external Web service to the configuration tree, select
the WS reference branch and click Add in  the context menu or the Actions menu.
Chapter 5. Configuration Objects 1-245

Fig. 106.  Adding a  WS Reference

You should type the URL of the added Web service description in the opened
window, e.g. http://users.v8.1c.ru/ws/products.1cws?wsdl.
NOTE
When you add a  WS reference, note that 1С:Enterprise deletes the final char-
acter "/" from the URL entered. 1С:Enterprise therefore considers the URL
http://localhost/ws/ws-service/?wsdl and the URL http://localhost/ws/ws-service?wsdl
to be identical.

5.5.20.2. WS Reference Hierarchical Structure

The hierarchical structure of a  WS reference can be viewed in  the WS reference
viewing window. Values of the reference element properties can be viewed in  the
properties palette.
In order to open the WS reference viewing window, select the required WS refer-
ence in the configuration tree and click Properties in the context menu. Then
use the WS-reference property in  the properties palette to open the WS reference
viewing window.

Fig. 107.  WS Reference

The viewing window contains the hierarchical structure of the WS reference,

displayed as a  tree.
The first hierarchy level can include the following elements:
„„ Data model – contains a  list of XDTO packages describing the structure of the
types used by the Web services to which this WS reference refers;
„„ Web-services – a  list of Web services to which this reference refers.
1-246 1C:Enterprise 8.3. Developer Guide

You can view data model structure and properties in  the same way as you view
XDTO packages (see page 1-236); however, you cannot edit properties of packages
displayed in  the WS reference viewing window.
You can view WS reference structure in  the same way as you view Web services;
however, each Web service has a  list of supported connection points that also have
a  list of operations and their parameters.

Fig. 108.  Web Service Structure

Using different Web service connection points allows you to run operations using
different protocols.

5.5.21. Style Elements

Style elements configuration objects are used to ensure consistency in  formatting
various form elements in  cases where 1C:Enterprise automatic formatting is  not
sufficient. For example, you might want to highlight labels in  configuration forms
using the same color. In  this case it  is  convenient to create a  style item, assign
it  a color and use the created item to set the text color for a  form element.

Fig. 109.  Using Style Items

Style elements can be of three types:

„„ Color
Chapter 5. Configuration Objects 1-247

„„ Font
„„ Border
NOTE
System style items cannot be selected as values of custom style items.
The font selection dialog box used at the thin client contains a  list of fonts that
includes fonts installed at the machine and special fonts enclosed in  angle brackets
(<>). If you select <Font>, the system will use a  font of the 1C:Enterprise interface,
while all other fonts will correspond to the fonts existing in  the operating system.
A list of <Font> sizes starts with "<>". Selecting this font size (its value is  0) means
that the font size will match that of the 1C:Enterprise interface. The  font effects
(bold, italic, etc.) default to the style settings, but can be customized without any
limitations. If you select another font, all changes to the font size and effects are
reset to the default values.
You can access the style item value programmatically, using the Value property.
Example:
Metadata.StyleItems.NegativeColor.Value

5.5.22. Languages
Languages configuration objects are used to create program interfaces in  different
languages. Each configuration object of the Languages type has a  separate reserved
string for the metadata attributes that can be represented in  different languages.
Let us review a  sample form for the Items catalog item. For the Russian language
the form labels look like the following:

Fig. 110.  Form in  Russian

1-248 1C:Enterprise 8.3. Developer Guide

If the Languages branch contains more than one object (e.g., Russian and English)
and you want to change the language, select Configuration – Design Language.
Select the configuration viewing language in the opened language selection
window.

Fig. 111.  Selection of Designer Language

The same can be done using the language selection button located on the status
bar to the right of the CAP and NUM buttons (the right bottom corner of the main
Designer window).
The Designer replaces label text with the text in  the selected language.

Fig. 112.  Form in  English

Of course, the label text has to be entered in  advance for each control. To enter the
text in  the properties palette of the Label control, click the magnifier button in  the
Title property (Text or Synonym, depending on the type of control), see fig. 113.
The  Strings in  Different Languages window will open.
TIP
A configuration can have any number of languages. However, there is  no need
to create Languages objects "just in  case", since they may be created at any time.
Chapter 5. Configuration Objects 1-249

Fig. 113.  Strings in  Different Languages

Language code property contains the language code, e.g., EN for English.
If two or more Languages objects are defined in  the configuration, the text editing
button (a magnifier icon) will be displayed for the Synonym and Title properties
of the control.
The first language object is created by the system according to the language
(country) selection for a  new infobase.
To create a text representation of an attribute to be displayed in the form, the
following rules are used:
„„ The title of the displayed object is  retrieved in  the configuration language of
the current user. If the title is  specified, it  is  the one that is  used.
„„ The system attempts to retrieve the synonym of the displayed object in the
configuration language of the current user. If the synonym is specified,
it  is  the one that is  used.
„„ Subsequent actions depend on the type of the displayed object:
○○ For standard attributes, a representation in the platform localization
language is  retrieved;
○○ For objects created by the application developer, the object name is  used as
it  is  specified in  the configuration (including its language).
IMPORTANT!
If the language code in  the Language code property is  changed, texts in  the Syn-
onym or Title properties will be "lost" (they will be stored for the previous code
value). The  texts will be "restored" when the previous code value is  specified.
For the purpose of text editing and localization (creating an interface in  a different
language), use the Edit interface texts mode (see page 2-1021).
If the application is  to be used on mobile devices, language codes shall be specified
as per ISO 639 (http://www.iso.org/iso/home/standards/language_codes.htm). Otherwise,
a  warning will be displayed during the configuration check.
1-250 1C:Enterprise 8.3. Developer Guide

5.6. COMMON PROPERTIES OF CONFIGURATION OBJECTS

This section describes common properties of configuration objects.

5.6.1. General Properties

Most configuration objects have the following properties which appear in the
General category:
„„ Name: The  name of the configuration object. The  name must consist of a  single
word, begin with a  letter and contain no special characters other than underscore
("_"). The  1C:Enterprise script tools access and manage configuration object by
its name. Names of configuration objects must not be identical to the reserved
words of a  query language (see page 1-445 for a list of reserved words).
„„ Synonym: In addition to the name, you can also specify a synonym. If the
configuration is  to be used in  different languages, synonyms in  the languages
used should be specified. When working with the 1C:Enterprise system,
a  synonym will be displayed in  various selection lists, window titles and label
texts, when interfaces are generated, taking the current language into account.
A synonym has no restrictions on the use of characters. If no synonym is  speci-
fied, the name is  selected.
NOTE
The name or synonym displayed to the user are also called the presentation of
the configuration object.
„„ Comment: An arbitrary character string. As a rule, it's drilled down and
explains the name of an object. When shown in various lists (for example,
in  the list of catalogs for selection of the desired catalog), a  comment is  shown
in  parentheses immediately after the presentation of the configuration object.

5.6.2. Metadata Object Presentation

Various object presentations are allowed for many configuration objects. This  func-
tionality allows the developer to set a  presentation of standard commands, their
tooltips and form titles.

Fig. 114.  Object Presentation

Chapter 5. Configuration Objects 1-251

„„ Object presentation (for a  register – Record presentation):

○○ An object name (e.g., Account).
○○ This is  used in  a standard command presentation (creation of an object).
„„ Extended object presentation (for a register – Extended record presentation)
is used to generate a title for the object form. For example, Organization
account.
„„ List presentation:
○○ A name for a  list of objects (e.g., Accounts).
○○ This is  used in  a standard command presentation (a command that opens an
object list).
„„ Extended list presentation is used to generate a title for the list form (e.g.
Organization accounts).
„„ Extended presentation – a  title of a  report or data processor form (e.g., Report
on mutual settlement of accounts).
„„ Explanation is  used to generate tooltips for standard commands (e.g., Accounts
of my organizations).
„„ Picture – a  picture that represents a  subsystem in  the sections panel.
Please note that you only need to fill in  the properties associated with the object
and list presentations if you want to specify more information in  addition to the
data displayed by default.
For example, you have a  Goods catalog (Name of the metadata object is  Goods,
Synonym of the metadata object is  Goods) that can contain goods and services as
its items. However you want to use singular in  command texts ("Create product")
and do not want to include services data as it makes commands longer. At the
same time, you want to show the user that the relevant object form can be used to
edit both goods and services. In  this case you can enter Product text in  the Object
presentation property and Product (service) in the Extended presentation property.
Then the command for creating a Goods catalog item will look like Product:
Create, while the form will have a  Product (service) title.
For details on which of the above properties belong to particular metadata objects
see page 2-1195. You can also read about the rules of generating texts for standard
commands, command tooltips and form titles.

5.6.3. Custom Presentation of Data

The standard data presentation provided by the system may be unacceptable for
the user. This can happen, for example, when the system is operated by users
speaking different languages and system objects contain all the necessary infor-
mation in different languages as well. For instance, let the products have two
names: in Russian and English. But the text should be displayed depending on
the session localization code. In addition, the presentation should be generated
1-252 1C:Enterprise 8.3. Developer Guide

in the required language in every location where the object presentation

is  formed: in  a dynamic list, report, etc.
To implement this, the developer can use a  special feature which allows him to
define the attributes involved in generating the presentation and to describe an
algorithm based on which the object presentation will be generated.
This is  available for the following configuration objects:
„„ Exchange plans
„„ Catalogs
„„ Documents
„„ Charts of characteristic types
„„ Charts of accounts
„„ Charts of calculation types
„„ Business processes
„„ Tasks
„„ Tables of external data sources
The presentation is  created in  two steps: defining the attributes involved in  gener-
ating the presentation and then generating the presentation itself.
The attribute list is defined through the PresentationFieldsGetProcessing
event handler in  the respective object manager. The  handler is  called during the
first attempt to get the presentation of a  selected object, and the result is  saved
for the current session. Names of attributes that will be involved in  generating the
presentation should be specified in  the Fields array of this handler. If the Stand-
ardProcessing parameter in  the handler is  set to the True value, then after the
handler completes its operation, the Fields array will be cleared and filled with the
fields used to create a  standard presentation of this object. If not, the system will
only use the values put into the Field array.
NOTE
The examples below are not complete. They simply illustrate how to work with
custom presentations.
For instance, the Goods catalog has the following attributes: RussianDescrip-
tion, EnglishDescription and Article that are to be used in generating
a  presentation. In  this case the handler of the getting presentation fields (in the
Goods catalog manager module) will look as follows:

Procedure PresentationFieldsGetProcessing(Fields, StandardProcessing)

Fields.Add("RussianDescription");
Fields.Add("EnglishDescription");
Fields.Add("Article");
StandardProcessing = False;

EndProcedure
Chapter 5. Configuration Objects 1-253

When it is necessary to get a presentation, the system calls the Presenta-

tionGetProcessing event handler in  the respective object manager. The  values
of the attributes involved in  generating the presentation are passed to this handler.
The  program code located in  this handler generates a  presentation text.
CAUTION!
The PresentationGetProcessing event handler is called whenever the
presentation of any infobase object is  required. Redundant data or incorrect data
selection for generating the presentation can significantly slow down system
operation.
The PresentationGetProcessing event handler creates the presentation and
returns it  via the Presentation handler parameter. The  data required to generate
the presentation is  passed through the Data parameter. The  Data parameter is  a
structure where the key is the attribute name and the value is the value of the
attribute for the current object. If the StandardProcessing parameter is  set to
True, the system will attempt to generate a  standard presentation for the current
object based on data passed. In case the Data parameter contains no attribute
required to generate a  standard presentation, then the presentation will be an empty
string.
Let us review a  sample creation of a  presentation for the Goods bilingual catalog.
Procedure PresentationGetProcessing(Data, Presentation, StandardProcessing)

StandardProcessing = False;
SessionLocaleCode = Upper(CurrentLocaleCode());
If Find(SessionLocaleCode, "RU") <> 0 Then
Text = Data.RussianDescription;
ElseIf Find(SessionLocaleCode, "EN") <> 0 Then
Text = Data.EnglishDescription;
Else
Text = Data.RussianDescription;
EndIf;
Presentation = Text + "(" + Data.Article + ")";

EndProcedure

Please note that a 1C:Enterprise script error in the PresentationGet-

Processing handler may sometimes lead to abnormal termination of application.

5.6.4. Standard Attributes

If you need to override interface properties (such as a  synonym, fill checking, etc.)
for standard attributes (e.g., Code, Description, Parent) and standard tabular
sections (e.g., ExtDimensionTypes, BaseCalculationTypes) of application
objects at the configuration level, you can set up these properties.
1-254 1C:Enterprise 8.3. Developer Guide

Fig. 115.  Standard Attributes

To do this, you can use commands that open lists of standard attributes and tabular
sections in  the properties palettes of certain objects (see fig. 115). These commands
are available for the objects that own standard attributes and tabular sections.
You can use the properties palette to override some properties of standard attrib-
utes so that they fully meet the requirements of the application task at hand.
For example, you can set Contractor as a  synonym for the Owner property of the
Accounts catalog. Then this attribute (Owner) will be represented as "Contractor:"
in  all forms by default.
If properties of a standard attribute or tabular section are not specified, default
properties of standard attributes are used instead.
A standard attribute has virtually the same set of properties as any other attribute;
however, you cannot modify the following:
„„ The standard attribute name
„„ The standard attribute type
„„ The standard tabular section name
„„ The standard attribute indexing
IMPORTANT!
If a  standard attribute has a  description, its name remains unchanged, i.e. it  does
not change calls to the attribute from the 1C:Enterprise script and the query
language.

5.6.5. Predefined data

5.6.5.1. Overview
Predefined data means the items of application objects created in Designer.
They can be called directly by name, without a preliminary search required.
If a  certain data element will be constantly needed and will require simple access
from program code, this serves as a  reason to create predefined data. For instance,
Chapter 5. Configuration Objects 1-255

the predefined element Service can be created in  the Goods catalog. To call this
element, execute Catalogs.Goods.Service. Individual elements and groups
of elements may be predefined. Groups can be created if predefined elements are
created in  hierarchical objects, such as a  hierarchical catalog. Predefined data can
be created:
„„ For catalogs (see page 1-280)
„„ For charts of accounts (see page 1-652)
„„ For charts of characteristic types (see page 1-309)
„„ For charts of calculation types (see page 1-665)
When a predefined element is created in Designer, the possibility to create or
update the data elements related to it  is  defined by a  combination of the following
two values:
„„ Configuration object property value PredefinedDataUpdate. Is set
in Designer;
„„ Object property value in  the infobase. Use 1C:Enterprise mode and methods
GetPredefinedDataUpdate() and SetPredefinedDataUpdate () to
obtain and set the value for this property.
The property can have three values:
„„ Do not update automatically: in  this case the system does not create or update
a data element when predefined data is created or modified. However,
it should be noted that if such a property is set for a configuration object,
an exception may be generated when predefined data is called since a data
element connected with a  predefined element is  absent;
„„ Update automatically: in  this case, the system automatically creates new data
elements (or updates the existing ones) for new (or changed) predefined data;
„„ Auto: the system defines the need for an update automatically. No update
is  performed in  the following cases:
○○ If the configuration object properties (metadata) have the Predefi-
nedDataUpdate property set to Do not update automatically; the value set
in  1C:Enterprise mode is  irrelevant.
○○ If the configuration object properties (metadata) have the Predefi-
nedDataUpdate property set to Update automatically, and Do not update
automatically is  set via method SetPredefinedDataUpdate().
○○ If Auto is set in the metadata and 1C:Enterprise mode, and the action
is executed in the subordinate node of a distributed infobase (see page
2-772).
The action to be taken by the system is defined via the AND operation between
a  configuration object property and a  property of an object specified in  1C:En-
terprise mode. It should be remembered that Auto values do not participate
in  defining an action (create or do not create). First, they are resolved into one of
1-256 1C:Enterprise 8.3. Developer Guide

two values: Do not update automatically or Update automatically, and these values
are then used in  the AND operation.
A data element is  connected to a  predefined data element via PredefinedData-
Name. This  property facilitates the following:
„„ Connecting a  predefined data element with a  data element. To do this, assign
the name of a  predefined data element to be connected with data to the Prede-
finedDataName property:
ItemRef = Catalog.Goods.FindByDescription("Delivery service ");
Object = ItemRef.GetObject();
Object.PredefinedDataName = "Service";
Object.Write();

This operation maps a  predefined Service item of the Goods catalog to a  data
item named Delivery service.
When an object is  written, the system checks that an infobase contains no other
data element with exactly the same name as this predefined element and set to
the value with which the data element is  written.
„„ "Disconnect" a  data element from a  predefined data element. Assign an empty
line to the PredefinedDataName property and write the element:
Object = Catalog.Goods.Service.GetObject();
Object.PredefinedDataName = "";
Object.Write();

If you try to call the Catalog.Goods.Service predefined element after the

example above is  executed, an exception will be generated.
Therefore, changing a  data element related to predefined data includes two steps:
„„ The existing data element is  disconnected from a  predefined element.
„„ A new data element is  connected to a  predefined element.
There are three ways to create data elements connected to predefined data:
„„ Automatically, during infobase restructuring. This happens in the following
cases:
○○ The automatic creation and updating of predefined data are allowed;
○○ Predefined data have been created in  this data area or in  an infobase.
„„ Automatically, when the user first opens the table that stores configuration
object data. Predefined elements will only be created if such an operation is  not
prohibited.
„„ With a script, by specifying PredefinedDataName when a data element
is created. This method can be used if the automatic creation of predefined
elements is  prohibited in  the configuration object properties.
Data connected to predefined data is updated if the automatic updating of
predefined data is allowed, predefined data is connected to real data and
Chapter 5. Configuration Objects 1-257

predefined data is changed in Designer. In all other cases, information entered

in  Designer will not be transferred to an infobase.
The change of order of predefined elements in a chart of accounts and a chart
of characteristic types in  the connected data is  not handled, i.e. the order of data
elements will be the same as they are set in  metadata. The  data entered by the user
(not the predefined data) will be located after the predefined data.
If a  predefined data element is  deleted in  Designer, the following will happen:
„„ A data element connected to a  predefined data element will be marked for dele-
tion.
„„ The corresponding entries will be deleted from an ExtDimensions list of an
element from the chart of accounts.
„„ The corresponding entries will be deleted from the lists of leading, basic, and
displacing calculation types.
If the automatic updating of predefined data is disabled in the application,
deleting a predefined element changes the related data object (if applicable).
PredefinedDataName property value is  replaced with #xxxxxxxx-xxxx-xxxx-
xxxx-xxxxxxxxxxxx, where xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
is a  unique deleted metadata element identifier.
As a  rule, the PredefinedDataName property cannot be assigned a  name of the
type specified above. However, there are two exceptions:
„„ If the DataExchange.Load property is set to True when a data object
is written;
„„ If an existing object in  the database for which such name is  already specified
changes.

5.6.5.2. Working in  a distributed infobase

When working with a distributed infobase, predefined elements are transferred
together with the configuration. Data elements connected to predefined data are
transferred normally, via an exchange plan. However, no predefined data will be
created automatically in a peripheral infobase. For a detailed description of the
reasons, see page 1-254.
CAUTION!
If data connected to predefined elements has been received in  the subordinate
node before the configuration with connected predefined elements, data and
predefined data will not be connected automatically. To do this, a  user will have
to dump the required data elements from the central infobase into a  peripheral
infobase.
If an initial image of the remote infobase is created before users have started
working with the main infobase, use the PredefinedDataInitialization()
special method to create predefined elements and automatically move them
1-258 1C:Enterprise 8.3. Developer Guide

to the peripheral infobase. This  method should be called before an initial image
is created.
If a  generic data exchange mechanism is  used, the following should be taken into
account:
„„ When writing a  data object that is  a predefined object in  the source infobase,
the system checks whether the same predefined data name exists in  the type
forming the configuration object. If such name already exists, the object will
be loaded without any changes. If there is  no such name, the Predefined-
DataName property will be cleared in  the object during loading.
For instance, a  common data exchange between similar infobases is  performed.
Each infobase includes a  Nomenclature catalog. Each infobase of this catalog
contains a  predefined Service element. References to these data objects differ.
In this scenario, the following happens during loading: the system detects
a  Service predefined element in the destination infobase and performs
loading with the PredefinedItemName property preserved. This  is  possible,
if the DataExchange.Load property is  set to True before the item is  written.
Otherwise, an exception will be thrown.
However, if you try to call the Service predefined element in  the destination
infobase, an error will occur, as the system cannot have two objects connected
to the same predefined element.
Such a  situation should be avoided. The  application developer shall handle the
attempt to load a  data object with a  similar predefined data name on his or her
own.
„„ When writing a  data object whose predefined data name references a  remote
element (has type #xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx), the
element will still be written. The  system will not allow two objects referencing
the same predefined remote element (that have the same predefined data name
value) to be written. The  only exception is  the case when the DataExchange.
Load property is  set to True before writing the element.

5.6.5.3. Working in  data separation mode

For guidelines on working in  an infobase that features data separation, see page
2-1229.

5.6.6. Input by String

You can use the String input property to specify the attributes to be used in  the
search for application objects (catalogs, documents, charts of characteristic types,
charts of accounts, charts of calculation types, register, business processes and
tasks, exchange plans). If input by string is  enabled (the relevant attributes are set),
it's allowed to enter information from the specified object attributes in  the text box,
rather than make a  selection in  the object form.
Chapter 5. Configuration Objects 1-259

Fig. 116.  Input by String

For example, you have a  Nomenclature catalog with multiple products that start
with Bosch. By entering bos in  the nomenclature text box you can obtain a  list of
goods that start with this word (see fig. 116).
You can use the following attributes to perform searches:
„„ Code and Description for catalogs, charts of characteristic types, charts of
accounts, charts of calculation types and exchange plans;
„„ Number for documents;
„„ Number and Description for business processes and tasks;
„„ Attributes of the Number or String type with their Index property set to Index
or Index with additional ordering. An example would be the text box for input of
article, barcode or TIN.
To generate a  list of attributes, press the selection button and in  the dialog box that
opens move the fields for which input by string is  permitted to the left-hand list.

Fig. 117.  Setting Up Input by String

For multiple fields, specify the order. When you search for a  string, the search will
scan the fields in  the same order as their order in  this dialog box. For example, for
a  Nomenclature catalog item, you can enter items by Code or by Part #. When the
1-260 1C:Enterprise 8.3. Developer Guide

value of an item's code matches the value of another item's Part #, these values will
be listed in  the order in  which they are specified in  the settings.
IMPORTANT!
When you search for data (use input by string), data access restrictions are applied
(see page 1-188).

5.6.6.1. Input Field Behavior

When entering data into text box, you should know some features of selection lists.
If the entered text allows the system to expressly identify the object wanted by the
user, it  inserts the object automatically in  the text box.
If the text entry results in  finding multiple objects that start with the entered text,
a  drop-down list of these objects is  displayed (up to 50 items). When entering the
text, you can navigate through the list using the Up Arrow and Down Arrow buttons,
while continuing to enter the text in  the text box. In  this case you can select the
item you want and confirm the selection by pressing Enter or Tab.

5.6.6.2. Programmatic Generation of Selection Lists

If a  developer is  not satisfied with the procedure of selection list generation, it  can
be overridden.
Two methods are available:
„„ In the form directly: In  this case a  special procedure of selection list generation
is  only used in  this particular field;
„„ In the module of the relevant object manager: In  this case a  special procedure
of selection list generation is  used for all text boxes used to enter values for the
object.
If a  field is  linked to data with an application object reference type (for example,
CatalogRef, EnumRef, etc.), you can generate a selection list in the manager
window of the corresponding object or by using form module handlers. In  other
cases you can generate a  selection list only by using form module handlers.
For details on the latter method see below.
To generate a  selection list programmatically, you have to override the Choice-
DataGetProcessing event handler of the object manager. The  handler receives
a  set of parameters that define conditions of selection list generation.
The set of parameters is  a structure containing the following items:
„„ A search string: A string containing the text entered by the user in  the text box.
This  parameter is  always used.
„„ Filter: A structure that describes the filter in the same way as the Filter
form parameter for extending the form for the dynamic list. This parameter
is  always used.
Chapter 5. Configuration Objects 1-261

„„ A property that indicates the group and item selection mode (it is  passed for
hierarchical lists only).
„„ In addition, the structure receives items set in  the following form element prop-
erties: Choice parameter links and Choice parameters.
The handler also receives a  variable it  uses to return the generated selection list
and the StandardProcessing parameter that determines the system behavior
after the handler completes its work.
If the developer sets StandardProcessing to False, the complete selection list
must be generated by the developer (considering it  can contain up to 50 visible
items).
If the standard processing flag is  set to True, the system can generate the selection
list, but you can modify parameters selection (by adding additional filter values,
changing the group and item selection mode, etc.).
NOTE 1
If the selection list is  generated by the system, it  applies the relevant data access
restrictions (see page 1-188).
NOTE 2
The examples you can see below are not complete. They only demonstrate various
methods of selection list retrieval.
Thus, when a  user enters any text, the following code generates a  selection list
consisting of three goods with 00000002, 00000003 and 00000004 codes.
Example:
Procedure ChoiceDataGetProcessing(ChoiceDataChoiceData, Parameters, StandardProcessing)

ChoiceDataChoiceData = New ValueList;

ChoiceDataChoiceData.Add(Catalogs.Goods.FindByCode("00000002"));
ChoiceDataChoiceData.Add(Catalogs.Goods.FindByCode("00000003"));
ChoiceDataChoiceData.Add(Catalogs.Goods.FindByCode("00000004"));

StandardProcessing = False;

EndProcedure

In the example below the filter generated by the text box is extended with an
additional filter that excludes services from the selection list. The selection list
is  generated by the system.
Example:
Procedure ChoiceDataChoiceDataGetProcessing(ChoiceDataChoiceData, Parameters, StandardProcessing)

Parameters.Filter.Insert("Type", Enums.ProductTypes.Product);

EndProcedure
1-262 1C:Enterprise 8.3. Developer Guide

The last example is a simplified case of filter implementation by using the
1C:Enterprise script only. This code filters goods with names that start with
a  user-entered string.
Example:
Procedure ChoiceDataChoiceDataGetProcessing(ChoiceDataChoiceData, Parameters, StandardProcessing)

Query = New Query;

Query.Text = "SELECT ALLOWED
| Goods.Ref as Product
|FROM
| Catalog.Goods AS Goods
|WHERE
| Goods.Description LIKE &Description";
Query.SetParameter("Description", Parameters.SearchString + "%");

Result = Query.Execute();
ResultTable = Result.Unload();
ProductArray = ResultTable.UnloadColumn("Product");

ChoiceData = New ValueList;
ChoiceData.LoadValues(ProductArray);

StandardProcessing = False;

EndProcedure

Please note there is another method of selection list generation: you can pass
a  structure with special content as a  value list item instead of a  reference to the
object to be found (as in  the examples above).
This structure consists of the following items:
„„ Value: A value of the selected item. The structure item with this name
is mandatory.
„„ DeletionMark: A flag specifying that the selected value is  marked for deletion
in  the infobase. The  structure item with this name is  optional.
„„ Warning: A string with the warning text displayed by 1C:Enterprise when an
item of this kind is selected from a value list. The structure item with this
name is  optional.
If the DeletionMark property in the structure is set to True and the Warning
property is not set, the system auto-generates the warning text. If the Warning
property is set, it is the one to be displayed. Please keep in mind that the
Warning text ends with a  question Continue? and has two options to select from:
Yes and No.
Below you can see a  modified code from the previous example where warehouses
with the DontUse attribute set to True have the following warning generated:
This  warehouse should not be used.
Chapter 5. Configuration Objects 1-263

You can also include both Structure type values and ordinary values in  a single
selection list.
Example:
Procedure ChoiceData GetProcessing(ChoiceData, Parameters, StandardProcessing)

StandardProcessing = False;
ChoiceData = New ValueList;

//Generate a  list with warnings

Query = New Query;
Query.Text = "SELECT
| Warehouses.Ref,
| Warehouses.Description,
| Warehouses.DontUse
|FROM
| Catalog.Warehouses AS Warehouses";

Result = Query.Execute();
SelectionDetailRecords = Result.Select();

While SelectionDetailRecords.Next() Do

Structure = New Structure("Value", SelectionDetailRecords.Ref);

//Enter the warnings
If SelectionDetailRecords.DontUse Then
Structure.Insert("Warning", "This warehouse should not be used.");
EndIf;

Item = ChoiceData.Add();
Item.Value = Structure;
Item.Presentation = SelectionDetailRecords.Description;

EndDo;

EndProcedure

NOTE
If presentations of items (including structure items named Value) are not expressly
specified, they are retrieved automatically.

5.6.7. Forms
Forms are objects created specifically for entering and viewing information and for
managing various processes. The  program uses forms to ask the user for information
it  needs to continue processing or to display information the user can view and edit.
If you need to ensure the configuration can work in  both the ordinary and managed
modes, you can use additional forms of metadata objects. 1C:Enterprise automati-
cally picks the form corresponding to the current operation mode.
1-264 1C:Enterprise 8.3. Developer Guide

Fig. 118.  Main and Additional Forms

Thin clients and web clients only work with managed forms. It means the
following:
„„ If both of the assigned forms are managed, the form marked as the main one
is displayed;
„„ If only one of the assigned forms is  managed, it  is  displayed;
„„ If no managed form is  assigned, it  is  auto-generated.
The thick client picks the form that is the most appropriate for the current run
mode.
„„ If no forms are assigned, the following is  generated:
○○ An ordinary form in  the ordinary mode;
○○ A managed form in  the managed mode.
„„ If only one form is  assigned, it  is  the one to be opened;
„„ If two forms are assigned (an ordinary and a managed form), the following
is opened:
○○ An ordinary form in  the ordinary mode;
○○ A managed form in  the managed mode.
„„ If two ordinary forms and two managed forms are assigned, the form marked as
the main form is  opened.
You can use a  duplicate set of forms if you switch your configuration from the
non-managed to the managed mode or if you want to make configuration function-
ality partially available at the web client (or the thin client). In  this case you can
implement the required features in  the managed forms and mark them as additional
forms. Then the right (managed) forms will be used in  the web client (thin client)
mode.
Chapter 5. Configuration Objects 1-265

However, you should remember that default form retrieval in the thick client
is  affected by the following configuration properties: Use managed forms in  ordi-
nary application and Use ordinary forms in  managed application:
„„ If the Use managed forms in  ordinary application configuration property is  set
to False, retrieving a  default form in  the ordinary mode at the thick client must
always result in  an ordinary form. If neither the main form nor the additional
form is  ordinary, an ordinary form is  generated. When specified, however, the
default constant form (Default Form property) is used regardless of whether
Use managed forms in  ordinary application is  checked or not.
„„ If the Use ordinary forms in  managed application configuration property is  set
to False, retrieving a default form in the managed mode at the thick client
must always result in  a managed form. If neither the main form nor the addi-
tional form is  ordinary, a  managed form is  generated.
If a form opens that is automatically generated by the system and the client
application run mode is  different from the run mode set in  the Default run mode
configuration property, the object forms and recordset forms are opened only
in  Read only mode. Generate commands will not be included in  list forms and
object forms and Create commands will not be included in  list forms, if to run
these commands the system needs to automatically generate a form applicable
for the current run mode and the client application run mode is  different from the
mode set in  the Default run mode configuration property.
If a managed application is selected as default run mode, a form purpose can
be selected for each managed form of the application. The form property Use
purposes is  equivalent in  terms of content and usage to a  similar configuration
property (see page 1-163). Form editor behavior depends on a cross-section of
multiple configuration purposes and the specific form.
If such a  cross-section has no value, Personal computer is  specified:
„„ The properties of attributes, parameters, commands, and elements that are not
supported by a  mobile platform are unavailable in  the property palette.
„„ Editing the context menu of a  form item is  unavailable.
„„ Editing an extended tooltip of a  form element is  unavailable.
„„ Form fields that are not supported by a  mobile platform are unavailable (see
page 2-919).
„„ The dynamic list settings editor does not support expanding available fields
(this is  due to the fact that a  dynamic list on a  mobile platform only works
with one table).
If a purpose of the form does not include Mobile application, it is not included
in  the mobile application configuration.
1-266 1C:Enterprise 8.3. Developer Guide

5.6.8. Commands
You can perform operations with a specific metadata object using this object's
commands. Please note that non-parameterized commands of the object are avail-
able in  the command interfaces of subsystems that include this metadata object. If
a  command is  parameterized, it  is  available in  forms that contain form attributes
(including top-level subordinate attributes of the main form attribute) of the same
type as the command parameter type.
Commands require command execution procedures. To write these procedures, use
the command module for where you need to implement CommandProcessing()
handler. This procedure must be preceded by the &AtClient directive because
the command is executed in the client application. However, other procedures
and functions in the command module can be preceded by other directives
if it is required for command execution. For details on compiler directives see
page 1-161.
A command module could contain, e.g., a procedure that opens a report form
with a  preset parameter to print out a  specific account card or a  procedure that
opens a  product list form with a  predefined filter by product type. If a  command
belonging to the Navigation panel group should open the same form in  different
tabs, you should specify a  unique key or a  unique form parameter to receive (or
open) a  form.
NOTE
If a  command is  located in  the main application window navigation panel (see
page 1-83), re-selection of this command will not lead to its repeated execution.
This  applies both to standard commands and commands created in  the configu-
ration.

5.6.9. Attribute Fill-in Mechanism for New Objects

You can fill in  attributes of new objects when you create them interactively (except
when they are copied), use the input-on-basis procedure, apply OpenForm()/
GetForm() methods or explicitly call the Fill() method. You can fill in  attributes
with the following values:
„„ Filter values, when entering values from a  list;
„„ Specific values indicated in  the attribute properties in  the configuration (fill-in
values);
„„ Values specified by the developer in  the Filling() event handler.
Fill-in processing is  implemented for the following objects:
„„ Exchange plans
„„ Catalogs
„„ Documents
„„ Charts of characteristic types
Chapter 5. Configuration Objects 1-267

„„ Charts of accounts
„„ Charts of calculation types
„„ Information register record sets
„„ Business processes
„„ Tasks
The Filling() handler uses the FillingData parameter to retrieve the filling
data. Depending on how you call the handler, the FillingData parameter can take
on different values:
„„ Generation based on another object: A reference to the source object is  passed
as a  parameter value. In  this case the FillingData parameter is  a reference to
the database source object.
„„ Selection from a  list with a  filter applied: The passed parameter value is a
structure that contains filter items with their comparison type set to Equal to
or In  list (the list has a  single value). When a  new document is  created in  the
document journal form, items of the journal column filter are preliminarily
converted so that the FillingData structure item is  named after a  document
attribute rather than a  journal column.
„„ Input of a  new object or record without applying a  filter: The  parameter value
is  Undefined.
„„ Input of a  new object or record using a  global command: The  parameter value
is  Undefined.
„„ Execution of OpenForm()/GetForm() methods from 1C:Enterprise script: If
OpenForm()/GetForm() methods result in  a new object form, a  Structure
type value of the FillValue form parameter is  passed as a  parameter value to
the FillingData handler. If the FillValue parameter is  not specified in  the
form parameters, the handler parameter value is  set to Undefined.
„„ Calling the Fill() object method from 1C:Enteprprise script: The  passed param-
eter value is  the information passed as a  Fill() method parameter.
NOTE
When a  new object is  created interactively by copying, this operation is  pro-
cessed in  the OnCopy() handler of the corresponding object.
If attributes are filled in  from the filling data, this process is  affected by the Fill
from filling data property of the metadata object attribute. If this property is  set to
True, the attributes are auto-filled by the system from the filling data. If the prop-
erty value is  False or the filling data do not contain the required value, the system
attempts to fill in  the attribute using the Fill value property.
IMPORTANT!
A developer can control how both custom and standard object attributes are
filled in. For example, the developer can disable auto-filling the Parent standard
attribute with the current group.
1-268 1C:Enterprise 8.3. Developer Guide

If the StandardProcessing parameter equals True after the Filling() handler

is  executed, the system auto-fills the attributes (including the standard attributes)
that have their Fill from filling data or Fill value property set in  the metadata and are
not filled in  the handler (their value equals the default value for the attribute type).
The  Fill from filling data property is automatically set by the system for certain
standard attributes of specific objects:
„„ For catalogs – Parent and Owner attributes;
„„ For charts of accounts, charts of characteristic types and charts of calculation
types – Parent attribute;
„„ For information registers – leading dimensions;
„„ For standard attributes of other objects this property is  not set by default.
The system retrieves data for filling standard attributes from data attributes with the
same names passed in  the FillingData parameter.
The filling data are passed to the created object form as a  standard parameter of
the FillingValues form and are later passed from this parameter to the object as
an extension of the form to be filled. You can also set the FillingValues form
parameter of the new object programmatically; in  this case all actions character-
istic of interactive object creation are performed.
NOTE
If you create a  new object programmatically, filling is  not automatically called by
the system. Instead, you should call the filling handler using the Fill() method.
Fill value: This property of a metadata object attribute can be used to specify
a  default value the attribute takes on when an object is  created interactively.
IMPORTANT!
Attributes can be filled in  from the Fill value property after the Filling() handler
is  called. The  attribute is  filled if its value has not been filled in  previously (by
the Filling() handler or the standard filling procedure).
The value types matches the attribute type. Please note that you can specify primi-
tive types or predefined data as values for this property.

5.6.10. Attribute Fill Check

Data in  the information system can be entered using multiple methods which are
frequently invalid. Therefore, a  lot of effort is  invested in  validating the entered
data and notifying the user if the data are invalid at the solution development stage.
The fill checking process facilitates configuration development considerably.
The platform supports auto-check of the specified application object and form
attributes and enables module checks.
The platform auto-checks filling for the following objects:
„„ constants
Chapter 5. Configuration Objects 1-269

„„ catalogs, documents, reports, data processors, charts of characteristic types,

charts of accounts, charts of calculation types, business processes and tasks:
○○ attributes and standard attributes
○○ tabular sections
○○ attributes and standard attributes of tabular sections
„„ record sets of accounting registers, information registers, accumulation regis-
ters, calculation registers, recalculations and sequences:
○○ dimensions
○○ resources
○○ attributes and standard attributes
„„ form attributes
„„ report form attributes
„„ data processor form attributes
NOTE
Attribute fill checking is  similar to the ValueIsFilled() function. In  tabular
section fill checking a  tabular section is  filled if it  contains at least one row.
You can call a  fill check using one of two methods:
„„ Call the FillCheck() method (for an object or a  form);
„„ Use automatic calls.
IMPORTANT!
If the Compatibility mode is  set to Version 8.1, automatic fill checks are unavailable.

5.6.10.1. Default Settings

By default the properties listed below are set to Display error for the following
standard attributes:
„„ ExchangePlan – Description
„„ Catalog – Owner, Description
„„ Document – Date
„„ ChartOfCharacteristicTypes – Description
„„ ChartOfAccounts – Code, Description
„„ ChartOfAccounts.ExtDimensionTypes – ExtDimensionType
„„ ChartOfCalculationTypes – Description
„„ ChartOfCalculationTypes.LeadingCalculationTypes – CalculationType
„„ ChartOfCalculationTypes.BaseCalculationTypes – CalculationType
„„ ChartOfCalculationTypes.DisplacingCalculationTypes – Calcula-
tionType
„„ InformationRegister – Period
1-270 1C:Enterprise 8.3. Developer Guide

„„ AccumulationRegister – Period
„„ AccountingRegister – Period
„„ CalculationRegister – RegistrationPeriod, CalculationType, BegOfAc-
tionPeriod, EndOfActionPeriod
„„ BusinessProcess – Date
„„ Task – Description

5.6.10.2. Procedure
Fill auto-check is called by a form extension before all objects, except docu-
ment, business processes, report and data processors, are written interactively.
The  following behavior is  defined for the following objects:
„„ For documents:
○○ Fill check is  called by the form extension before posting if the Post property
is  set to Enable;
○○ Fill check is  called by the form extension before writing if the Post property
is  set to Disable;
„„ For business processes fill check is  called by the form extensions before the
start;
„„ For report fill check is  called by the form extension when the Create button
is pressed;
„„ For data processors fill check is  called by the form extension in  cases when
buttons related to standard form commands are pressed: OK, Yes, Retry, Ignore.
If an attribute is the main form attribute with one of the following types:
CatalogObject, DocumentObject, ReportObject, ChartOfCharacteris-
ticTypesObject, ChartOfAccountsObject, ChartOfCalculationTypesOb-
ject, BusinessProcessObject, TaskObject, a  fill check is  also called for its value.
For the system to call the fill check, the form where you work should have its
Check fill automatically property set. In  this case the system calls the form's Fill-
CheckProcessingAtServer() handler first and then calls the object module's
FillCheckProcessing().
IMPORTANT!
If the form's Check fill automatically property is set to True when you execute
standard commands, such as Write (Post for documents, etc.) or standard form
commands (OK, Yes, Retry, Ignore), the FillCheck() method is  called. Otherwise
the fill check is  called neither for the form nor for the object.
The following procedure is  used for fill checking:
„„ A list of form attributes that can be checked for filling and have their
FillChecking property set to ShowError is  created. This  list does not include
attributes of the type that does not support fill checks (e.g., CatalogObject);
however it  includes the main form attribute name.
Chapter 5. Configuration Objects 1-271

Form attributes disabled by functional options will not be included in  an auto-
matically generated list of attributes.
„„ The form's FillCheckProcessingAtServer event handler is  called; a  devel-
oper can use it  to describe a  custom fill check algorithm or modify the list of
attributes to be checked. The  created list of attribute names is  passed to the
handler. You can only add attributes to the list in  the handler if they belong
to the types listed above (that support fill checks in forms) or are the main
attributes. Adding object-type attributes (e.g., CatalogObject) to the list raises
an exception during the subsequent auto-check. Adding a  non-existing attribute
name to the list raises an exception during the subsequent auto-check.
„„ When the event handler execution is completed, the fill check procedure
gets a  list of the checked attributes (the list might have been changed by the
handler). The  system analyzes the list of attributes and checks each attribute
for filling. If an attribute is  a main object-type attribute (e.g., Object of the
CatalogObject type), the fill check is called for the object. If an attribute
is  an object-type attribute, but is  not the main attribute, an exception is  raised.
A developer can modify the check process by defining a  FillCheckProcessing
event handler in  an object, record set or form module.
This allows the developer to gain full control over fill checks. The Chec-
kedAttributes parameter is  used to pass an array of parameters that are selected
for the check in  the Designer to the handler. The  developer can modify this array
in  any way:
„„ Delete the attributes that undergo custom checks or do not need to be checked
now;
„„ Add the required attributes that need to be checked for filling.
If the developer does not want to use the standard check procedure, he or she can
use a  custom algorithm instead and implement the UserMessage object to notify
users of the detected issues.
If the check process displays error messages to the user, the Cancel parameter
should be set to True for the platform to know that the current action cannot be
completed.
The CheckedAttributes event parameter contains attribute names in the
following formats:
„„ For attributes and constants – AttributeName, e.g. Vendor;
„„ For tabular sections – TabularSectionName, e.g. Goods;
„„ For tabular section attributes – TabularSectionName.AttributeName, e.g.
Goods.Nomenclature;
„„ For form attributes – AttributeName, e.g. DocumentObject.
If attributes are a part of functional options (see page 1-211) without param-
eters, option values are accounted for during fill checks. If the functional option
1-272 1C:Enterprise 8.3. Developer Guide

is  enabled, the attribute is  added to the list of checked attributes; otherwise the
attribute is  not added to the list. It  means the disabled field is  not passed to Fill-
CheckProcessing in  CheckedAttributes parameters.
If attributes are a part of functional options with parameters (see page 1-211),
they are always included in the list of checked attributes (CheckedAttributes
parameter). In  this case if you want to delete an attribute from the checked attributes
list, you should use the FillCheckProcessing handler. First, you need to retrieve
a  value of the functional option by specifying the required object data as parameters.

5.6.10.3. Mark Incomplete Display Rules

The following properties of configuration elements have an impact on mark incom-
plete display:
„„ Fill сheck property of a  metadata object attribute;
„„ Fill сheck property of a  form attribute;
„„ Automark unfilled property of a  form element;
„„ MarkIncomplete property of a form element (it can only be modified
programmatically).
The Automark unfilled property of a  form element can take on the following values:
„„ Auto: The mark is displayed if the form attribute or the metadata object
attribute has its Fill check property set to Display error and the attribute associ-
ated with the form element is  empty.
„„ Yes: The mark is displayed for an unfilled item regardless of the Fill check
property value.
„„ No: The  mark is  not displayed for an unfilled item regardless of the Fill check
property value.
If an incomplete mark is not shown when a text box is interactively changing,
MarkIncomplete property values do not change. Marking is shown again
(if necessary) after interactive editing in the text box is completed or the value
is  set. The  system can change the MarkIncomplete property if the AutoMarkIn-
complete property is  set to True:
„„ if the field value is  not entered, the MarkIncomplete property is  set to True;
„„ if the field value is  entered, the MarkIncomplete property is  set to False.
NOTE
If the MarkIncomplete property is  set for a  table with no rows, the first row
is  highlighted; if, however, the table is  filled, all rows are highlighted.
Additionally the incomplete mark is displayed if the message window contains
a message (see page 1-353) associated with a specific form field, regardless of
the specified properties of the form element and the associated attributes. After the
message window is  cleared, the incomplete mark is  removed for all form elements
if their MarkIncomplete property set to False.
Chapter 5. Configuration Objects 1-273

5.6.11. Indexing Object Attributes

Most configuration application objects have a subordinate Attributes group.
This  group contains additional characteristics of these objects.
In the 1C:Enterprise mode it  is  often necessary to filter data based on a  certain
attribute or to sort data lists based on attributes. 1C:Enterprise can be used for this
purpose; however, in  case of large data amount this task may take a  long time.
To speed it  up, you can specify the Index property for the attributes that will be
used for filtering or sorting. If this property is  set (the Index or Index with additional
ordering value is selected), these tasks will be performed faster. For primitive
attribute types, attribute indexing makes it  possible to sort lists by clicking in  a
column title.
In addition to sorting by attributes or filtering data by an attribute value, it  is  often
required to sort data by its main presentation (e.g., description or code) in the
resulting list, i.e. to sort records by presentation within each attribute value. To
get the correct result, select the Index value and specify both the attribute and the
presentation in  the list sorting criteria.
If you need to minimize filtering or sorting time, choose the Index with additional
ordering option for the attribute (if available).
IMPORTANT!
You can effectively use the additional sorting tool only when a  certain sorting
order is  specified in  the 1C:Enterprise mode in  the list sorting criteria: first by
attribute, then by presentation.
If such sorting criteria are not specified, there is  no need to specify the Index with
additional ordering option, since it  will be equivalent to normal indexing, however
the index size will be greater.
Indexing with additional ordering is used for attributes of catalogs, documents,
charts of characteristic types, charts of accounts and charts of calculation types.
Normal indexing can be used for register attributes.

5.6.12. Rights
You can edit rights of access to configuration objects both in  the editor of role
access rights (see page 1-185) and in  the object editing window (see page 1-59).
You can use the object editing window to set up access rights for a  specific object
in  all roles existing in  the system.
You are allowed to set access rights:
„„ For metadata objects
„„ For tabular sections
„„ For object attributes
1-274 1C:Enterprise 8.3. Developer Guide

5.6.13. Quick Choice

When text boxes are filled in, the method of object selection is defined by the
Choice Method and Quick choice properties.
The Quick choice property manages the default selection mode. This property
is  only available if the Choice Method property is  set to Both ways. Review the
example below to see how the Quick choice property works.
Assume you have a  Warehouses catalog. Its Choice Method property is set to
Both ways; its Quick choice property is  also set. In  this case values from the Ware-
houses catalog are selected in  the quick selection mode by default throughout the
entire configuration. If you disable the Quick choice property, the selection mode
changes to Using form by default.
You can also expressly override the selection mode for a  metadata object attribute
or a form element. To do so, you can just change the Quick choice property
value from Auto to Use, thus enabling the quick selection or None, disabling it.
By default, the Quick choice property for a metadata object attribute or a form
element is  set to Auto.
Therefore, the system of selection mode management has three levels:
1. First, the platform analyzes the form element Quick choice property.
2. If set to Auto, the property is  checked for the object attribute.
3. If Auto values match, the platform analyzes the Choice Method and Quick choice
properties of an application object that corresponds to the attribute type. If the
Quick choice property is  set to a  value other than Auto at the first or the second
level (form element and object attribute), the check is  terminated and a  selec-
tion is  made in  the specified mode.
NOTE
If the Choice Method property of an application object is  set to Using form or Quick
choice (not Both ways), specifying Quick choice properties for an attribute or a  form
element has no impact on the selection method.

5.6.14. Choice Parameter Links

The Choice parameters links property is  used to create a  list of attributes that will
provide values to be used when selecting an attribute value, opening a  selection
form or displaying a  quick selection list and using input by string.
As an example, consider selecting a contractor agreement. First, you select
a contractor, then you select an agreement from the list of agreements of the
selected contractor. If you change the contractor, the list of agreements changes
automatically.
To restrict selection, the attribute in  the Choice parameters links property is  set
to the attribute to be used when filtering the selected values and the attribute to be
used as the source of the filtering value.
Chapter 5. Configuration Objects 1-275

Fig. 119.  Choice Parameter Links

Values indicated in  this property are passed to the form to be opened through the
Parameters structure. Please note that the value in  the Name column matches the
structure item key, while the attribute value in  the Attribute column corresponds
to the structure item value. If the Name column contains a value of the Filter.
Owner type, a  Filter parameter (of the Structure type) is  created for the form.
The  item created in  this structure will have the Code key and a  value retrieved
from the attribute indicated in  the Attribute column (Supplier in  this example).
If the name of an item in  Choice parameters links matches the name of an item
in  Choice parameters, the item from Choice parameters links will have maximum
priority (the item from Choice parameters is  ignored), when the value of the field
specified in  the Choice parameters links item and passed to the ValueIsFilled()
function returns True. At that the item from the Choice parameters property
is ignored.
You can also use the choice parameter links window to clear the field when link
fields are modified. If the Edit mode of the linked value property is  set to Clear,
the field is cleared when the link value is modified interactively (selecting the
value previously specified in the field again is also a modification) before the
OnChange event. Otherwise the field is  not cleared (the property value is  Do not
change). Elements are cleared regardless of a  real value change in  the link element
beforethe OnChange event handler is  called.
If the field displays table data (a table column or an individual field associated with
the current data), it  is  cleared if the source of data for the form table is  Form-
DataCollection or FormDataStructureAndCollection. If the attribute you
want to clear is  associated with table data, while the link attribute is  not, values
in  all table rows are cleared.
1-276 1C:Enterprise 8.3. Developer Guide

The attribute cannot be cleared if it  is  associated with a  column of the Dynami-
cList type attribute.
For a  standard Parent attribute of a  subordinate catalog the Choice parameters
links property can be changed by the system automatically. It  could happen in  the
following cases:
„„ When the catalog subordination state changes;
„„ When the Hierarchical property value for the catalog changes.
The following procedure is  used:
„„ If the catalog is subordinate and hierarchical, a value with Name = Filter.
Owner and Attribute = Owner is  added in  the list of Choice parameters links
property values for the Parent attribute;
„„ Otherwise the value with Name = Filter.Owner and Attribute = Owner
is removed from the list of Choice parameters links property values for the
standard Parent attribute.
Review the following example: a form contains Vendor and VendorAccount
fields. The  ChoiceParameterLinks property for the VendorAccount field is  set
to Object.Vendor that is  displayed in  the Owner filter field.

Fig. 120.  Clearing Associated Form Elements

Chapter 5. Configuration Objects 1-277

Then, if you change the Vendor field value interactively, the VendorAccount field
value is  auto-cleared.

5.6.15. Choice Parameters

The Choice parameters property can be used to specify parameter values to be
applied when selecting an attribute value. This  restriction applies when you open
a  choice form, display a  quick selection list or use input by string. For example,
you might want to restrict the selection to the products with the Type attribute set
to Enum.ProductTypes.Service. You can specify a  list of values for a  specific
filter value. To do so, select the FixedArray type when you edit the Value column.

Fig. 121.  Parameters selection

Values indicated in  this property are passed to the form to be opened through the
Parameters structure. Please note that the value in the Name column matches
the structure item key, while the value in the Value column corresponds to the
structure item value. If the Name column contains a  value of the Filter.Code type,
a  Filter parameter (of the Structure type) is  created for the form. The  item
created in  this structure will have the Code key and the Value value.
If the name of an item in the Choice parameters links property matches the
name of an item in the Choice parameters property, the item from Choice
parameters links will have maximum priority (the item from Choice parameters
is  ignored). The  item priority is  maximum when the value of the field specified
in the Attribute parameter of the Choice parameters links item is filled (the
ValueIsFilled() function returns True for this value).
1-278 1C:Enterprise 8.3. Developer Guide

NOTE
Values specified in  the Choice Parameters attribute property are also used by
dynamic lists and the data composition system.
If you select extra dimension values in  a table cell linked to an accounting register
recordset, the selection parameter is  automatically set for the Owner field, but only
if this type of extra dimension has an additional catalog type of extra dimension
values. The  corresponding extra dimension type is  the selection parameter value.

5.6.16. Other
The Use standard commands property defines whether standard commands of
a  particular object (e.g., commands that open a  catalog list) can be added to the
command interface. If this property is  set to False, the standard commands are
not displayed in  the system and you can only include the object in  the interface by
using a  command created in  the Designer.
The Choice form property determines a  form to be used when selecting an attribute
value. It  is  used for attributes with the types based on metadata objects that use
forms. For example, a  Goods catalog might have multiple selection forms, but the
standard Parent attribute requires a  special form. If you want to implement this
behavior, specify this form in  the Choice form property for the standard Parent
attribute (for details on standard attributes see page 1-253).
Format is  used for Number, Boolean and Date types and defines a  format to be
used when attribute data are displayed.
The Editing format property sets a  format to be used when editing data of Number,
Boolean and Date types.
Link by type establishes a  relational link with the attribute determining the types of
values entered in  the text box. It  is  useful to set up type links for attributes that
have a  composite data type and are logically linked to another attribute, such as
ChartOfChartOfCharacteristicTypes.Ref, possibly creating a link between
an attribute that contains an extra dimension with an attribute that contains a  value
of the ChartOfAccountsRef type. An item of the type link contains the number of
extra dimension type in  case the attribute selected for the type link has a  value of
the ChartOfAccountsRef type.
For example, you might have two attributes – CharacteristicType and
Characteristic. The  CharacteristicType attribute's type is  ChartOfChar-
tOfCharacteristicTypesProductCharacteristicTypes.Ref, while the
Characteristic attribute's type is Characteristic.ProductCharacteris-
ticTypes. You can set the Characteristic attribute's property Link by type to
CharacteristicType. In  this case the selected value type is  defined by the type
specified for the selected value of the chart of characteristic types.
Chapter 5. Configuration Objects 1-279

5.7. CONSTANTS
In 1C:Enterprise, constants are used to store permanent or nearly permanent
information. This  information either does not change at all or changes quite infre-
quently. For example, the names of companies usually do not change.
The main reason for using constants is  that once information is  put there, it  can be
used for preparing documents, in  calculations or in  reports. Constant values may
be edited when necessary.
Let us look at an example. Company documents are usually signed by the director
and the chief accountant. Of course, the officials themselves must sign the docu-
ments. However, aside from the signature, it  is  necessary to provide the signature
drill down – last name of the person who has signed the document. Of course,
it  is  possible to enter the names of the director and chief accountant directly in  the
document forms. However, if one of the last names changes, you will have to edit all
of document forms and correct the last names all over again. So it  is  much easier
to create two constants for the last names of the director and the chief accountant
and use these constants in  the document forms instead of their values. If there is  a
new director or chief accountant, you only have to change the constants by entering
new names and the changes will be automatically implemented everywhere these
constants are used.
IMPORTANT!
When value of a  constant changes, the previous value is  lost. To get the previous
data values, you have to use an information register with no dimensions instead
of constants.
The 1C:Enterprise Designer can be used to create any number of constants for
storing any information.

5.7.1. Properties of a  Constant

Use the Constants branch of the configuration tree to work with constants.
Constant properties should be edited in the properties palette. Please note that
a  constant is  a typed configuration object.
Type specifies the type of constant. A constant may be of any standard configura-
tion type (Date, Number, CatalogRef, DocumentRef, etc.) or a  composite type
(comprising several types).
Depending on the type selected, the properties palette may contain additional prop-
erties that refine the selected type.
If you want the constant editing form displayed in  the command interface, set the
Include in  the command interface property. It  displays the command that opens the
constant editor in  the subsystems where the constant belongs. The  constant editing
form is  set up using the Default Form property (for details see page 2-989).
Use the Common forms branch to create constant input forms (see page 1-229).
1-280 1C:Enterprise 8.3. Developer Guide

5.8. CATALOGS
Sometimes, when document forms are filled out, it  is  necessary to enter informa-
tion by selecting a  value from a  preset list.
Let us take an application form to be completed when applying for a  job as an
example.
When filling out the Place of birth field, it  is  necessary to specify a  city or town.
Although the total number of cities and towns is  quite big, it  is  finite. Actually,
it  is  possible to specify a  place of birth by selecting a  city or town from a  list.
This list is called a catalog.
A catalog is  a list of possible values for a  certain attribute of a  document (in its
broadest sense).
Catalogs are used when it  is  necessary to ensure consistent information input.
For example, it  is  necessary to use the same name for an item so that different
employees (salespersons, managers and warehouse staff) understand what the item
is. In this case a catalog is also needed. Usually in mercantile business such
a  catalog is  stored as a  price list. If such a  catalog is  stored in  electronic form,
it  contains all of the possible items that a  business works with.
1C:Enterprise makes it  possible to maintain any number of catalogs. Each catalog
represents a list of consistent object instances: employees, organizations, goods,
etc. We will refer to each object item as a  catalog item.
Please keep in  mind that the configuration is  only used to create the structure of
a catalog, while its contents, i.e. catalog items, have to be entered by the user.
In the configuration process, it is necessary to describe the structure of the
information that will be stored in  the catalog, develop the screen and/or print repre-
sentation of the catalog and specify various characteristics of its behavior.
Catalogs usually have predefined code and description attributes. The  code number
may be of a  Number or a  String type.
The 1C:Enterprise system provides you with a  wide range of options for working
with catalog item codes: the codes are automatically assigned and checked for
uniqueness, etc.
A catalog in  1C:Enterprise may have a  hierarchical structure. There are two types
of hierarchies – the folder and item hierarchy and the item hierarchy. In  the
first case, all data in the catalog are divided into two types: catalog items and
catalog folders. Folders are logical blocks of catalog items. For example, a  catalog
of goods, where the folders are types of products (Plumbing Systems, Household
Chemicals, etc.) and the items are specific products (Mixer, Mirror, Detergent),
is  a hierarchical catalog.
Using hierarchical catalogs makes it  possible to enter information with the required
level of detail. Items and folders in  a hierarchical catalog can be moved from one
group to another.
Chapter 5. Configuration Objects 1-281

There are no folders in  catalogs with the Item hierarchy. In  this case some items
may also act as folders. In such catalogs, all of the items have the same func-
tionality. A list of company departments is  an example of such a  catalog. Each
department may be described by the same set of attributes; however, it  may logi-
cally contain another department or be a  component of another department.
For hierarchical catalogs, the Designer makes it  possible to specify a  limit on the
number of catalog levels or to use an unlimited number of nested levels.
In addition to code and description, you can create a  set of attributes to store addi-
tional information about items in  the catalog.
For example, the Contractors catalog may contain information such as the full
description of a  contractor, tax ID number, the last name of the director and the
chief accountant and other information.
If an object of the application domain corresponding to the catalog has both simple
properties like a  full description or tax ID and composite (list) properties, you can
create a  set of tabular sections for the catalog.
For example, you can create a  tabular section for the list of contractor's telephone
numbers in  the Contractors catalog.
The names of catalog attributes should not match the names of attributes in a
tabular section.
To work with information stored in  a catalog, you can create on-screen forms. You
can create separate forms for viewing, editing and selecting items from a  catalog.
The Designer allows you to create multiple forms of the same type, e.g., forms for
selecting an item from the catalog and use them in  different situations.
We recommend creating separate forms to display the list of items and to select
catalog items.

5.8.1. Catalog Properties

Use the Catalogs branch of the configuration tree to work with catalogs.
When you create a  new catalog, the object editing window opens (see page 1-59).
Hierarchical сatalog – if this check box is  selected, the catalog has a  hierarchical
structure and the Hierarchy type and Number of hierarchy levels can be set.
Hierarchy type specifies which type of hierarchy is used in a catalog. If the
Folder and item hierarchy option is selected, the catalog may contain two types
of items: folders and items. Folders are used only to hold other folders and items
of a  catalog. To define a  folder, you usually need a  code, description and parent
(link to a  higher level). A catalog item may also contain other attributes specified
on the Data tab. For catalogs with this hierarchy type, you can create folder forms
and item forms. When Item hierarchy is  selected, all items of a  catalog are at the
same level. Catalogs of departments or cost items may serve as an example.
1-282 1C:Enterprise 8.3. Developer Guide

Folders on top – this  property becomes available when Folder and item hierarchy
is  selected. If the Folders on top property is  set and the catalog is  displayed as
a  hierarchical list, its folders are placed on top, above all items. If this property
is  not set, the folders and items will be arranged according to the specified sorting
rules (by code, description, etc.). For example, if a  new folder has a  code greater
than the codes of all other folders and items (when sorted by code), in  the former
case this folder will be placed below all other folders, but above all other items;
in  the latter case it  will be placed below all folders and items.
Please note that the Folders on top property does not affect how the catalog
is  displayed as a  non-hierarchical list.
Number of hierarchy levels becomes available if the Limit the number of hierarchy
levels check box is  selected. Catalogs in  1C:Enterprise can have more than one
nested level. If the Limit the number of hierarchy levels property is not set, the
catalog may contain an unlimited number of nested levels.
Owners: This  property has to be explained in  detail.
Any catalog may be used independently or as a  subordinate to another catalog. For
example, a  catalog of contracts may be used independently or may be linked with
a  catalog of companies.
To make a catalog subordinate to any existing catalog, click the editing button
in the List of catalog owners field and specify the catalogs that own this catalog
in  the object selection window. In  1C:Enterprise, the owning catalog is  called the
owner and the owned catalog is  called the subordinate.
Unlike multi-level catalogs, where all items have the same structure, the mecha-
nism of subordinate catalogs makes it possible to connect items with different
structures. In  this case each item of the subordinate catalog will be logically linked
to one of the items of the owner catalog.
For catalogs with several owners, different items may have different types of
owners, but one item can have only one owner.
Subordination type allows you to manage owner restrictions. This  property speci-
fies whether the owner can use only items, only folders or both. If a  catalog has
several owners, the restriction applies to all of them.
Code length: This property specifies the maximum length of code for catalog
items.
You can specify zero code length in  the Designer if a  catalog item code is  not
used.
When this property is  specified, it  is  desirable to determine the code length that
is  actually possible. Please keep in  mind that you can increase code length when
needed as you operate the configuration.
NOTE
The maximum code length is  50.
Chapter 5. Configuration Objects 1-283

Description length specifies the maximum length of a  description for catalog items.
You can specify zero description length in  the Designer. It  means the catalog has
no description.
NOTE
The maximum description length is  150.
The Code series property is  used to specify the range for checking code unique-
ness and for automated code assignment.
If this property is set to In  the entire catalog and you automatically assign or
manually enter a  code, its uniqueness is  checked against all items of the catalog.
The Within subordination area setting works for hierarchical or subordinate catalogs
only. In  this case the system checks code uniqueness only within folders and items
of the owner catalog where a  new catalog item is  added or where an existing item
is edited.
When the code series is  set to Within Subordination area, catalog items in  different
folders may have the same codes. Please keep it in mind when moving items
of a multi-level catalog from one folder to another. If the code of an item that
is  moved is  the same as the code of an existing folder item, a  warning message
is  displayed and the item is  not moved.
When the code series is set to Within owner subordination area in hierarchical
subordinate catalogs, all codes with the same owner and different parents are auto-
numbered and checked for uniqueness.
The Code type property is  used to select a  value type for the catalog item code –
Number or String. String type codes are useful for complex coding systems
in  which the code may contain numbers, letters and separators. Articles of clothing
may serve as a  typical example of a  String code.
Please note that String type codes can also be assigned automatically.
For the first item, the system creates a  code that looks like 001 (the number of
zeros depends on the specified code length), i.e., the code is  a string of characters
where all characters are numerical. When other items are added to a  catalog, the
system will keep assigning item codes: 002, 003, etc.
If catalog maintenance requires using mixed alphanumerical codes, codes like
AA001 can also be used for auto-numbering. The  first component of the code here
(АА) is  a text prefix, while the second component (001) is  interpreted as a  number
and used for auto-numbering.
For example, if the first code is  АА001, the second code will be АА002, the third
code will be АА003 and so on.
A text prefix may be set manually (you can use a  composite code when adding
a new item to the catalog) or using the 1C:Enterprise script (SetNewCode()
method).
1-284 1C:Enterprise 8.3. Developer Guide

Allowed code length is  available if the Code type property is  set to String. You
can use this property to adjust the length of the string to store the code. If the
property value is  Fixed, the length of the string storing a  catalog item code always
equals the value specified in  the Code length property. Otherwise the string length
equals the actual number of characters in  the item code.
Attributes. A new catalog can be viewed as a  table with two columns: the catalog
item code and its description. 1C:Enterprise can store additional information about
catalog items, other than the description and code. When you edit a  catalog, you
can specify a  set of additional attributes for storing such additional information.
When a  catalog is  displayed on the screen, these attributes may be displayed as
columns in  the table box of the catalog's list form. In addition, the information
stored in  attributes may be used in  different calculations, reports, etc.
For example, it  is  easy to use catalog attributes to organize an employee table. To
do this, you need to create attributes that would store information about education,
personal data and other HR data in  the Employees catalog. Simple built-in search
tools make it easy to find the required information about an employee in the
catalog when using the configuration.
Tabular sections. Tabular sections are used to describe information that is  related
to the catalog, but is  not used independently. For example, a  tabular section may
contain information about an employee's family (information about each family
member will be described in  attributes of the tabular section and there can be any
number of family members), the employee's job record, etc.
In the example above, if it were possible to use information about employees'
families independently, you could put this information in  a separate catalog which
would be subordinate to the Employees catalog.
The main difference between a  tabular section and a  subordinate catalog is  that
it is possible to reference items of a catalog, unlike lines of a tabular section.
When a catalog is accessed, it is loaded into memory together with all tabular
sections. If a tabular section has many lines, this may decrease system perfor-
mance. Therefore, it is recommended that tabular sections be used when there
is  no need to store item references and when the count of items is  limited. Each
catalog may contain an unlimited number of tabular sections.
Autonumbering. If this property is set, a code will be automatically assigned to
each new item in  the catalog. Auto-assigned codes can be modified.
Check uniqueness. If code is used to identify a specific item in a catalog, this
code should be unique (have no duplicates). If the Check uniqueness property
is  set, the code will be automatically checked for uniqueness each time a  new item
is  added to the catalog.
Default presentation specifies how catalog items are displayed. For example, values
of the CatalogRef type in a document or catalog attribute or a constant, will
be displayed as the code or description of a  catalog item depending on the prop-
Chapter 5. Configuration Objects 1-285

erty value. For list forms, this column becomes the default column. When a  list
is  opened, this column becomes active.
Generation. The  Generation tab specifies which configuration objects may serve
as a  basis for objects of a  given type and for which objects the objects of a  given
type may serve as a basis. The  Generation settings wizard button launches the
"Create Based On" wizard. For more details on working with the wizard, see page
2-985.
An example of document generation is  entering a  Warehouse Transfer document
based on an item of the Goods catalog.

5.8.2. Properties of Catalog Attributes

In addition to the main properties, catalog attributes can also have the following
properties:
„„ Type specifies the attribute data type.
„„ Use specifies the attribute's use for folders and items in  hierarchical catalogs.

5.8.3. Predefined Catalog Items

A configuration developer can create a set of predefined items and folders
(for hierarchical catalogs) for any catalog. These items cannot be deleted in  the
1C:Enterprise mode.
You can open the form for entering preset items by clicking the Predefined button
on the Other tab in  the configuration object editing window. You can only enter
main properties of an item (name, code and description) in  the Designer. The  item
name may be used in  expressions of the 1C:Enterprise script. The  values of other
attributes of a  predefined item are entered in  the 1C:Enterprise mode.
In the 1C:Enterprise mode icons for predefined catalog items and custom items
look different.
IMPORTANT!
You cannot create predefined items for a  catalog that has an owner, and you can-
not set an owner for a  catalog that has predefined items.

5.9. DOCUMENTS
A document is  one of the main concepts in  1C:Enterprise. Documents are used to
enter information about business transactions into the system.
Most documents that are created during task configuration are electronic coun-
terparts of standard paper documents; however, in  addition to recording business
transactions, this data type may be used to save other data, too.
Every document contains information about a specific business transaction and
is  characterized by a  number, date and time. Date and time are the most important
1-286 1C:Enterprise 8.3. Developer Guide

document characteristics, since they make it  possible to determine the sequence of
operations.
The configuration only describes the document structure; specific document
instances have to entered by a  user working with the program. For example, the
Invoice document in  1C:Enterprise may be used to prepare invoices with different
contents and the same attribute sets, the same logic of behavior, etc.
Hereinafter, document structure is  referred to as a  document, i.e. tools for docu-
ment input and visualization.
The Designer can be used to describe a document structure, arrange forms for
entering information in  a document and describe the algorithm of print form crea-
tion for the document.
In addition to the date, time and document number, you can create a  set of attrib-
utes for storing additional information.
If an object of the application domain corresponding to the document has both
simple properties like date, number and total amount and composite (list) proper-
ties, you can create a  set of tabular sections for this document.
For example, you can create a tabular section for a list of items in the Goods
Issue document.
A configuration may contain any required count of lists of documents with the
same type and document journals with different types. List forms do not have the
Document type column (since lists contain documents of the same type), while
journals usually do contain this column.
When a  document is  created, you can specify a  list of journals that will be used
for working with this document. You can specify one journal for different docu-
ment types which will allow you to group documents in  the journals as needed.
You can change the journals assigned to a  document.
Documents can change the status of accounting registers (when they are posted).
If a  document has been posted, the data specified by the user when entering the
document affect the system accounting registers, i.e. modify inventory balances,
amounts due to contractors, etc. You can post documents in  real time (real-time
posting) or backdated (regular posting).

5.9.1. Document Properties

The Documents branch of the configuration tree is  used for working with docu-
ments. This  branch also contains service configuration objects – numerators and
sequences.
This section describes specific document properties. Common properties of all
configuration objects, including documents, are described on page 1-250.
Document properties can be edited using the properties palette or the editing window
(see page 1-59). You can configure various document properties at different tabs.
Chapter 5. Configuration Objects 1-287

The Main tab contains the main document information.

The Data tab contains attributes and tabular sections.
In the properties palette, the type is  specified for each attribute, in  addition to the
main properties. To enable fast searching or information selection by document
attributes, it is necessary to set the Index property for the appropriate attributes
(for details see page 1-273).
The Numbering tab contains data that are used to assign document numbering rules.
Each document has mandatory attributes that are created automatically and cannot
be deleted. These attributes include the date, time and document number. Unlike
date and time, you can specify several parameters for the document number. These
parameters will control how this attribute behaves when you work with a  docu-
ment of this type. The  combination of these parameters will define the document
numbering rules for 1C:Enterprise.
Autonumbering. If you turn this property on, each new document will be numbered
automatically. An automatically assigned number can be corrected.
Numerator. A document can be assigned one of the numerators already existing
in  the configuration. To assign an existing numerator to the document, select the
numerator name in  the Numerator property. In  this case all items on the Numbering
tab, except Autonumbering, become unavailable, i.e., the numbering rules for this
type of document will be completely defined by the assigned numerator. For infor-
mation about numerator creation and properties see page 1-290.
Numerators help organize continuous numbering for different types of documents.
To do this, you have to assign the same numerator to all documents that should be
numbered continuously. Uniqueness check and sequential number assignment will
take into account all documents with this numerator.
Number length specifies the maximum length of a  document number.
Number format is  the same as Code type in  a catalog (see page 1-280).
Allowed number length is  available if the Number format property is  set to String.
You can use this property to adjust the length of the string to store the number.
If the property value is  Fixed, the length of the string storing a  document number
always equals the value specified in the Number length property. Otherwise the
string length equals the actual number of characters in  the document number.
If the Check uniqueness property is set, the number of each new document
is  checked for uniqueness, subject to the restrictions specified by Periodicity.
Periodicity specifies the document number uniqueness check and the number repeti-
tion period. If the Check uniqueness property is  turned on for document numbers,
Periodicity specifies the limits for checking.
If Autonumbering is  turned on, 1C:Enterprise will assign a  new sequence number
to each new document. When the period specified in  Periodicity expires, document
numbering restarts from 1.
1-288 1C:Enterprise 8.3. Developer Guide

The Posting tab is  used to set up behavior during document posting and posting
cancellation.
Posting specifies whether the document can be posted when it is saved. If this
property is set to Enable, the document modifies the register records (changes
their state). This  selection also automatically calls the Posting event handler for
document posting in  the 1C:Enterprise mode which opens when a  button with the
predefined Save and close action (usually an OK button) is  clicked. You can use
the register record wizard (see page 2-980) to create the Posting event handler.
Open the wizard by clicking the appropriate button at the Posting tab in  the Docu-
ment object editing window.
Real-time posting specifies whether real-time posting is  enabled for a  document.
When a  non-current date is  selected, documents with enabled real-time posting are
posted in  regular mode, because in  this case an accomplished fact that does not
require real-time verification (e.g., checking the balance in  the product's invoice)
is  being recorded.
If Real-time posting is  turned on for a  document, then zero time is  set for a  new
document. Upon posting, the system receives a  real-time timestamp which may be
the same as or greater than the current date and time and assigns this time stamp
to the document. After that, the document is  posted in  real time. For details on
real-time timestamp see page 1-292.
If a  document being edited has Real-time posting turned on, the time differs from
the current time and when the document is posted (if the current date is speci-
fied), the system asks what type of posting should be used. If you select Real-time
posting, then the system sets the current time for the document. If you change the
time when the document is  edited (e.g., if you specify future time of the current
day), the system also sets the current time for the document. If you select Regular
posting, then the system sets the time to the beginning of the day if the date format
does not require entering the time.
Register records deletion is available if the Posting property is set to Enable.
This option defines how all records saved during document posting are deleted
when the document is  reposted or unposted:
„„ Delete automatically means the system deletes the records when a  previously
posted document is  reposted (prior to writing new records) or when document
posting is  canceled.
„„ Do not delete automatically means register records are deleted programmatically
in special cases. Use this mode to manage deletion during both posting and
unposting.
„„ Delete automatically on clearing posting means the system automatically deletes
register records only when posting is canceled. Reposting will not result
in  automatic record deletion. This  mode is  used by default.
Chapter 5. Configuration Objects 1-289

If the Register records deletion property is  set to Do not delete automatically or
Delete automatically on clearing posting, you should clear any Register Records
collection recordsets before the posting operation to avoid information duplication.
Add register records on posting defines how the system behaves when register
records are created during document posting:
„„ Record selected (default mode) means a  record set of the register record collec-
tion is only written if the Write property of the set is  True (regardless of
whether the records in  the set have been modified or not).
„„ Record modified (this mode is  set when migrating from 1C:Enterprise 8.1 and
older versions) means that the system write the record sets that have been modi-
fied (their Write property is  automatically set to True).
After the document is  written, the system resets the Write property for all record
sets that register document records, even if the write operation failed.
Sequence filling sets the automated sequence filling mode. The  Sequences tab of
the Edit window specifies whether the document is  part of a  sequence.
At the Journals tab in the document editing window, you can mark document
journals that will display documents of this type for 1C:Enterprise users. You can
create the required document journal forms later.
The Generation tab contains two lists of configuration objects. The  top list should
contain objects that may serve as a basis for the document and the bottom list
should contain objects for which this document may serve as a  basis.
IMPORTANT!
A document may be entered on basis of another document or based on objects
of a different type (items of catalogs, charts of characteristic types, charts of
accounts or charts of calculation types). A document may also serve as a  basis
both for other documents and for objects of a  different type.
If you want to create a  procedure for preparing the created object data based on
a  sample, use a  special wizard. For a  description of this wizard see page 2-985.
The Rights box allows you to set the privileged mode for posting (Privileged
mode for posting property) and/or for unposting documents (Privileged mode for
unposting property):
„„ If this property is  set, the system will always post or unpost document in  the
privileged mode (at the server side and in file mode version). However, the
privileged mode is  not set if a  document is  posted or unposted in  the client/
server mode at the thick client side. The  privileged mode enables you to do the
following:
○○ Autodelete register records;
○○ Autowrite register records;
○○ Use an appropriate handler (Posting or UndoPosting). However, objects
are written in  the regular (non-privileged) mode.
1-290 1C:Enterprise 8.3. Developer Guide

„„ The privileged mode is  enabled by the system after the object is  written, but
before posting starts (before register records are deleted if it  is  done automati-
cally). The  same procedure is  used when unposting.
„„ When new documents are created, these properties are set to True if the
managed application mode is  selected as the main run mode in  the configu-
ration properties; otherwise if the ordinary application mode is selected, the
properties are set to False.

5.9.2. Document Posting Mechanism

Information about business transactions of a  company is  stored in  registers (see
page 1-316). Documents can change the register status. This process is known
as posting. It is recommended to use this process to change the register status.
Posting can be real-time or regular (Real-time posting property).
NOTE
Generally, real-time posting is  used for real-time accounting purposes.

5.9.2.1. Real-Time and Regular Posting

Real-time posting is  designed to better separate cases of document posting in  real
time and document posting that reflects an accomplished fact.
Real-time posting is  required when document entry and posting do not just register
an event, but are a part of the event and help the operator enter information
correctly. Naturally, it  only makes sense if the event happens in  real time.
A classical example is entering and posting a document that reflects goods
sales from a  warehouse. When entering this document, the operator has to both
enter a valid list of goods purchased by a customer and run various checks.
The first check is whether the requested product is available at the warehouse.
It  is  important to remember that the check must also be run for other operators
that work concurrently and can order the same products. Accordingly, the system
is  to prevent operators from selling the same product to two different customers.
Additionally you might want to check the amount of credit available to a  customer,
the payment against the invoice and other aspects.
At the same time, if a document is backdated, i.e. entered when the business
transaction has already occurred (e.g., a  specific product has been shipped to the
customer), there is  no need to run checks; all you need to do is  to record the event
in the accounting register. In this case posting a document only registers the
event, without being its part.
Therefore, real-time posting aims to separate two posting options: on the one hand,
the user needs to understand which posting option is  selected; on the other, the
posting algorithm needs to perform actions that correspond to the current posting
option.
Chapter 5. Configuration Objects 1-291

The posting option (real-time or regular) for a  document is  selected on the basis
of its date. If the posted document date matches the current date, the system posts
the document in  real time without additional queries. The  option is  defined by the
posting data processor which determines the specific algorithm of document posting.

5.9.2.2. Form Extension and Posting

In addition to the Real-time posting property of a document, you can also set
a  posting mode for a  document form extension. The  Use posting mode property
can be assigned one of the following values:
„„ Non-real-time. Documents are always posted in the regular mode. If regular
posting rights are missing, an exception is  raised.
„„ Real-time. Documents are always posted in  real time. If regular posting rights
are missing and you attempt to post a  document that belongs to a  prior period,
an exception is  raised.
„„ Query. The  system always prompts the user to select the current posting mode.
„„ Auto. The  system uses the following algorithm:
○○ If the document date precedes the current date, regular posting is  used;
○○ If the document date matches the current date, real-time posting is  used;
○○ If the document date follows the current date, an exception is  raised;
○○ If the document cannot be posted in  the selected mode (insufficient access
rights, etc.), an exception is  raised;
○○ If the posting mode at the client side is  unknown, the PostingMode param-
eter of the BeforeWrite event handler receives the Undefined value.
In real-time document posting, one of the targets is listing documents chrono-
logically on the time scale. This  is  required, in  particular, to write off balances
correctly in  the balance registers (see page 1-325) of real-time accounting. Docu-
ment arrangement uses the following concepts: point in time and real-time
timestamp. Let us review these concepts in  more detail.
A document's position on a  time axis is  defined with the help of the Date attribute
that contains time with accuracy of up to one second. It  means you can manage the
sequencing of document records. However, where the number of documents being
created is  large, there will probably be instances in  which several documents will
have identical dates (i.e. they will be created in  the same second). How do we then
determine the sequence of document creation?

5.9.2.3. Point in  Time

The point in time concept was introduced to deal with just this problem.
A point in time is a combination of date, time and a reference to a database
object. It  allows you to explicitly identify any reference-type database object, but
it  generally only applies to documents. The  point in  time also identifies non-ob-
ject data such as register records that are subordinate to a  recorder.
1-292 1C:Enterprise 8.3. Developer Guide

The point in time concept is implemented in the 1C:Enterprise script using the
universal PointInTime object.
If multiple documents have identical dates and times, their sequence on the time
axis is established based on the references. This sequence may differ from the
sequence of document creation and cannot be changed by the user. i.e. the user
cannot change the sequence of documents within a second or figure out which
document is  created earlier or later.

5.9.2.4. Real-Time Timestamp

A real-time timestamp is a value of the Date type. A real-time timestamp
is  the basis that allows you to actually post documents in  real time. The  system
generates a  real-time timestamp for each instance of real-time document posting.
Its value is generated based on the current session date and the last real-time
timestamp generated.

5.9.2.5. Time Zones

If the system works with multiple time zones, this should be accounted for
when retrieving a real-time timestamp. For example, an infobase can be physi-
cally located in  a single city (time zone), but can be used to record transactions
in  multiple remote offices (e.g., branches of a  holding company) located in  other
cities (and time zones). In  this case you would need each branch to have its own
timestamp.
Time zones are accounted for through infobase time zones and session time zones.
An infobase time zone defines the time zone used for a  new session by default.
When you create an infobase, the infobase time zone is  undefined. However, you
can specify it  using the global context SetInfoBaseTimeZone() method. Infor-
mation about the infobase time zone is  saved in  the database and does not modify
when the infobase is  restored or dumped. Creating an initial infobase image (using
distributed infobase mechanisms; see page 2-772) copies the infobase time zone
from the original infobase to the image.
If the infobase time zone is not specified, the system uses the time zone
of the machine where 1C:Enterprise server is  installed (in the client/server mode)
or the time zone of the local computer (in the file mode version).
A session time zone describes the time zone for a  particular session. By default
the session time zone matches the infobase time zone.
You can specify the session time zone using the global context SetSessionTi-
meZone() method. The session time zone is saved until the session ends.
It is used to define the current date of the session and to retrieve a real-time
timestamp.
Chapter 5. Configuration Objects 1-293

5.9.2.6. Retrieval of Real-Time Timestamp

In real-time posting, the system modifies document time so that the next docu-
ment posted in real time has a later point in time compared to the previously
posted document. It is implemented through real-time timestamps. Real-time
timestamps are retrieved by the system automatically during real-time posting;
however, they can also be explicitly obtained in  the 1C:Enterprise script using the
GetRealTimeTimestamp() method based on the current session date.
The current session date is  the system date recalculated to match the session time
zone. It  means the local computer time is  recalculated into the zone time defined
by the session time zone. This recalculation uses Universal Time Coordinated
(UTC).
All users call a single real-time timestamp mechanism that provides each user
with the next timestamp in  turn. The  mechanism of real-time timestamp retrieval
returns date that is  greater than the previous timestamp received by this or another
user in the current time zone. Generally, the system returns the current session
time as the real-time timestamp. However, if the current time is  greater than or
equal to the last timestamp returned to any user, the returned value is  one second
more than the last timestamp value. Thus, it  ensures that each call returns a  value
that matches the current time, whenever possible and is  always greater than the last
returned value.
Please keep in  mind that different session with the same time zone use the same
time to obtain real-time timestamps. Therefore, the number of unrelated real-time
timestamps is  defined by the number of unique time zones set as session time zones.

5.9.3. Numerators
A numerator is a configuration object that defines document numbering rules:
document number type and length, periodicity, requirements for uniqueness check.
The main purpose of the numerator is  to provide continuous numbering for docu-
ments of different kinds. For this purpose, the same numerator is  assigned to such
documents.

5.9.3.1. Management of Numerator Lists

To work with Document numerator configuration objects, you have to use the
configuration branch within the Documents branch that starts from the Document
numerators keyword.

5.9.3.2. Numerator Properties

This section describes numerator-specific properties. Common properties of all
configuration objects, including numerators, are described on page 1-250.
1-294 1C:Enterprise 8.3. Developer Guide

Fig. 122.  Numerator Properties

Number Type. Type of document number value: numeric or text. Text numbers
are useful for complex document numbering systems. The  document number may
contain numbers, letters and separators.
Number Length specifies the maximum length of a  document number.
Periodicity specifies the two important characteristics of the numerator: document
number uniqueness check and the number repetition period.
If the Check Uniqueness property is  turned on, Periodicity specifies the range for
checking.
For example, if Within a  day is set as the periodicity option, document number
uniqueness will be controlled within a  24-hour period: on the next day, the docu-
ment numbers may repeat; however within the same day they will be unique.
If Autonumbering is  turned on (see page 1-286), 1C:Enterprise will assign a  new
sequence number to each new document. When the period specified in  Periodicity
expires, document numbering restarts from 1.
If the Check Uniqueness property is set, the number of each new document
is  checked for uniqueness, subject to the restrictions specified by Periodicity.

5.9.4. Document Sequences

Document sequences are auxiliary configuration objects. They are intended for
timely posting of specific documents.
All documents in the 1C:Enterprise form a single time sequence. To make this
possible, every document has its own date and time. If two documents have the
same date and time, they are still placed in  a certain sequence which depends on
the time they were entered into the system. You can change a  document's date and
time. Therefore, regardless of the entry order, the documents may be placed in  any
sequence corresponding to the actual sequence of the business events represented
by these documents.
Chapter 5. Configuration Objects 1-295

When a  document is  posted in  1C:Enterprise, the system performs certain actions
that are recorded by the document in  multiple accounting mechanisms supported
by 1C:Enterprise.
The document posting algorithm usually records information saved in  a document
(in its attributes and tabular sections). However, in some cases, the document
posting algorithm also analyzes current totals and uses them in posting. For
example, if a  document is  used to write off goods or materials at average cost,
the algorithm determines the write-off amount by analyzing the inventory balances
of goods (or materials) at the document time. If goods or materials are written off
using LIFO or FIFO methods, the posting algorithm will analyze the remaining
inventory balance of goods (or materials) by lots for date and time of document
posting.
It is  obvious that posting of documents based on total results should follow a  strict
sequence. However, it often becomes necessary to input or correct some docu-
ments post factum, due to human errors or document delays. In  this case posting
of register records generated by subsequent documents (created after the corrected
document) will be considered incorrect. For example, if it  turns out that a  receipt
that was entered at the beginning of the month contained the wrong amount of
goods, it  is  necessary to reanalyze all subsequent invoices that write off available
lots and to re-write the register records. In  other words, all documents that analyze
the remaining inventory and come after the changed document have to be reposted.
Sequences branch objects are used for automatic check of document reposting.
Each Sequence object in the configuration checks posting of documents of the
specified types. Therefore, there may be multiple independent sequences in the
system.

5.9.4.1. Management of Sequence Lists

Sequence configuration objects are created in the Configuration window. Each
sequence uses a  separate configuration tree branch that is  located within the Docu-
ments branch and starts from the Sequences keyword.

5.9.4.2. Document Sequence Properties

This section describes properties specific to document sequences. Common proper-
ties of all configuration objects, including document sequences, are described on
page 1-250.
Sequence properties can be edited in  the Sequence editing window.
You can select documents in  the sequence and register records that influence the
sequence at the Usage tab (see fig. 123).
1-296 1C:Enterprise 8.3. Developer Guide

Fig. 123.  Sequence Properties

Move the boundary when posting. If the Move option is  enabled, when you post
a  document registered in  this sequence, it  will try to move the boundary of the
sequenced documents. If the property value is  Do not move, the posted document
will not move the boundary of this sequence.
Incoming documents. The top list of the Sequence window contains document
types for a  specific sequence.
Select documents types that analyze values of different registers during posting
as documents affected by this sequence. Such documents may include invoices,
transfer orders, sales orders, etc.
Register records that affect the sequence is one of the main sequence proper-
ties. It  defines register records that will influence re-posting of documents in  the
sequence, i.e. accounting mechanisms that will be used for posting of documents
in  the sequence. For example, such records may include register records.
To configure this parameter, add register types that influence the current sequence
to the list.
Dimensions. Sequences may have subordinate objects known as dimensions which
are created on the Data tab of the Edit window.
If no dimensions exist for a sequence, then all incoming documents will be
reposted when this sequence is  restored. If you want the sequence to cover specific
rather than all situations, add a  dimension to the sequence. In  this case re-posting
will be needed only for documents that change the register value allowing for the
dimensions properties.
Chapter 5. Configuration Objects 1-297

If sequence register values change, all later documents with the same attribute
values (listed in the Document Attributes Mapping dimension property) included
in the attributes of the deleted (added) register records (listed in the Register
records attributes mapping dimension property) become invalid.
For example, a sequence takes into account register changes for Goods Receipt
and Goods Issue documents. If additional criteria need to be taken into account
for reposting of specific documents (e.g., it is necessary to repost documents
related to a specific item), then a dimension has to be added to the sequence.
Use the dimension's properties palette to specify the dimensions type (Cata-
logRef.Nomenclature) and to link it  to register attributes.

Fig. 124.  Sequence Dimension Properties

Depending on the dimension type selected, document lists and dimension register
lists only contain objects with the specified type of dimension.
Implementation of dimensions makes document reposting faster which is espe-
cially important for large volumes of documentation, since only documents
containing the specified data will be reposted.

5.9.4.3. Work with Document Sequences

The 1C:Enterprise mode automatically maintains a sequence boundary for each
document sequence in  the configuration. Document position acts as the sequence
boundary. During sequential posting of documents in a sequence, the sequence
boundary is  placed on each newly posted document. However, if you post a  docu-
ment that belongs to this sequence, but follows another posted document belonging
to the same sequence and located after the current sequence boundary, the boundary
does not change, as this would violate the sequence of posted documents. A docu-
ment posting algorithm may be used to analyze such situations.
When documents are posted post factum, posting is cancelled, documents are
deleted or register records that influence this sequence are deleted or written,
the sequence boundary is moved to the time of the modified document. Before
1-298 1C:Enterprise 8.3. Developer Guide

the boundary is  moved backwards, the system checks if there are other boundaries
to be moved backwards. This  check does not require exclusive boundary lock.
Therefore, the sequence boundary will move forward with sequential posting of
documents in  this sequence and will move back if register records for this sequence
are modified post factum.
There is  a special feature to restore the document posting sequence in  the docu-
ment reposting mode (All functions  – Standard  – Document Posting). When this
feature is  used, the system automatically reposts all documents belonging to this
sequence from the sequence boundary up to a  specified location.
In the example with goods accounting, posted invoices will move the sequence
boundary forward. If any modification of records in the register used for cost
accounting of goods is written before the sequence boundary, it will move
the boundary back to the time of this document. After that, posted documents
positioned after the sequence boundary no longer move it forward if there are
any posted documents of this sequence between the sequence boundary and the
currently posted document. Restoring the sequence reposts all invoices. Please note
that receipts, although influencing the sequence boundary, are not reposted, since
their posting algorithm does not use balances and they are not included in  the list
of documents belonging to this sequence. After restoring the sequence, documents
that are posted after the sequence boundary will move the boundary forward.
The Restore sequences mode makes it  possible to automatically repost all docu-
ments related to the sequence from the current position of the sequence boundary
to a  specified moment. In  this case you need to select a  position that will limit the
document reposting at the top of the dialog.

5.9.5. Entering Documents Based on Existing Objects

You can enter new documents in the 1C:Enterprise system based on existing
objects. Users can enter documents or catalog items and enter their respective
attributes by copying information from other infobase objects, such as documents
or objects of other types.
The Generation tab lists the objects that can be used as a  basis for the selected
document type (the Can be generated based on field) and the objects that can be
based on this document type (the Can be used as a  basis for generating field).
To enable the generation procedure, you must implement the Filling event handler
in  the document module. For a  description of the filling procedure see page 1-266.
The code of the handler may be adjusted by a system configuration specialist.
The  code of the handler should provide for certain information transfer operations
depending on the type of source document, as well as other required operations.
Create Based On Wizard (see page 2-985) can be used to facilitate creation of this
handler.
Chapter 5. Configuration Objects 1-299

5.10. DOCUMENT JOURNALS

In 1C:Enterprise, document journals are objects that enable users to work with
documents of various types. Users can enter, view and delete documents in  journal
forms.
Users can search for any document in a journal by column contents, search for
a  document by its number and filter documents by specific parameters.
You can create any number of journals in  the Designer.
When a journal is created, you can create any number of screen forms for it.
Screen forms contain table boxes that display the document type, number, date and
time, as well as additional columns for other document attributes that are shown
in  each journal.
If no journal form is  created, a  default journal form will be created automatically
in  the 1C:Enterprise mode.

5.10.1. Journal Creation

The Document journals branch of the configuration tree is  used for working with
journals.
In 1C:Enterprise, journal creation and document placement processes are very
closely related. Document representation in  a journal is  synchronized with journal
data for documents the journal contains.
When both a  journal and documents are created, a  new document or journal will
automatically be added to the list of journals and documents. To display document
data in  the journal it  is  necessary to specify the relationship, either in  the journal
or in  the document. You can specify that a  document belongs to a  journal using
both the journal and the document, since this operation is  synchronized.

5.10.2. Journal Editing

This section describes journal-specific properties that supplement common prop-
erties of configuration objects (see page 1-250) and editing methods for Journal
configuration objects that differ from the editing methods common for all configu-
ration objects.
Journal properties (preparing additional column lists, column definition, journal
forms, print form templates, etc.) are configured in  the editing window (see page
1-59).
Use the Data tab to prepare a  list of documents in  a journal and a  list of journal
columns.
Each subordinate object at the Graphs branch contains a  common attribute of all
documents included into the journal (see below).
1-300 1C:Enterprise 8.3. Developer Guide

5.10.3. Document Journal Columns

When a  new document journal is  created in  the configuration, you can create any
number of journal forms for it. Journal forms can be created using the configuration
object form wizard (see page 1-59). The  wizard places a  table box with a  set of
columns for different document attributes into the form. When you create a  journal
form, the form wizard creates the following columns: picture (the document status),
type, date and document number. If you want to add more information to the
journal, prepare a  list of additional columns and place them in  the forms.
The Data tab of the editing window contains a list of documents with data
displayed in  the journal. To create an additional column in  the bottom list, add
a  Graph subordinate object and specify the attributes of documents with data
displayed in  this column.
To select the document attributes to be displayed in  the journal column, click the
selection button in the References property of the column's properties palette.
The  document attribute selection window will open.

Fig. 125.  Attribute Selection for a  Column

IMPORTANT!
You cannot select more than one attribute of the same document.
If an attribute of a  document is  not selected, the column of the document journal
will contain no information for all documents of this type. Your selection should
be based on common sense. It is not reasonable to include entirely different
documents in  the same column (e.g., a  contractor description and a  document's
amount).
You can add any number of columns to the journal in  addition to the obligatory
document columns (Date, Number, Document type) and columns specified in  the
subordinate group of Graph journal objects.
Chapter 5. Configuration Objects 1-301

If all the documents with a  string type number in  the journal have a  fixed number
length, then the Number column of the journal will also be of a  fixed length. When
at least one document with a string type number in the journal has a variable
number length, then a  Number journal column of variable length will be created.
A new column is  first added to the column list of the selected Document journal
object and is  then inserted into a  form using the Form – Insert Attributes menu item.
Availability of additional columns in  the journal enables a  user to get the most
important information about a  document without opening it.
For any form elements displaying a  journal column, the following attribute proper-
ties included in  the column are applied automatically:
„„ Password mode – if this mode is  set for any attribute included in  the column.
„„ Format – in case of match for all attributes included in the column on all
languages specified in  the configuration.
„„ Tooltip – if tooltips match for all attributes, one tooltip is  shown; if tooltips do
not match, they are shown separated by a  comma.
„„ Highlight negative – if this property is  set for all the attributes included in  the
column.
„„ Multiline mode – if this property is set for all the attributes included in the
column.

5.11. ENUMERATIONS
An enumeration is  a service data type that is  mainly used with other data types
rather than independently. An enumeration is  a list of possible attribute values.
Enumerations are used to enter document or catalog attributes and constant values
when it  is  necessary to enter only predefined information.
As an example, let us take the customer status concept. In  the simplest case, there
may be retail and wholesale customers. Customer status usually influences the level
of discounts.
This list of statuses (Retail and Wholesale) is actually a simple enumeration.
When billing, the user has to specify the customer's status by selecting it  from the
list. The  selected customer status influences the sales price.
If the customer status is entered as an enumeration during task configuration,
a 1C:Enterprise configuration specialist may specify price calculation options
depending on the status.
First of all, when you use it, the enumeration cannot be expanded since the list of
its values was set during the enumeration setup.
All enumerations have only one level; no nesting is  available.
The main feature of an enumeration is that its values are known and available
in  the Designer. The  configuration itself uses specific enumeration values.
1-302 1C:Enterprise 8.3. Developer Guide

With enumerations, you can limit the number of possible options, e.g. when
you enter a  document attribute. Since enumeration value lists are created in  the
configuration, you can validate the selected value and specify the actions that
should follow.
Use the Enumerations branch of the configuration tree to work with enumerations.
Editing an enumeration actually involves creating a list of values. To edit an
enumeration object, use the Enumeration object editing window. The  Include in  the
command interface property is  disabled when a  new enumeration is  created.
Enter values for an enumeration at the Data tab.

Fig. 126.  Adding an Enumeration Value

The properties palette contains a  name and a  synonym.

The list of enumeration values in  the 1C:Enterprise mode is  used as follows: each
enumeration value is represented by a synonym or by a name if the synonym
is  not set.
In the above example (see fig. 127), the value of the ProductTypes enumeration
will be displayed as Product (the specified synonym).
The Forms tab is  used to create list and choice forms. You can create different
selection forms (depending on the context). In  list forms, enumeration lists can be
printed. The  Include in  the command interface property is  automatically enabled
when a  default list form is  created.
You can create print templates at the Templates tab.
Chapter 5. Configuration Objects 1-303

5.12. REPORTS AND DATA PROCESSORS

Any accounting system is functional only when it has the ability to process the
accumulated information and to produce summary data that are easy to view and
analyze. For this purpose, accounting systems usually have a report generation
feature. The  Designer makes it  possible to prepare a  set of different reports suffi-
cient to meet system users' requirements for accurate and detailed output information.
Configuration objects located at the Reports branch of the configuration tree are
used to generate reports in the 1C:Enterprise system. Each object of this type
can contain an algorithm for generating paper or electronic reports written in  the
1C:Enterprise script or a data composition schema used in 1C:Enterprise as
a  basis to auto-run reports (see page 1-536). A report may contain one or several
forms which may be used to enter parameters that influence the algorithm, if neces-
sary. A report may have print form descriptions (templates) that are created in  the
template wizard and used to display algorithm results on screen or print them out.
Use the editing window to edit properties of Report and Data processor objects and
create subordinate objects (see page 1-59).
Configuration objects located at the Data processors branch of the configura-
tion tree are used to handle information in  1C:Enterprise. For example, you can
use them to delete obsolete data from the system, import information from other
systems and for many other purposes. The  name of the configuration object (Data
processor) describes the actions that are performed with information, since they
modify the information stored in  the system.
A data processor may contain one or several forms which may be used to enter
parameters that influence the algorithm, if necessary. Algorithm results are
displayed or printed out using the template wizard for print form descriptions
(templates).
The main difference between a  report and a  data processor is  the ability to use
the data composition schema (for details see page 1-531). All other features of data
processors are identical to those of reports.
You can use the same report forms, report settings or variants for multiple (or
all) application reports. You need to use common forms for this. In  general, the
following usage options are available:
„„ A single report form set is used for all application reports. In this case you
need to create the required forms and specify them in configuration proper-
ties (see page 1-167). Then you do not need to design forms in  reports, since
common forms will be used.
„„ You can select report sets and design special report forms for every report set.
In  this case common report forms are created that are specified for every report
of a  corresponding group. Thus you can create a  special form set, for example,
for accounting reports and analysis reports.
1-304 1C:Enterprise 8.3. Developer Guide

NOTE
If several reports have the same default form specified as their main form, only
one report can be opened in  the thick client (in a  regular mode).

5.12.1. External Reports and Data Processors

In 1C:Enterprise an external report is stored outside the configuration, in a
separate external report file. It  has the same purpose as the Report configuration
objects.
In 1C:Enterprise an external data processor is stored outside the configuration,
in  a separate external data processor file. It  has the same purpose as configuration
objects of Report or Data processor type.
The main purpose of any external report (data processor) is  implementing, deliv-
ering and updating specific features outside the configuration.
External reports and data processors are stored in  .erf and .epf files, accordingly.
You can develop and debug them as you work with 1C:Enterprise. In this case
development and debugging is  performed much faster: the external data processor
(report) is  edited and saved in  the Designer mode without saving the entire config-
uration and is launched in the 1C:Enterprise mode. An external data processor
(report) is  launched using File – Open like any other data processor (report) in  the
configuration.
NOTE
External reports and data processors opened using File – Open are executed in  safe
mode (see page 1-182) if the user has no administrative access rights.
Any Report or Data processor configuration object may be copied to an external
data processor (report) file or vice versa – a  configuration object may be replaced
by an external data processor (report).
You can create Help Content for an external data processor (report), just as for any
other configuration object.
TIP
To ensure configuration integrity, it  is  recommended that external data processors
(reports) be used mainly for debugging purposes. After debugging the algorithm
of data processor (report) creation, it  is  necessary to include the external data
processor to the configuration.

5.12.1.1. Creation of an External Data Processor (Report)

To create an external data processor (report), use File  – New and select External
data processor or External report in  the dialog (see fig. 127).
This opens a form editor where you can develop an external data processor
(report). For an external report, the editing window also contains controls that can
be used to create, configure and edit the data composition system.
Chapter 5. Configuration Objects 1-305

Fig. 127.  Document Type Selection

Since an external data processor (report) is  not a  part of the current configuration
(although it  is  closely linked to it), the procedure for saving it  is  different from
the procedure for saving configuration changes (see page 1-48). To save an external
data processor (report), use File – Save, File – Save As or File – Save Copy. In  the
standard saving dialog box, select the External data processor (*.epf) (External
report (*.erf)) file type and enter the name for the external data processor (report).

5.12.1.2. Use of External Data Processors (Reports)

To use an external data processor (report) in 1C:Enterprise, you have to open
it  the same way as in  the Designer. However, please keep in  mind that an external
data processor (report) in 1C:Enterprise can be opened only for execution and
users cannot edit it. When the system attempts to open an external data processor
(report), it  checks access rights and sets the safe mode (if the user has no adminis-
trative privileges).
The external data processor (report) module is  compiled when the external data
processor (report) is opened. Therefore, after editing an external data processor
(report) in  the Designer and saving it, this data processor has to be reopened in  the
1C:Enterprise mode.
Besides, you can work with external data processors (reports) at the 1C:Enterprise
Server. In  this case, all restrictions applied to using interactive objects (forms, etc.)
are still valid.
If you want to use an external data processor (report) programmatically, you need
to connect it  to the server first, using the Connect() method (which is  only avail-
able at the 1C:Enterprise Server).
// Insert a  data processor into a  temporary storage at the client
StorageURL = "";
Result = PutFile(StorageURL,
"ExtDataProcessor.epf",
,
False);

...
1-306 1C:Enterprise 8.3. Developer Guide

// Connect the data processor to the server from the previously created
// temporary storage.
DataProcessorName = ExternalDataProcessors.Connect(TempStorageURL);

The name of the external data processor is stored in the DataProcessorName

variable. This name is later used to call the connected external data processor,
e.g., to open the data processor form:
// Open the form of the connected external data processor
OpenForm("ExternalDataProcessor."+ DataProcessorName +".Form");

A data processor (report) to be used programmatically can be saved at the following

locations:
„„ file stored in  the configuration (e.g., a  template)
„„ infobase data
„„ temporary storage (see page 2-841)
Names of external data processors (reports) must be unique within a  single session.
If you attempt to connect an external data processor (report) (programmatically or
interactively) and its name is  a duplicate of the name of a  data processor (report)
already connected to the current session, the system disconnects the previous data
processor and connect the new one.
NOTE
If you use external data processors (reports) at the thick client, please note that
in  the managed mode you can only open managed forms, while in  the ordinary
mode ordinary forms are only available.
When using external data processors (reports), please keep the following in  mind:
„„ If you connect a new data processor (report) with the name identical to the
name of a  previously connected data processor (report), open forms of the older
data processor (report) will not work (generate an error).
„„ When an external data processor (report) is  connected and this data processor
(report) being connected is identical to the one already connected, and their
safety mode property is the same, no actual re-connection occurs, no error
is  thrown. Alternatively, an external data processor (report) connected earlier
is  disconnected, and a  new external data processor (report) is  connected.
„„ When method Create() is executed, the SafetyMode method parameter
is ignored if the external data processor (report) was connected earlier with
method Connect(). If no connection was set earlier, the SafetyMode parameter
from method Create() will be used to connect an external data processor (report).
„„ When you get a form for an external data processor (report), an open form
is  retrieved, regardless of whether it  is  opened for the currently or previously
connected data processor (with the same name).
Chapter 5. Configuration Objects 1-307

„„ If you open a  data processor (report) using File – Open, its form is  opened with
the help of the OpenForm() method (with Uniqueness set to True); it  ensures
a  new data processor form can be opened in  case of modifications.

5.12.1.3. Editing an External Data Processor (Report)

You can edit external data processors in  the Designer.
Select File – Open to open an existing external data processor (report). Select the
External data processor (*.epf) (External report (*.erf)) file type in the standard
dialog box and specify the file name.
When an external data processor (report) is opened, the Designer automatically
opens the object editing window. Unlike other configuration objects, you can edit
an external data processor (report) without restarting 1C:Enterprise. After saving
the data processor (report) in  the Designer, you simply need to reload it  in  the
1C:Enterprise mode.

5.12.1.4. Help Content

An external data processor (report) can have a custom description. To edit
a  description, click the Open link for the Help content property in  the properties
palette of the external data processor.
To view an external data processor (report) description in  the 1C:Enterprise mode,
press the F1 key.

5.12.1.5. External Data Processors (Reports) and Configuration Objects

Existing Report and Data processor configuration objects can be converted into
external reports and data processors and vice versa. External reports and data
processors can also be added to the configuration structure as new configuration
objects of the Report or Data processor type.
Copying a  Data Processor (Report) to External Data Processor (Report)
An existing Report or Data processor configuration object may be copied to an
external data processor or report. To do this, select the object name in  the Configu-
ration window and select Save as External Data processor, report from the context
menu. Select the External data processor (*.epf) (External report (*.erf)) file type
in  the standard Save File dialog box and specify the file name for the external data
processor (report).
A new external data processor (report) will be created. It  will be a  copy of the
selected configuration object. The  configuration object itself will not change.
This operation is  useful for further debugging of a  report or data processor. When
debugging is  completed, you can re-insert the external data processor or report into
the configuration.
1-308 1C:Enterprise 8.3. Developer Guide

Replacement of a  Data Processor (Report) with

an External Data Processor (Report)
An external report or data processor may replace an existing Report or Data
processor configuration object.
To replace a  configuration object with an external data processor (report), select
its description in the Configuration window and click Replace to External Data
processor, report in  the context menu. Select the External data processor (*.epf)
(External report (*.erf)) file type in  the standard Open File dialog box and specify
the file name for the external data processor (report).

Addition of an External Data Processor (Report) to Configuration Structure

An existing external data processor (report) may be added to the configuration
structure as a  new Report or Data processor configuration object. To do this, select
any Report or Data processor configuration object in  the configuration structure
and click Insert External Data processor, report in the context menu. Select the
External data processor (*.epf) (External report (*.erf)) file type in the standard
Open File dialog box and specify the file name for the external data processor
(report) to be inserted into the configuration structure.
A new data processor (report) will be created in  the configuration tree.

5.12.1.6. Comparison and Merge of External Data Processors (Reports)

External data processors (reports) may be compared and merged with configuration
data processors (reports) or with other external data processors (reports).
To do this, select the required object in the Configuration window and click
Compare and Merge with External Data processor, report in the context menu.
Select the required external data processor (report) in  the standard file selection
dialog box.
The Compare and Merge… window will open. Actions available in  this window
are identical to those in  the Merge Configurations window (see page 2-1074), see
fig. 128.
To compare or merge an external data processor (report) with another external data
processor (report), open the source external data processor (report) in  the editing
window, click the Actions button and select Compare and Merge with External
Data processor from the drop-down list. Select the external data processor (report)
you need in  the standard file selection dialog. For a  description of further actions
see page 2-1074.
Chapter 5. Configuration Objects 1-309

Fig. 128.  Merging Data Processors

5.13. CHARTS OF CHARACTERISTIC TYPES

1C:Enterprise uses Charts of characteristic types to describe the characteristics of
analytical accounting objects.
Objects of this type may be used to describe the characteristics of goods or
contractors. They are used for analytical accounting for extra dimensions (not for
subaccounts) in  the chart of accounts. Chart of characteristic types do not describe
a  specific product or account; they only reference the description. Thus, manage-
ment accounting often has to describe not only mandatory features of goods like
their description, price, article and vendor, but also other features, such as color,
best before date, size, weight, flavor etc. Of course, different types of goods will
have different features (e.g., for footwear you need to specify the size, width, color,
material and other features, but these features are not needed for computer equip-
ment). In  this case it  is  sufficient to create the required description schemas at the
object level of the configuration and select the required description type (character-
istic type) for a  specific item.
You can use the 1C:Enterprise Designer to create any number of charts of charac-
teristic types as required for analytical accounting purposes.
Working with Chart of characteristic types objects is similar to working with
Catalog objects. Objects may also form hierarchical structure. They have the same
subordinate objects: they can be created and edited as an item, as a  list or in  both
ways, etc.
Configuration developers may create a  set of predefined items for Chart of character-
istic types objects. These items cannot be deleted in  the 1C:Enterprise mode.
However, configuring Chart of characteristic types objects has some differences.
A Chart of characteristic types object may have a  Characteristic value type property
which makes it  possible to define a  list of valid data types used for characteristic
types. Value types are selected on the Main tab of the object editing window.
1-310 1C:Enterprise 8.3. Developer Guide

A composite data type is  usually used. This  ensures you can specify the required
value when entering a specific characteristic. For example, the ProductChar-
acteristicTypes object of the chart of characteristic types is used to specify
extra dimension types for charts of accounts. This  object has a  composite type of
a  characteristics value (see fig. 130).

Fig. 129.  'Product Characteristic Types' Chart of Characteristic Types

Thus, when Chart of characteristic types objects are used to describe the structure
of a  chart of accounts, extra dimension types will be selected from predefined list
of characteristic types. When a specific account is created, specify which extra
dimension types are linked with this account.

Fig. 130.  Using Extra Dimension Types

Chapter 5. Configuration Objects 1-311

As the figure shows, account 30 Accounts receivable has two extra dimension
types – Company and Document – which are selected from a set of predefined
characteristic types specified in  this chart of characteristic types.
To maintain accounts for a  characteristic that has no description (catalog) in  the
configuration, use the Additional characteristic values property of the chart of
characteristic types. For example, you need to maintain accounts by cost centers,
but the configuration does not contain an appropriate catalog. In  this case you can
create a  custom CostCenter characteristic type and specify that items of an addi-
tional catalog will be used as values for this characteristic type. Since this catalog
is  subordinate to the chart of characteristic types, only catalog values subordinate
to the characteristic type may be selected. It  means values of different types will
not be mixed.
IMPORTANT!
When primitive types (Number, String or Date) are selected in  the Characteristic
value type property, specify the size or contents of the type in the value type
editing window so that this description covers all possible values. If fractional
parts are not specified for numeric types, you will not be able to enter fractional
numbers. Changes in  the description of numeric data after a  user has entered
values may result in  data loss.
To create predefined items in the Chart of characteristic types object editing
window, click Predefined at the Other tab. The  window for predefined items will
open.

Fig. 131.  Predefined Items in  Charts of Characteristic Types

Maintenance actions for predefined characteristics are available in the Actions

menu.
Predefined and custom items have different icon types in  the 1C:Enterprise mode.
In the 1C:Enterprise mode, you can change the value type for custom characteristic
items.
1-312 1C:Enterprise 8.3. Developer Guide

How to Create and Use a  Chart of Characteristic Types: Example

Please review a  sample structure of data used to store characteristics (irrelevant
table fields are omitted).
Nomenclature Catalog
Description
Vega 700 Telephone
Vega 300 Telephone
Omega Copier

NomenclatureCharacteristicTypes Chart of Characteristic Types

Description
Weight
Lifetime
Paper size
Main vendor

NomenclatureCharacteristics Information Register

Description CharacteristicType CharacteristicValue
(dimension) (dimension) (resource)
Ref: Vega 700 Telephone Ref: Weight 70
Ref: Vega 700 Telephone Ref: Lifetime 120
Ref: Vega 300 Telephone Ref: Weight 50
Ref: Vega 300 Telephone Ref: Lifetime 80
Ref: Omega Copier Ref: Weight 1300
Ref: Omega Copier Ref: Paper size  A4
Ref: Omega Copier Ref: Main vendor Ref: Priborpostavka 

Contractors Catalog
Description
Ref: Priborpostavka 

Add metadata objects (catalogs, a  chart of characteristic types and an information

register) with the specified structure to the configuration.
When you attempt to implement this example in  the configuration, you will face an
important question. You do not know what type needs to be selected for the Char-
acteristicValue resource of the NomenclatureCharacteristics register.
In practice, characteristics differ both in  their use and value types. This  is  where
features specific to charts of characteristic types acquire importance. Unlike cata-
logs, charts of characteristic types can contain descriptions of characteristic value
types. Metadata for charts of characteristic types include the Type property that
Chapter 5. Configuration Objects 1-313

describes characteristic value types. This property's type is  TypeDescription;

it  must include all value types available for various characteristics. For example,
in  this case you can specify the following types for the NomenclatureCharac-
teristicTypes chart of characteristic types: 
„„ String, length: 20;
„„ Number, format: 15.2;
„„ CatalogRef.Contractors.
This set of types must ensure all characteristic values in  the example can be stored.
After you select values for the Type property (characteristic value type) in the
chart of characteristic types, the list of available types will display Characte-
ristic.NomenclatureCharacteristicTypes.
Now, when selecting the CharacteristicValue resource type you can specify
the type (Characteristic.NomenclatureCharacteristicTypes) defined
by the chart of characteristic types. Please note that the type you should select
is  Characteristic.NomenclatureCharacteristicTypes, not ChartOf-
ChartOfCharacteristicTypesRef.NomenclatureCharacteristicTypes.
By selecting the Characteristic.NomenclatureCharacteristicTypes type,
you define the resource type indirectly, i.e. you do not specify specific types;
instead, you specify that the set of types is  defined by the types selected in  the
property of the chart of characteristic types. 
Therefore, creating the chart of characteristic types you determine that the database
can store a  list of product characteristic types and define the range of valid charac-
teristic values.
In addition to describing value types for all characteristic types, charts of char-
acteristic types can also be used to store value types for each characteristic type
in  the database since metadata are used to specify types for all possible character-
istic types, while individual characteristic types can have values of specific types.
For example, weight must be a  numeric value.
For this purpose, charts of characteristic types support a ValueType field.
This field's type is TypeDescription; it is used to describe valid types for
specific characteristic types. Therefore, the chart of characteristic types in this
example will have the following data structure:
NomenclatureCharacteristicTypes Chart of Characteristic Types
Description ValueType
Weight Number
Lifetime Number
Paper size String
Main vendor CatalogRef.Contractors
1-314 1C:Enterprise 8.3. Developer Guide

All objects required to store characteristics have been described. Please note,
however, that Nomenclature and CharacteristicType dimensions are unrelated
in  the system. Therefore, when you enter characteristic values the system ignores
the selected characteristic type; instead, it  prompts you to fill in  the field using all
types described in  the chart of characteristic types.
Structure description for the information register has no information about logical
links between the fields that store characteristic types and values. In  real-life solu-
tions this logical link can be quite complex. A characteristic type can be stored
in  other objects and defined by a  complex algorithm that depends on the subject
area. This is why a relationship between characteristic types and values are
configured by the configuration developer.
In this case you need to configure a  relationship between characteristic type and
value in  order to enter information register records.
To do this, set the Link by type property for the CharacteristicValue resource to
CharacteristicType.
Now, if a user changes the characteristic type and the existing value does not
match characteristic types for the selected value type, the value is  cleared.
If you want to try this example out, you should make another minor change in  the
configuration. Set the Master property for the Nomenclature dimension of the
NomenclatureCharacteristicTypes register. It removes characteristic data
when goods are deleted and displays the Open Information Register command
in  the catalog navigation panel.
Now you can check if the characteristic storing procedure is  fully implemented.
Open the Nomenclature catalog item, select the Nomenclature characteristics
hyperlink in  the navigation panel and start entering characteristics for a  specific
item. As you enter the characteristics, you can create new characteristic types and
select their value type.
The implemented solution has a major drawback. You have enabled entry of
primitive-type characteristics and reference types defined in the configura-
tion. This example uses a catalog of contractors to enter the main vendor.
It is obvious, however, that some properties need to have their values selected
from lists. On the other hand, lists of values for various properties are different.
Accordingly, you cannot select values for these properties from catalogs existing
in  the configuration. In  this example paper size is  entered as a  string. It  would
be more convenient to select a  value for this property from a  list of available sizes;
however, you cannot create catalogs for each characteristic type in  the configura-
tion, since catalogs are created at the configuration development stage, while new
characteristic types are entered as you use the application.
Charts of characteristic types can help you deal with this issue. You can use
a subordinate catalog to store values of characteristics that cannot be selected
from catalogs, enumerations and other content existing in the configuration.
Chapter 5. Configuration Objects 1-315

Create a CharacteristicValues catalog and specify it is subordinate to the

NomenclatureCharacteristicTypes chart of characteristic types. Next, select
this catalog as a  value for the CharacteristicExtValues property of the chart
of characteristic types. Additionally you need to add a  CatalogRef: Characteris-
ticValues type to the Type property of the chart of characteristic types. 
Now the chart of characteristic types can use the CharacteristicValues catalog
for characteristic value lists. Change ValueType for the Paper size characteristic
type by selecting CatalogRef: CharacteristicValues. When you fill in  the charac-
teristic value, you will be prompted to select it  from the catalog list limited by the
owning Paper size characteristic type.
The structure of data in  the resulting example will look like the following:
Nomenclature Catalog
Description
Vega 700 Telephone
Vega 300 Telephone
Omega Copy Duplicator

NomenclatureCharacteristicTypes Chart of Characteristic Types

Description ValueType
Weight Number
Lifetime Number
Paper size CatalogRef: CharacteristicValues
Main vendor CatalogRef: Contractors
Casing color CatalogRef: CharacteristicValues

NomenclatureCharacteristics Information Register

Description (dimension) CharacteristicType (dimension) CharacteristicValue (resource)
Ref: Vega 700 Telephone set Ref: Weight 70
Ref: Vega 700 Telephone set Ref: Lifetime 120
Ref: Vega 300 Telephone set Ref: Weight 50
Ref: Vega 300 Telephone set Ref: Lifetime 80
Ref: Omega Copy Duplicator Ref: Weight 1300
Ref: Omega Copy Duplicator Ref: Paper size  Ref: A4
Ref: Omega Copy Duplicator Ref: Main vendor Ref: Electronica 

Contractors Catalog
Description
Priborpostavka 
1-316 1C:Enterprise 8.3. Developer Guide

CharacteristicValues Catalog
Owner Code Description
Ref: Paper size 1 A3
Ref: Paper size 2 A4
Ref: Casing color 3 White
Ref: Casing color 4 Silver

You can use charts of characteristic types to enter characteristic types as you
work with the infobase. However, you can also create predefined characteristic
types in  the configuration. You are recommended to create these types as values
corresponding to the operation logic of the configuration, rather than as default
characteristic types. An example could be a  New Year discount percentage. If you
enter this characteristic for a  product, the price calculation algorithm can use it  to
define a  selling price in  the period preceding the New Year. 

5.14. REGISTERS
1C:Enterprise registers are mainly used to store and process information about the
company's business or organizational activities.
Document and Catalog type infobase objects are used to store information about
actual objects of a  subject area, such as employees, goods, material and currency.
Each database object corresponds to an actual object of a  subject area.
Registers usually store information on changes in the status of objects or other
information that does not directly reflect subject-domain objects. For example,
registers can hold information on currency exchange rates or information on the
receipt and dispensing of merchandise.
A database object is independent of its attributes and has its own value. For
example, an employee may change their last name, passport number or any other
attribute. However, the employee will still be the same individual.
After you delete an object, you cannot create it  again. Even if you make all of an
object's attributes the same as those of the deleted object, it will be a different
object. The system stores an internal object ID – a reference. A reference
is unique within the entire infobase. No two objects may have the same refer-
ence in  the entire lifetime of the infobase. References of the deleted objects are
not assigned to new objects. Database object references may be stored in  database
fields.
The information in  registers is  stored in  records. Use of a  register record depends
only on the data that are stored in  this record. For example, a  currency exchange
rate record does not represent anything material. It does not correspond to any
physical object. The only important factor is that it contains currency, a date
and the exchange rate set for this date. This  record may be deleted and replaced
with the same record, but this will not affect the logic of the system. Accordingly,
Chapter 5. Configuration Objects 1-317

register records do not have references and references to register records may not
be stored in  database fields.
This section describes information and accumulation registers. For information
about accounting registers see page 1-660; for information about calculation regis-
ters see page 1-668.

5.14.1. Information Registers

Here you will learn, what an information register is  and how information registers
should be used.

5.14.1.1. Data Register Overview

The main purpose of an information register is  to store existing information for
the application task, whose makeup extends to a  certain combination of values and
when necessary, extends over time. For example, if we want to store information
about competitors’ prices for the goods that we sell, this information could be
expanded by adding goods or competitors. If we also want to track price move-
ments and if we enter this information periodically, the stored information can be
expanded over time, as well.
1C:Enterprise uses a  special mechanism – information registers – for storing these
data and working with them.
An information register is a multi-dimensional data array needed to imple-
ment a function that provides the required information for a specific set of
arguments. Function arguments are called dimensions and function results are
called resources. In the example given above, the two-dimensional register
CompetitorsPrices will have Competitor and Product as its dimensions and
Price as its resource. You can have more than one resource. For example, you can
store the wholesale and retail prices.
In addition to dimensions and resources, you can create a  set of attributes for an
information register. Attributes can be used to add any information to register
records. Attributes do not influence values of register resources and may be used to
analyze register records.
Information registers whose data extend over time are called "periodic". For
periodic information registers, the system also supports standard operations such
as getting the latest or earliest value (for example, getting the last price entered
for a  particular product and a  particular competitor) and also getting a  slice of the
latest or historical values. For example, all the latest prices for various goods and
competitors can be retrieved.
To expand the information over time, use the Period field in  the register. It  is  not
entered as a dimension, but is automatically added by the system when a peri-
odical register is  created.
1-318 1C:Enterprise 8.3. Developer Guide

It is not necessary to create dimensions for information registers. In this case

a  register is  actually a  set of periodical data. Such registers may be used to store
the last names of the officers responsible for signing documents. Documents are
created and signed by officers with the right of signature at a  certain point in  time.
For information on how to use constant values for these purposes see page 1-279.
One drawback of this method is  that when the value of a  constant changes, a  new
name will be shown in  archive documents. In  such cases, it  is  necessary to use
a periodical information register instead of a constant. This periodical informa-
tion register stores information about changes and documents use values from the
information register depending on the date.
Currency exchange rate is the most typical example of a one-dimensional peri-
odical value. When some calculations are performed (e.g., when a  price in  dollars
is determined by recalculating a price in euro according to the exchange rate),
it  is  important to know this value at the time of the calculation.
It is especially important to know the currency exchange rate when performing
certain calculations post factum. In  this case it  is  necessary to recall the exchange
rate for past dates.
To make it  possible to obtain such information, it  is  necessary to create a  table
that contains three columns: currency name, date and currency exchange rate.
The rows of this table contain the exchange rates for several currencies on
a  specific date.
Date Currency Rate
31.10.2008 USD 26.5430
31.10.2008 EUR 35.0447
01.11.2008 USD 27.0981
01.11.2008 EUR 34.4092
02.11.2008 USD 27.0793
02.11.2008 EUR 34.4828

When you open a table like this, please keep in mind that the Rate column
contains specific exchange rates for a  certain date and it  is  assumed the rate does
not change for all the following dates until the next rate is  available. Therefore, to
obtain the exchange rate for an intermediate date, you should take the rate for the
closest previous date with a  recorded exchange rate.
It is also necessary to remember that different values in the Currency column
mean that a  parallel history of exchange rates is  maintained for several currencies.
In  other words, the table shown above can be represented in  a different way:
Date USD Rate EUR Rate
31.10.2008 26.5430 35.0447
01.11.2008 27.0981 34.4092
02.11.2008 27.0793 34.4828
Chapter 5. Configuration Objects 1-319

Such a  table may contain any number of columns, depending on the number of
currencies for which exchange rates need to be stored.
If a  register is  not periodical, no Period field is  created for it. In  the example
above, the CompetitorPrices register may be non-periodical if you do not want
to store the price change history (you only need the current prices). In  this case
the register function can be used to tell us what a  specific competitor's price is  for
a  specific good currently, but it  will not be able to tell what the price was at the
beginning of the year.
These principles imply that the system can only have one record with a  specific
set and period of dimensions. In  fact, there really can be only one price for each
product of each competitor. If, for any reason, we can obtain multiple prices and
want to store this information in  the database, we need to create another dimension
to store a  value that makes these prices different. For example, you can create an
InformationSource dimension. In  this case we will be able to enter competitors’
prices from different sources.
Uniqueness of the records in  a dimension set makes information registers funda-
mentally different from accumulation registers where multiple records can be
entered with the same value and period.
If receiving data as of the very first moment or the most recent (current) moment
is  the most frequent use of the register, then it  makes sense, with regard to such
registers, to allow the system to support totals for the slice of the last data (Allow
totals: section of last property) or the slice of the first data (Allow totals: section of
first property). An example of such use is  a register with the sales prices of goods.
The  item price can change, but queries for the current price are the most common
queries to this register.
Information register totals will be used if all of the following prerequisites are met:
„„ Totals use in  the configuration is  allowed for the register.
„„ Totals use in  1C:Enterprise mode is  allowed for the register.
„„ Data as of the very first date (the slice of the first data) or the last (current) date
(the slice of the last data) is  received without specifying the period value.
„„ Conditions for the SliceFirst and SliceLast virtual tables are set only for
values of dimensions and separators that are in  the Independent and Shared
mode.
„„ Only dimensions and separators in  the Independent and Shared mode are used
in  data access restrictions.
If none of the above is  met, the standard query is  used to get the information from
the register.
1-320 1C:Enterprise 8.3. Developer Guide

5.14.1.2. Information Register Records

Lines of the information register containing information about resource values for
specific dimensions and specific periods, are called records. A record key can
be used to identify information register entries. Records may be entered into the
information register in  two ways:
„„ Manually
„„ Using documents
For information on selecting the record entry method see page 1-320.
These two options only influence the way the information is  entered and have no
impact on the main principle of the register functioning.
A document that enters a  record into the information register is  called a  recorder.
Registers that are recorded independently may be freely edited manually or using
the 1C:Enterprise script tools. If a  dimension of such a  register is  assigned as the
master dimension and its value is  a reference to a  database object, this record will
make sense only while this object exists. For example, if you specify Competitor
dimension as the master dimension, it  is  considered that this record makes sense as
information about this competitor. Correspondingly, when a  competitor is  deleted,
all related records will be deleted automatically.
If a register is maintained by a recorder, this means that the records in this
register will be strictly subordinate to the recorder documents. Usually it  means
that records are created when documents are posted. When a  document is  deleted,
the records will be deleted automatically. Unlike master dimensions, there may be
only one recorder.
You should remember that an information register record key created with the help
of the EmptyKey() method is  not equal to the information register record key, the
dimension values of which are equal to default values for its own types.

5.14.1.3. Information Register Editing

The Information registers branch of the configuration tree is used to work with
information registers.
Editing a  register includes specifying its properties and developing its structure:
sets of dimensions, resources and attributes, screen forms for viewing and editing
records and (if necessary) print forms (see page 1-59).
Here you will find information about properties specific to information registers.
They supplement common properties of all configuration objects.
Use the Information register editing window to edit registers. Register properties are
arranged in  tabs (see fig. 132).
Periodicity. This property defines how often resource values are saved in the
register.
Chapter 5. Configuration Objects 1-321

Fig. 132.  Information Register Editor

This property directly influences the possibility of obtaining register resource

values using the 1C:Enterprise script methods. For a  non-periodical register, you
can obtain only the last entered value of a  register resource – information from
previous periods is  not available in  such a  register. For periodic registers, a  value
with a  periodicity smaller than the specified register periodicity cannot be obtained.
Periodicity does not depend on the register editing type.
Write mode. This  property determines how records are entered: independently (for
example, manually) or subordinate to the recorder (for example, using documents).
If a  register is  periodical and the independent write mode is  selected, the Include
period in  the main filter property becomes available. If this option is checked,
in  addition to the main dimensions and attributes of the register, the user can also
filter records by the Period field.
The Data tab is  used to generate the data structure of a  register. Use it  to create
dimensions, resources and attributes.
The Recorders tab is  used to manage the list of recorders. This  tab is  available
only if the Write mode property is  set to Subordinate to recorder (see fig. 133).
The top list is  used to manage the recorder list (check or uncheck boxes) and the
bottom list contains the selected recorder objects.
Similarly to managing the recorder list in  information registers, you can manage
recorder lists in  registers of other types.
1-322 1C:Enterprise 8.3. Developer Guide

Fig. 133.  Setting Recorder for an Information Register

Resources in  an information register can have a  wide variety of data types, while
other registers can only contain numeric resources.
For a  description of how to create forms and templates see page 1-47.

5.14.1.4. Development of Information Register Structure

To develop an information register structure, you need to create sets of dimensions,
resources and attributes.
To manage a  register's list of dimensions, resources and attributes and edit their
properties, use the Dimensions, Resources and Attributes folder controls in the
Register editing window. The setup procedure for the items of these folders
is  identical. For information about how to use these controls see page 1-59.
Properties of Information Register Dimension (Resource, Attribute)
Properties of dimensions, resources and attributes are edited using the proper-
ties palette. They are mainly the same as common properties of all configuration
objects. Unique properties of dimensions, resources and attributes are described
below.
Master. This property is meaningful for dimensions that contain a reference to
configuration objects. If this property is  turned on, the information register record
is  meaningful only as long as this object exists. If the object is  deleted, all related
records will be deleted from the register.
Chapter 5. Configuration Objects 1-323

No Empty Values. If this option is  checked, register records cannot have empty
dimension values.
Index. This dimension property may be edited for non-master dimensions. For
dimensions, resources and attributes with the Index property turned on, a  separate
index is  created, thus increasing register performance. Index is  always created for
master dimensions.
When a register is viewed in the 1C:Enterprise mode, you can sort register
records by indexed dimensions, resources and attributes. The  required number of
forms for register viewing and editing has to be created at the configuration devel-
opment stage.
Ordering Information Register Dimension List
The arrangement of an information register's dimensions is  very important.
If you need quick access to some dimensions, place them at the beginning of the
list.
The sequence of information register dimensions influences the possibility of using
1C:Enterprise script methods that employ positional access to dimensions.
You should also remember that changing the order of dimension requires restruc-
turing of the infobase.

5.14.2. Accumulation Registers

Accumulation registers are used in 1C:Enterprise to store information about
availability and movements of certain values (material, cash, etc.). All data on
commercial transactions that are entered using documents or generated using
calculations must be accumulated in  registers. In  this case they can be retrieved,
analyzed and displayed to a  user in  report forms.
Here you will learn about accumulation registers and the basic principles of using
them.

5.14.2.1. Accumulation Register Overview

An accumulation register is a configuration object designed to store register
records and total data.
A typical problem you may face when creating a  summary information "storage"
is the structure decisions: what points to choose for accumulating the summary
data to ensure a  simple retrieval of the required information. The  1C:Enterprise
system uses simple but flexible means to generate accumulation registers.
You only need to specify what points and data need to be stored in  the register, and
the system itself will ensure recording and retrieval of data using simple language
resources.
1-324 1C:Enterprise 8.3. Developer Guide

The 1C:Enterprise script methods allow to retrieve accumulation register balance

for a  specified point in  time. You can filter data by dimension values or obtain
balances by other dimensions.
Consider the following example. Say you are creating a sales and warehouse
accounting program and you need to store information about the quantity and price of
each product in  each warehouse. You want to get information such as the remaining
inventory of a  specific product at a  specific warehouse, the remaining inventory of
a  specific product at all warehouse, the cost of all goods at warehouse, etc.
In 1C:Enterprise, such an accumulation register is  a rectangular system of coor-
dinates. One of its axis contains warehouses, the other – goods. The  intersections
between goods and warehouses contain the values of a  product's quantity and cost.

Fig. 134.  Accumulation Registers

It is  hard to explain the physical meaning of an accumulation register, since it  does
not have any material counterpart.
IMPORTANT!
Therefore, let us specify that an accumulation register is  an n-dimensional system
of coordinates for storing joint data. The  axes of such coordinate systems are
called register dimensions and the stored data are called register resources.

5.14.2.2. Records of Accumulation Registers

The state of accumulation registers usually changes when a  document is  posted.
The  document posting procedure is  located in  the document module. It  contains
an algorithm of generating data on register changes to be made when the docu-
ment is  posted. This  information is  called register records. The  totals calculation
mechanism uses register records to make direct changes in  accumulation registers.
Therefore, register records contain only increments (positive or negative) of register
resource values, not the total values.
A system configuration specialist can allow end users to track register records.
The Designer can be used to create screen and print forms for viewing and
analyzing register records.
Chapter 5. Configuration Objects 1-325

You can create any number of accumulation registers at the configuration develop-
ment stage. However, you should remember that if there are too many accumulation
registers, this might reduce system performance during document posting.
In addition to dimensions and resources, you can also create a  set of attributes for
an accumulation register. Attributes may be used to add any information to register
records. Attributes do not influence values of register resources and may be used to
analyze register records.

5.14.2.3. Totals of Accumulation Registers

As pointed out above, register changes are implemented by register records.
Register records influence the register's totals. Totals are summarized register
information obtained by summing up the values of register records.
The totals of an accumulation register may be represented as a  table with a  number
of columns equal to the number of dimensions and resources in  the accumulation
register. The number of rows in the table depends on the number of different
dimensions and resources:
Product Warehouse Count Total
Table Retail 10 5 000
Table Wholesale 5 2 500
Cabinet Temporary 7 10 500
Cabinet Wholesale 2 3 000
Cabinet Retail 10 15 000

You can see in  the table that the Product dimension has the Table and Cabinet
values, while the Warehouse dimension has the Temporary, Wholesale and Retail
values. The  Count and Total columns for the accumulation register's resources
contain the quantity and total value for each product at the warehouse.
Unlike register records, you cannot view totals of accumulation registers directly.
To obtain totals information, you can create any number of reports in  the configu-
ration. These report will query the totals and display them as product reports,
warehouse cards, lists, etc.

5.14.2.4. Balance Registers and Turnover Registers

In the 1C:Enterprise system, you can use two types of accumulation registers:
balance registers and turnover registers.
Balance registers can use the 1C:Enterprise script methods to get accumulation
register balances for a  specified point in  time. You can filter data by dimension
values or obtain balances by other dimensions.
Turnover registers are used to store information that cannot have any balance, e.g.,
sales volume for different customers.
1-326 1C:Enterprise 8.3. Developer Guide

As an example, review how settlements with buyers of goods manufactured or sold

by the company (or consumers of the company's services) are tracked. This  kind of
accounting is  usually mandatory for every enterprise.
To be able to obtain current information about how much the enterprise and one
of its customers owe each other, it is necessary to use a Settlements register
which will store the amount of debt for each customer. When a  business transac-
tion occurs, the register is  updated according to the current state of settlements.
The  Settlements register is  a balance register.
However, it  is  impossible to obtain information about volumes of purchases for
a specific customer in a certain period of time from the Settlements register,
since it does not store this information. Therefore, additional effort is required
to get this information: for example, you can include a  Contractor attribute in  the
register structure, then select register records for each contractor, and calculate the
total amount of purchases. However, if you need this information in  real time (e.g.,
when a customer is eligible for a discount upon reaching a certain volume of
sales), this method is  not applicable.
In this case you can use a  turnover register. This  register (let us call it  Purchase
Volume) will store information about sales volume for each customer (turnover
with the customer).
Now, for business transactions, it  would be necessary to change both the Settle-
ments register and the Purchase Volume register. After each purchase, information
about the amount of the purchase will be recorded to this register. As a  result, the
Purchase Volume register will constantly accumulate information about the total
volume of purchases made by the client.
All of this makes the advantages of registers quite clear.
First of all, registers are used to store information that needs to be accessed quickly.
A 1C:Enterprise configuration specialist must determine whether information
is needed quickly and whether it is necessary to use a register, based on the
requirements of system users.
Registers also make it possible to obtain the most accurate information about
current funds. As the processes of saving documents and recording changes
in registers are separate (a document may be saved without posting), the data
in  documents and in  registers may differ. However, registers (unlike documents)
are a storage of totals information, i.e. changes recorded in registers confirm
completion of a  business transaction.

5.14.2.5. Main Properties of Accumulation Registers

The Accumulation registers branch of the configuration tree is  used to work with
accumulation registers.
Use the editing window to edit properties of Accumulation register objects and
create subordinate objects (see page 1-59).
Chapter 5. Configuration Objects 1-327

When you edit an accumulation register, you specify its type and develop its struc-
ture:
„„ Create sets of register dimensions, resources and attributes;
„„ Create screen and print forms to view register records, if necessary.
NOTE
Such values as UUID, BinaryData, and any unlimited length string cannot be the
accumulation register dimension type.
This section describes unique properties of accumulation registers that supplement
common properties of all objects.
Register Type specifies if a  register can be used:
„„ To store balances (select Balance from the list),
„„ To store turnovers (select Turnovers).
See page 1-325 for a  description of the differences between the balance register
and the turnover register.
Default List Form. A register may contain several forms for tracking its records.
If there are multiple forms for entering and selection, you can specify the default
form in  the Default List Form property.
Enable totals split. If this check box is  set to True (default value), totals splitter
mechanism is  used to ensure a  greater concurrency of writing to the register. If
the system writes records in  multiple concurrent sessions, it  does not update the
same totals records; it  writes each change in  the totals as a  separate record. To
obtain totals, these values are summed. This  way, totals are kept up-to-date (this
is  useful for quick generation of reports, for example) and register records can be
made concurrently. This  mode requires more resources (for instance, the amount
of data in  totals tables is  bigger in  this case). This  is  why both the configuration
and the 1C:Enterprise script contains properties that manage this mode.
Records multiply only when transactions are performed concurrently. Their
quantity for each combination of dimensions depends on the maximum number of
concurrent transactions. When recalculating totals, separate accumulated records
are collapsed.
The totals splitting mode can be modified by the user in  the 1C:Enterprise mode.
By default this property is  enabled.
Use in  totals. If this check box is  set to False, the dimension is  excluded from the
stored register totals.
Several forms can be created to view the register records. If there are several forms
for data input and selection, you can specify the form to be used by default in  the
Default List Form property.
1-328 1C:Enterprise 8.3. Developer Guide

5.14.2.6. Aggregates of Accumulation Turnover Registers

You can use aggregates to boost system performance when using accumulation
turnover registers. Aggregates can be represented as special storages that can be
used with queries in  1C:Enterprise.
Major Concepts
Terms used to describe aggregate operation are defined below in  this section.
Aggregate is  a physical database table that stores summary totals for all register
resources by the selected dimensions with the specified periodicity in  a specific
period. If a  register uses aggregates, it  can have up to 30 dimensions.
Aggregates are defined by the following parameters:
„„ Aggregate size: aggregate table size. Estimate.
„„ Effect: expected reduction in  average time of query execution with aggregates.
For example, if the aggregate effect is 90%, it means the average time of
query execution with aggregates is  90% less than the average time of executing
the same query with totals. Estimate.
Aggregate period is  a range of dates used to insert data in  the aggregate.
Aggregate periodicity is  periodicity used to store data in  the aggregate.
Aggregate list is  a set of aggregates created at the configuration stage. The  list
can be either manually generated or loaded from a  file resulting from the calcula-
tion of optimal aggregates.
Use statistics is information about the type of queries (dimensions, period and
periodicity) to the recorder. These data allow you to rebuild aggregates and obtain
an optimal aggregate list.
Optimal aggregate list is  a list of aggregates with an optimal size-effect correla-
tion for the register in  its current state (register records and use statistics).
Aggregates/totals mode: If you select the aggregates mode, queries are executed
using aggregate data; if you set the totals mode, queries use totals data.
Use aggregates: You can disable use of aggregates to perform no operations with
aggregates when register records change. It makes sense to disable aggregates
while you mass-load data into the registers; however, enabling aggregates later
could require a  lot of resources to update the aggregates (if the modified data fall
within the aggregate period).
General Flowchart for Working with Aggregates
Review the following general flowchart for working with aggregates (see fig. 135).
NOTE
This flowchart demonstrates how to work with a  single register. If you want to
work with multiple register, you need to perform every step for each individual
register.
Chapter 5. Configuration Objects 1-329

Fig. 135.  General Flowchart for Working with Aggregates (client/server variant)

Let us examine the working procedure in  greater detail:

1. Create a list of required aggregates in Designer. This is an optional step.
Creating aggregates in  Designer mode can be used if the constant use of an
aggregate in  any infobase needs to be supported.
There are several ways to create aggregates in  Designer:
○○ Calculate (i.e., in  totals mode) and load optimal aggregates (DetermineOp-
timalAggregates()). If aggregates have not been previously used, a  list
of optimal aggregates will be received on the basis of the register record
table. If aggregates have been previously used, a  list of optimal aggregates
will be built on the basis of a  table of records and the usage statistics.
○○ Create an own list of aggregates based on register queries analysis.
2. After the database configuration is updated, enable aggregate mode for the
register (SetAggregatesMode()method).
3. You then need to rebuild aggregates on a regular basis (RebuildAggre-
gatesUsing()method). During this operation, the system adds the required
aggregates and deletes ones that are not used. This  operation is  performed if
the current list of aggregates is  not optimal. Only the aggregates created during
the rebuilding operation are deleted. The aggregates created in Designer are
not deleted automatically, and if the aggregates are created in Designer, the
following actions will be taken during the rebuilding operation:
○○ An aggregate will be enabled if the aggregate’s use case is  set to Always.
Performance evaluation of the aggregate does not impact its usage.
1-330 1C:Enterprise 8.3. Developer Guide

○○ If the aggregate’s use mode is  set to Auto, the aggregate will be enabled
based on performance evaluation. The use of this aggregate is evaluated
together with the aggregates automatically created by the system. If an
automatically created aggregate performs better than the aggregate created
in  Designer with Auto use mode, an automatically created aggregate will
be used instead.
4. Aggregate updating must be completed afterwards (UpdateAggregates()
method). When aggregates are updated, data from the selected register records
table is moved to the corresponding aggregate tables. The records created
in  the records table after the previous aggregate update are moved.
5. Next, the usage statistics of the aggregates created should be accumulated.
To do this, perform standard tasks that use data from the register for which the
aggregate mode has been enabled within a  certain period of time (e.g., within 1
month). Regular aggregate updates must be performed while working. When the
period ends, rebuild the aggregates (step 3) and perform steps 3–5 on a  regular
basis.
The described schema details an approach to working with the register’s aggregates
in  a client/server mode.
Working with aggregates differs a  little when it  comes to file-based usage of the
system:

Fig. 136.  Working with aggregates (file-based variant): an overview

Chapter 5. Configuration Objects 1-331

The major differences between this approach and a  general approach to working
with aggregates (see fig. 137) is  as follows (only the differences are described):
„„ At step 1 a  list of aggregates must be created in  Designer.
„„ Step 6. Recalculation of optimal aggregates (DetermineOptimalAggre-
gates() method) should be performed regularly (e.g., once a  month). During
this period (1 month), standard tasks that use data from the register for which
the aggregate mode has been enabled should be performed. Regular aggregate
updates are needed while working.
„„ Step 7. When a  new list of optimal aggregates is  received, the user needs to
define whether or not a  list of aggregates needs to be changed in  the configura-
tion metadata. If no changes are required, proceed to step 3.
„„ Step 8. If a  list of aggregates needs to be updated, load the required (or all)
aggregates (from a  list of optimal ones). Update the database configuration (the
infobase will be restructured) and then proceed from step 3.
For guidelines on each of these steps, see the next section.

Recommendations on How to Use Aggregates

Generation of Aggregate List
You can generate a  list of aggregates using one of the available methods.
If you want to enable aggregates for a  register that exists in  the configuration, but
has never used aggregates, you can do the following:
„„ If the register has no or few records (up to 2 or 3 thousand records), analyze
queries that use this register to obtain a list of frequently used dimensions,
filters, query periods and data retrieval periodicity. Based on the information
you obtain, create a  list of aggregates while minimizing the number of aggre-
gates.
„„ If the register uses a  big number of records (more than three thousand), you can
calculate optimal aggregates based on the register data using the DetermineOp-
timalAggregates() method and then load the resulting list of aggregates.
„„ If the register you use already has the aggregates mode and use enabled (i.e.
the initial list of aggregate has been generated), you can also retrieve a list
of optimal aggregates and load it in the Designer. This method is different
from method 2, since in  this case the calculation of optimal aggregates uses
the system statistics. Therefore, the resulting list of aggregates is  more efficient
compared to the list obtained for a  register with the disabled aggregates mode
and use.
NOTE
Optimal aggregates method is  convenient, only if the table of register records
contains at least three to five thousand records. If the number of records is  below
this figure, the obtained list of aggregates might prove inefficient.
1-332 1C:Enterprise 8.3. Developer Guide

Rebuilding
You should rebuild aggregates at least as often as you calculate the list of optimal
aggregates. This operation does not modify the list of aggregates; instead,
it  attempts to use the existing aggregates only.
You should also keep in  mind that the rebuilding operation is  only efficient if you
have a  considerable amount of statistical data.
Although it is hard to recommend when you need to rebuild aggregates in the
most general case, major factors can be pointed out:
„„ when it  is  probable the nature of register data has changed;
„„ when it is possible the nature of queries has changed (which modifies the
accumulated statistics).
When you perform the operation, you are required to specify two parameters:
„„ Maximum relative size – limits the size of the generated aggregate list
(percentage of the record table size). If it  is  set to zero, there is  no limit on the
aggregate list size.
„„ Minimum effect – percentage of improvement in  the process of rebuilding the
older list. If the new list improves the effect by the specified value, the method
rebuilds the list. If the parameter has no value or is set to zero, there is no
minimum effect requirement.
The current list of aggregates is also rebuilt if its size exceeds the value in  the
Maximum relative size, % parameter or the resulting list is  at least as efficient as
the double value of the Minimum rebuild effect, % parameter. Otherwise the list of
aggregates is  not rebuilt.
NOTE
The rebuilding operation takes a  lot of time and resources. You are not recom-
mended to run this operation when other users actively use the infobase.

Aggregate Update Operation

You are recommended to run this operation more often than the aggregate
rebuilding operation.
You can update aggregates in  two ways:
„„ Run a complete update of all aggregates marked as used. This might take
a  long time.
„„ Use the so-called "partial" filling. In  this case a  single run updates 10 aggre-
gates for a  period of one month.
When you perform this operation, you should indicate the Maximum relative size.
It  limits the size of the generated aggregate list (as percentage of the record table
size). If set to zero, there is  no limit on the aggregate list size.
Chapter 5. Configuration Objects 1-333

NOTE
You are recommended to run this operation when the load on the infobase
is minimal.

TIP
You are recommended to use the totals splitting mode when using aggregates,
especially if aggregates are updated by a  scheduled job and at the same time
documents are posted for a  register that updates the aggregates.

Use of aggregates
To define an aggregate to be used for a  query, use the algorithm described below.
A query defines the register dimensions to be used, selects a  list of aggregates that
contain all dimensions used and match the query by frequency and period the best.
Next, an aggregate with the minimum size is  selected from the list. This  is  the
aggregate that will be used.
A query may use an aggregate with a lower frequency than the frequency set
in  the query. In  this case, the required data will be obtained by adding data from
shorter periods.
Sometimes a  period specified in  the query does not match the aggregates period.
In  this case, two aggregates can be used to execute a  query. Let us take a  look at
an example. For instance, an infobase includes two aggregates that cover the entire
query period:
„„ With monthly periodicity;
„„ With daily periodicity.
The query is  executed for the period from September 15 to November 15. In  this
case, two aggregates will be used:
„„ An aggregate with a monthly periodicity will be used to obtain data from
October 1 to October 31;
„„ An aggregate with a daily periodicity will be used to obtain data from
September 15 to September 30 and from November 1 to November 15;
„„ Data from the different aggregates will be added together to obtain the final
result.
A virtual turnover table of the register for which the aggregate mode is  enabled
always contains actual data.

Optimal Aggregate Calculation

You can run this operation as needed; it  is  not regular. Below is  a list of condi-
tions when you are recommended to calculate optimal aggregates:
„„ when some time elapses after you generate the initial aggregate list;
„„ if performance reduces significantly as you use the current aggregate list;
1-334 1C:Enterprise 8.3. Developer Guide

„„ if data nature changes significantly;

„„ if the set of queries to the register changes;
„„ if it  is  probable that the current aggregate list is  no longer optimal.
NOTE 1
This  operation is  optional for the client/server variant. Optimal aggregates are
created automatically (if necessary) when aggregates are rebuilt.

NOTE 2
This operation takes the longest time and the biggest amount of resources.
We strongly recommend running it  only when other users do not work with the
infobase.

Using scheduled jobs when working with aggregates

Rebuild and refresh aggregate operations can be executed with scheduled jobs.
You should follow the recommendations below when creating a schedule for
performing scheduled jobs:
„„ For a  scheduled job that performs rebuild and refresh operations, setting the
Key property of a  scheduled job is  recommended (see page 2-827).
„„ Setting a  schedule for scheduled rebuild and refresh jobs is  recommended to
avoid simultaneous execution of rebuild and refresh operations.
If you follow these recommendations, you can prevent simultaneous execution of
rebuild and refresh operations, which positively affects performance.

Aggregate Editing
You can only create and edit a list of aggregates for an accumulation turnover
register (the Register Type property is  set to Turnovers). If you want to call the
aggregate wizard, use the Open aggregates command in  the register context menu.

Fig. 137.  Calling the Aggregate Wizard

Chapter 5. Configuration Objects 1-335

It opens the aggregate wizard window where you can manage aggregates of an
accumulation turnover register. You can manage aggregates manually or load
a  ready-to-use list of optimal aggregates (use a  special button at the command bar).

Fig. 138.  Aggregate Wizard

As you create aggregates, you can specify their use. If it's Auto (by default), the
system independently determines whether an aggregate needs to be used during the
aggregate rebuilding operation. If Always is  selected, the system always uses this
aggregate.
The Periodicity column defines the minimum time period for storing totals for the
selected dimensions in  the aggregate. You are allowed to have multiple aggregates
with identical dimension sets and differing periodicity. Be sure not to overuse
aggregates. A big number of aggregates can excessively expand the database
without increasing query performance.
You can use the right-hand area of the window to indicate dimensions to be
included in  the edited aggregate. An aggregate can contain any number of dimen-
sions (up to 30) or have no dimensions. In  this case summary turnovers for the
register are saved with the specified periodicity.
If the list of optimal aggregates is stored in an xml-file, you can load this list.
To do this, use a  special command of the aggregate wizard (see fig. 139) and select
the ready-to-use list.

Fig. 139.  Loading Optimal Aggregate List

1-336 1C:Enterprise 8.3. Developer Guide

The system compares the list from the file with the current aggregate list and high-
lights the aggregates recommended to be added (from the Optimal Aggregates list)
and the aggregates recommended to be deleted (from the Aggregates list). You can
choose not to implement the recommendations or implement them partially.

5.14.2.7. Development of Accumulation Register Structure

To develop a  register structure, you need to create sets of dimensions, resources
and attributes at the Data tab (see page 1-59).

Properties of Accumulation Register Dimension (Resource, Attribute)

Properties of dimensions, resources and attributes are edited using the proper-
ties palette. They are mainly the same as common properties of all configuration
objects. Unique properties of dimensions, resources and attributes are described
below.
Type. Unlike dimensions and attributes, Resource objects may store only Number
data type.
No Empty Values. Check this option to disable writing register records with empty
dimension values.
Index. This  option may be specified only for dimensions. When you turn this prop-
erty on, it  speeds up operations with the register data, for example, when records by
a  specific dimension are selected. Such operations include queries with specified
dimension value, temporary calculations and methods of bypassing Accumula-
tionRegister object records in  the 1C:Enterprise script using dimension-based
filter.
Use in  totals. If this property is  not set, dimensions are excluded from the stored
register totals (this property is  only used for turnover register records). If a  dimen-
sion of this type is  used in  a query or condition of a  virtual table, the table does
not use the stored totals; instead, it  calculates data based on the record table only.

Ordering Accumulation Register Dimension List

The order of dimensions in  the accumulation register affects the access to register
totals. Place the dimensions that require fast access in  the beginning of the dimen-
sions list.
Chapter  6

COMMAND INTERFACE

Command Interface is  the main tool that grants users access to the application
functionality and ensures navigation between forms and various actions. A configu-
ration developer does not create detailed descriptions of global interface commands
or form command bars for every single user role available in  the application (or
for combinations of roles); instead, the developer describes the rules used by the
command interface to automatically create a  user-specific view.
The command interface representation depends on the user's rights (see page
1-180), functional options of the application (page 1-211) and, finally, user settings.
A declarative description of the command interface helps match the user-specific
commands and the user's rights to perform certain actions; it also ensures the
command interface of the application can be modified if some application function-
alities are not implemented.

6.1. GENERAL STRUCTURE OF COMMAND INTERFACE

6.1.1. Sections and Subsections of Main Application Window
All global commands in  the main application window are grouped into sections.
You can use the sections panel to navigate between them. The  set of these sections
is unambiguously defined by the set of top-level subsystems marked as Include
in  the command interface.
Commands of the current section are displayed in the navigation panel and the
actions panel of the main window.
When commands of a specific section are displayed in the navigation panel,
subsections can also appear; these are groups of commands corresponding to
a subordinate subsystem (also marked as Include in  the command interface).
For example, the Trade accounting partition could have Retail and Wholesale
subsections as it  owns identical subordinate subsystems.
1-338 1C:Enterprise 8.3. Developer Guide

6.1.2. Types of Commands

Commands in  the command interface could be grouped as follows:
„„ Independent global commands
„„ Parameterized global commands
„„ Local form commands
This section only deals with global commands (for a description of local form
commands see page 1-388). On the other hand, commands can be divided into the
following categories:
„„ Standard commands (automatically added into the command interface by the
system)
„„ Navigation commands
„„ Action commands
„„ Commands created in  the configuration

6.1.2.1. Standard Commands

Most configuration objects have system-provided standard commands that are
added to the command interface automatically. Below is  a list of these objects and
the corresponding standard commands provided by the system.
„„ Common form:
○○ Open common form
„„ Constants:
○○ Open constant editing form
„„ Catalogs:
○○ Open list form
○○ Open new item form
○○ Open new group form
○○ Generate
○○ Go to list filtered by owner
„„ Documents:
○○ Open list form
○○ Open new item form
○○ Generate
„„ Document journals:
○○ Open list form
„„ Reports:
○○ Open main form
„„ Data processors:
○○ Open main form
Chapter 6. Command Interface 1-339

„„ Chart of characteristic types:

○○ Open list form
○○ Open new item form
○○ Open new group form
○○ Generate
„„ Charts of accounts:
○○ Open list form
○○ Open new item form
○○ Generate
„„ Charts of calculation types:
○○ Open list form
○○ Open new item form
○○ Generate
„„ Enumerations:
○○ Open list form
„„ Information registers:
○○ Open list form
○○ Open new item form
○○ Go to list filtered by recorder
„„ Accumulation registers:
○○ Open list form
○○ Go to list filtered by recorder
„„ Accounting registers:
○○ Open list form
○○ Go to list filtered by recorder
„„ Calculation registers:
○○ Open list form
○○ Go to list filtered by recorder
„„ Business processes:
○○ Open list form
○○ Open new item form
○○ Generate
„„ Tasks:
○○ Open list form
○○ Open new item form
○○ Generate
„„ Exchange plans:
○○ Open list form
1-340 1C:Enterprise 8.3. Developer Guide

○○ Open new item form

○○ Generate
„„ Filter criteria:
○○ Open list form
Generation and Placement of Standard Commands
Standard commands that open a  list form and create a  new item are always added
to the interface if the Include in  the command interface property is  enabled.
A standard report command is  created if the default data composition schema or
the default or auxiliary form is  specified for the report.
A standard data processor command is created if the default or auxiliary form
is  specified for the data processor.
Standard generation commands are created by the system if you set the Base On
property appropriately. For example, if Goods and Product Lots catalogs can be
used as a basis to create Receipt and Invoice documents, the standard Generate
command will be available for these catalogs.
Standard commands that open a list form filtered by owner are created if the
Owners catalog property is  set appropriately and the information register has one
or more dimensions marked as Master.
A standard command that opens a list form filtered by recorder is created for
registers subordinate to a  recorder.
The following placement is  applied to standard commands:
Panel Commands to be placed
Navigation panel Commands that open lists
Actions panel Command that opens constant editing forms
Commands that open new item forms
Commands that open report and data processor forms
Form navigation panel Commands that open filtered list forms
Form command bar "Generate" commands

Parameterized Standard Commands

Some standard commands are parameterized, i.e. they can be executed in  a form
and receive a  value as a  parameter.
Command Parameter Type
Generate Basis object reference
Opening a  list filtered by owner Owner object reference
Opening a  list filtered by recorder Reference to recorder document
Opening a  filter criteria list Reference to filter criterion value
Chapter 6. Command Interface 1-341

For a description of how to create a parameter type for standard parameterized

commands see page 1-345.
Thus, if Goods and Product Lots catalogs can be used as a  basis to create Receipt
document, the parameter type for a  Generate command will be composite: Cata-
logRef.Goods and CatalogRef.ProductLots. Therefore, the Receipt:generate
standard command will be automatically added to the item forms of Goods and
Product Lots catalogs.

6.1.2.2. Independent and Parameterized Global Commands

Use independent global commands to select a  functionality throughout the entire
application. You do not need additional information (parameters) to run this type of
commands. The  following commands are independent:
„„ Opening a  catalog list
„„ Opening a  document journal
„„ Opening a  report form
„„ Opening a  new catalog item form, etc.
Parameterized global commands are context-dependent; you cannot run them
without additional information (parameters of command execution). The  following
commands are parameterized:
„„ Opening a  subordinate catalog list (use a  reference to an owner catalog item as
a parameter)
„„ Opening a  list of entries for a  register subordinate to a  recorder (use a  refer-
ence to a  recorder document as a  parameter)
„„ Input of an object based on another object (use a  basis object as a  parameter)
Parameterized commands can be displayed in  the navigation panel of an auxiliary
window or directly in  the form's command bar.
Global commands are displayed in the form's command bar before the Help
command. Please note that the Important command group is displayed in the
command bar while other command groups (the standard Generate group and other
groups in  the form Command bar category) are displayed as submenus. Execution
of global commands from the form's command bar opens a  new auxiliary applica-
tion window.

6.1.2.3. Navigation and Action Commands

Commands that allow a user to go to another application form without leaving
the current (default or auxiliary) application window are referred to as navigation
commands. They open a  new form in  the same application window where a  user
is  currently working.
Navigation commands can include both independent commands of the global
command interface and parameterized global commands. Navigation commands
can be found in  the navigation panel of the main or auxiliary application window.
1-342 1C:Enterprise 8.3. Developer Guide

Navigation commands of the main application window include Go to Catalog List

or Document Journal commands. For example, the Currencies command opens
a  currencies list form in  the same window and the Financial documents command
opens a  documents list form.
Navigation commands of an auxiliary application window include commands
used to go to lists that are logically subordinate to the object edited in  the current
window. For example, an editing form for a  currencies catalog item can contain
a  command used to go to an information register with an exchange rate history,
while a  document form can contain a  command used to go to records in  a specific
register, etc.
NOTE
Cancelling the Open Form command does not interrupt the navigation command
execution. However, it  does open an empty form.
Commands that generally open a  new auxiliary application window are referred to
as action commands. These commands temporarily change the task performed by
a  user, thus modifying considerably the context of his/her activities. For example,
a  Create New Document command makes a  switch from the application naviga-
tion task in  the main application window to the new document entry task.
These commands are added to the actions panel of the main application window or
to the form command bar displayed in  the auxiliary application window.

6.1.2.4. Commands Created in  Configuration

In addition to standard commands, a configuration developer can create custom
commands, determine their location (a command group), describe the corre-
sponding actions in  the 1C:Enterprise script, etc.
For details on properties of the Command object see page 1-230 and page 1-266.

6.1.3. Command Groups

All global commands are divided into four categories by their location and nature:
Category Description
Navigation panel Independent navigation commands
Form navigation panel Parameterized navigation commands called from a  form
Actions panel Commands that open a  new auxiliary application window
Form command bar Parameterized form commands that open a  new auxiliary application window

The above list of categories is a list of application interface areas where global
commands can be displayed.
The system provides standard command groups for global commands grouping.
Chapter 6. Command Interface 1-343

Location Standard command groups

Navigation panel ■■ Important
■■ Normal
■■ See also
Actions panel ■■ Create
■■ Reports
■■ Tools
Form navigation panel ■■ Important
■■ Go to
■■ See also
Form command bar ■■ Important
■■ Generate

Besides, at the configuration development stage the developer can create custom
command groups (Common  – Command groups configuration object, see page
1-230) that can be categorized into one of the categories listed above (Category
property of a  command group). These groups, along with predefined groups, can
be used for displaying the developed custom commands.

6.2. CREATION OF GLOBAL COMMAND INTERFACE

This section describes configuration objects and their properties that affect creation
of the configuration's global command interface.

6.2.1. Subsystems
The global command interface of the main application window is based on the
configuration's structure of subsystems. Subsystems are used as a basis of the
application functionality representation for users. The structure of subsystems
describes the overall system functionality. Since the global command interface of
the main application window depends on the structure of subsystems, the devel-
oper should exercise extra care when developing the configuration subsystems.
The  structure of subsystems is, in  fact, the first thing a  user will see when opening
the application.

Fig. 140.  Mapping Subsystems to Sections

1-344 1C:Enterprise 8.3. Developer Guide

The structure of the command interface is  affected by the subsystems marked as
Include in  the command interface. However, this property is  set for the subsystems
by default; therefore, it  is  assumed that the subsystems are primarily created to
describe the global command interface.
NOTE
If the configuration has no subsystems marked as Include in  the command interface,
the sections panel is  not displayed on the desktop in  the main application win-
dow.
Top-level subsystems create application sections, i.e. sets of global commands in  a
particular area. Sections are displayed in  the sections panel of the main application
window. Selecting a  specific section modifies the commands in  the navigation and
actions panels.
Subsystems of lower levels create subsections in  the navigation panel; these are
used to consolidate commands of a  particular subsystem.
If an object belongs to a  particular set of subsystems, its commands are displayed
in  the corresponding areas of the configuration's command interface. However, by
default new objects do not belong to any subsystem. It  means their commands are
not included in  the command interface. Therefore, to add the object's standard and
custom commands to the right areas of the command interface, you need to specify
the subsystems owning the object.
An object can belong to multiple subsystems with no regard to their interdepend-
ency, i.e. it can belong to both a parent and a subordinate subsystem or to
a  subordinate subsystem only if it  is  more convenient for the purpose of creating
the command interface.
NOTE
If the configuration has no subsystems marked as Include in  the command interface,
the desktop displays all commands that could be added there manually. In  this
case the command interface editor has a  different appearance: it  does not display
a  tree of commands and cannot remove commands from the desktop.
As soon as the first subsystem is  included in  the command interface, automatic
placement of commands on the desktop is disabled and commands should be
added to the desktop explicitly.
NOTE
The mode of automatic command placement on the desktop is  disabled if the
configuration run mode is  Ordinary application.

6.2.2. Commands
As mentioned above, the system includes both standard commands and commands
a  developer creates in  the configuration.
You can create a  Command configuration object as subordinate to the following
configuration objects:
„„ catalogs
Chapter 6. Command Interface 1-345

„„ documents
„„ document journal
„„ reports
„„ data processors
„„ charts of characteristic types
„„ enumerations
„„ charts of accounts
„„ charts of calculation types
„„ information registers
„„ accumulation registers
„„ accounting registers
„„ calculation registers
„„ business processes
„„ tasks
„„ exchange plans
„„ filter criteria
Additionally you can create common commands (Common – Common сommands
branch in  the configuration tree; see page 1-230).

6.2.3. Command Parameterization

If a command can be parameterized, it is executed by receiving a value as
a  parameter. Values can only originate from form data.
IMPORTANT!
Setting a  value type for a  command parameter only makes sense if the corre-
sponding command is  placed in  a form (is in  the form Command bar or form
Navigation panel categories).

The Command parameter type property defines a  list of forms where this command
can be executed. For example, if the command's parameter type is Cata-
logRef.Goods, it  can be executed in  the following forms:
„„ Form of Goods catalog item, where a  reference to the edited object is  used as
a parameter;
„„ Form of Goods catalog list, where a  reference from the current list row is  used
as a  parameter;
„„ Form of a  receipt, where a  reference to a  product from the current row of the
document's tabular section is  used as a  parameter, etc.
The number of values passed as parameter values to the command is  defined by
the Parameter usage mode property. If this property is  set to Single, the command
only receives a  single value of the selected type.
1-346 1C:Enterprise 8.3. Developer Guide

If the property is  set to Multiple, an array of values is  always passed as a  param-
eter (even if a single value is selected). This mode makes sense when data for
the command can originate from a  table in  the multiple selection mode. In  this
case the array's first item is  the current row (regardless of the selection order of the
table box rows). Thus, if a  list of goods includes Mixer, Vacuum cleaner, Refrig-
erator, Kettle and Mixer, Refrigerator and Kettle are selected while the current row
is  Refrigerator, the command receives an array with the following items (the order
of items is  preserved): Refrigerator, Mixer, Kettle. The  order of items after the first
item is  undefined, even though they are ordered in  the example above.
NOTE
If the current row is  not a  part of the selection, the first array item cannot be
identified unambiguously.
Areas of the forms' command interface are automatically created based on the
type of the main attribute. When a form is edited, a form developer can add
areas to the command interface. For example, if a  form is  used to edit goods, all
commands with the CatalogRef.Goods parameter type are automatically included
in  it (e.g., Print product card, Go to product price list, etc.). If a  product has the
Manufacturer attribute, commands with the CatalogRef.Contractor parameter
type can also be added to the form at the development stage (e.g., Contractor card,
Contractor agreements, etc.), as the form allows users to obtain values for param-
eters of these commands. Although these commands (that do not belong to the main
attribute) are not automatically included in  the command interface, the developer
can add them to the interface through the form editor.
Although a  group of parameterized global commands is  not automatically added
to the command interface for a  catalog group (Folder and item hierarchy hierarchy
type) or a  hierarchical chart of characteristic types, the developer can include these
commands in  the interface through the form editor.

6.2.4. Creation of Default Command Interface

Command placement is  defined by the Command parameter type and Group prop-
erties and by the membership of the command (or its parent object) in  a particular
subsystem.
Independent (non-parameterized) commands are added to the global command
interface areas corresponding to the subsystems that own the command (in case of
common commands) or its owner object.
Parameterized commands are added to the global command interface areas corre-
sponding to the objects with types included in  the command's Type parameter.
In both cases a  group of commands is  a more accurate location of the command
within an area. For example, command groups define a panel (navigation or
actions panel) to include independent commands of a  particular partition. In  case
Chapter 6. Command Interface 1-347

of parameterized commands, a command group defines whether the command

is  placed in  the form's navigation panel or command bar.
Therefore, independent commands (i.e. commands that do not require parameters,
such as opening a  list or a  new object form) are rarely placed by default in  cate-
gories different from the navigation or actions panel. On the other hand, placing
parameterized commands in the navigation or actions panel makes no sense, as
these commands cannot receive the required parameters in the main application
window. Review the following table of command placement.
Independent commands Parameterized commands
Navigation commands Navigation panel Form navigation panel
Actions commands Actions panel Form command bar

Please keep in mind that by default global commands are not included in the
command interface for forms of hierarchical catalog groups and chart of character-
istic types groups. To make a  global command available in  the command interface
of this form, you need to place it  there manually, through the form editor.
When you create a  command interface, use text representations of configuration
objects and commands. By default, the system generates representations based on
the Synonym and Name properties. However, you can modify these representations.
To do this, use object and list representations. For details see page 1-250.

6.2.5. Command Interface Property

Use the following properties to edit sets of global commands in  the appropriate
sections or sets of main section commands: Command interface (for subsystems),
Command interface (for the configuration) and Main section command interface
(for the configuration). You can edit these properties if you are dissatisfied with
the auto-generated order of commands, groups of commands within sections and
auto-defined default visibility.
Different sections can display the same command in  different areas of the naviga-
tion or actions panel with varying visibility. For example, a  command that opens
a  Goods catalog list in  the Trade section is  important and frequently used; there-
fore, a developer can add it to the Important group. In the Accounting section,
however, it  is  not as important and the developer can categorize it  as See also.
For details on the editor of command interface areas see page 2-967 and page 2-968.

6.2.6. Editing Sets of Commands

In addition to editing the subsystem's Command interface property in  the property
editor, you can also edit commands of all sections in  the All Subsystems editor (see
page 2-971).
Use the Command interface tab of the form editor to edit global commands
displayed in  the form (see page 2-937).
1-348 1C:Enterprise 8.3. Developer Guide

6.2.7. Role-Based Setup of Default Command Visibility

The following default visibility is used, when section commands and form
commands are created automatically.
Visible by default:
„„ commands that open lists of catalogs, documents, document journals, charts of
characteristic types, charts of calculation types, charts of accounts, independent
information registers, business processes, tasks and exchange plans;
„„ commands that open report and data processor forms;
„„ command that opens constant editing forms;
„„ commands that navigate to subordinate catalog lists;
„„ commands that navigate to lists of logically subordinate registers (i.e. registers
with master dimensions);
„„ commands that generate objects based on other objects;
„„ custom commands created by the developer at the configuration stage.
Invisible by default:
„„ commands that open lists of enumerations, information registers subordinate to
a  recorder, accumulation registers, accounting registers, calculation registers;
„„ commands that open new object and new group forms;
„„ commands that navigate to subordinate register lists;
„„ commands that navigate to filter criteria lists.
These visibility values auto-generated by the system can be modified for both
parameterized and independent commands. Default visibility values can be
based on roles used in  the configuration. When commands are displayed in  the
1C:Enterprise mode, a  command is  visible by default if at least one user roles has
visibility set for this command.
When editing role-based visibility, please note that command visibility for
a particular role is only enabled when the command is available for the role.
Therefore, if you set up visibility for a  role with a  very limited set of rights, you
almost never have to hide commands by clearing their default visibility check boxes
(the total number of available commands in  a section is  limited in  all cases).
Role-based editing of default visibility serves as a  tool of initial setup of the global
command interface content, primarily for users with a broad range of access
rights.
Chapter 6. Command Interface 1-349

6.3. SERVICE NAVIGATION FEATURES

6.3.1. Links
In 1C:Enterprise you can obtain a  text link to any command interface section, report,
data processor or infobase object (documents, catalog item, etc.).

Fig. 141.  Commands That Retrieve and Click Links

You can save the obtained link and use it  subsequently to go to the required object.
Since these links are text-based, you can send them to other users, e.g. by e-mail.
For a  description of link formats see page 2-1187. You cannot get links to tools
included in  standard functions.
You are allowed to launch the web client and follow a link concurrently.
It  requires an external link from the web or thin client connected to the infobase
through a  Web server.

Fig. 142.  Retrieval of External Link

To obtain an external link, use the standard link retrieval command, ensuring,
however, than the External button is  selected in  the link retrieval window (see fig.
142). The  resulting link can be inserted into the browser address bar to load the
application and follow the link (the example on fig. 142 opens the Sales Order list
form).
NOTE
When Microsoft Internet Explorer is  used, the application will not be launched
with simultaneous navigation to a  link if the link is  related to the application
already loaded in  the current browser window. It  is  recommended to enter the
link in  the address bar of a  new empty Web browser window.
1-350 1C:Enterprise 8.3. Developer Guide

6.3.2. User Notifications

Notifications are used to inform users of system actions. Notifications can be gener-
ated by the system or created by an application developer. The  system generates
notifications whenever an object is  written or modified interactively; the developer
can create notifications using the ShowUserNotification() method.
A notification is  displayed in  the window which is  by default placed in  the right
lower corner of the screen working area. If the notification has an associated link,
the explanation is also a hyperlink that opens the object indicated in the link.
The  explanation is  also represented as a  hyperlink if the notification is  auto-gen-
erated by the system (when an object is  written or modified interactively).

Fig. 143.  User Notification

If a  method call has no Explanation parameter, the URL becomes unavailable. For
the user to be able to follow the hyperlink, both NavigationLink and Explanation
parameters should be specified.
The notification window fades automatically after some time. However, if you
move the mouse cursor over this window, it  is  displayed until you close it  delib-
erately or move the cursor away from the notification window area.
If the notification display method is  called multiple times, the user only see the last
notification.
NOTE
The notification window is  shown on top of all the windows of the current
application apart from modal windows. Modal windows are displayed on top of
a  notification window.
When displayed in the favorites and history panel, the list of notifications
is aligned to the right side of the panel. The latest notification is displayed to
the right of the panel. If there are more than five notifications, only the last five
messages are displayed.
NOTE
The list of notifications is  only displayed during the session lifetime.
Notification windows displayed in  the web client are docked to the currently active
window.
Chapter 6. Command Interface 1-351

Fig. 144.  User notification in  web-client

When you close the window where the notification window appears, the latter is  then
displayed in  the parent window, etc. until it  reaches the main application window.
NOTE
You cannot move or re-size the notification window in  the web client.

6.3.3. Display Status of Lengthy Processes

As you develop a  configuration, you sometimes need to inform the system user of
the status of lengthy processes (e.g., payroll calculation for a  department). Use the
status bar to do so.
To display the status bar, call the State() method; however, you cannot call it  on
the server side. If you need to display the status of a  lengthy process at the client
while the process runs on the server, you must implement this process to run by
short chunks initiated by the client. In  this case as soon as a  new chunk runs on the
server, you can display the status change of the process. A status panel is  displayed
in  the window located by default in  the right lower corner of the screen work area.

Fig. 145.  Status Window

If you want to display the progress of the process in  a progress bar (e.g., if you
know the total number of employees in the calculation and want to show how
many have been processed), use the same State() method and specify the third
1-352 1C:Enterprise 8.3. Developer Guide

parameter that defines an absolute value of the progress bar. The  minimum value
of the progress bar is  always 0 and its maximum value is  100.

State("Processing data",
Counter*10,
"Processing chunk: " + Counter,
PictureLib.SubsystemTradeInventory);

If the third parameter is not specified for the method, the progress bar is not
displayed in  the status bar. In  this case the explanation text is  placed below the
text of the main description:
State("Posting for" +
Format(PostingDate, "DLF=DD"),
,
"Posted" + PostedCount,
PictureLib.Post);

Fig. 146.  Status Without Progress

The status bar automatically hides some time after a program fragment that
displays the bar stops running. However, if you move the mouse cursor over this
window, it  is  displayed until you close it  deliberately or move the cursor away
from the status bar area.
NOTE
The status bar is  shown on top of all windows of the current application apart
from modal windows. Modal windows are displayed on top of the status bar.
In the web client a  status bar is  displayed as a  separate Web browser window.
This  window is  updated in  the following ways:
„„ Microsoft Internet Explorer. The status is updated every time you call the
State() method.
„„ Mozilla Firefox. The  state is  updated upon each call to the server and after the
program code in  the 1C:Enterprise script is  executed. Therefore, if no server
methods are called during execution of the program code in  the 1C:Enterprise
script, the status bar is  not updated.
„„ Google Chrome and Safari. Status is  updated only when built-in code execution
is finished.
Chapter 6. Command Interface 1-353

6.3.4. Messages
Most messages in  an application are logically related to data. For example, if you
post a  document while certain items are missing at the warehouse, the programmer
has to notify the user of this event.
Messages allow the developer to create notifications that specify object attributes
causing the error. When displayed in a client application, a message can be
automatically docked to a form element used to edit the attribute; in this case
it  is  displayed next to the control.
Messages are displayed on the message panel in  the lower part of the work area.
The height of the message panel does not exceed 5 lines. If the panel contains
multiple messages, a  scroll bar appears, but the panel does not increase in  height.
Nor can the height be changed manually.
This mechanism is  based on the UserMessage object of the platform.

Fig. 147.  Messages

Messages are used to notify a user that the requested action has failed (e.g.,
a  document cannot be posted because the inventory balance is  not available).
1-354 1C:Enterprise 8.3. Developer Guide

If a  message is  linked to a  tabular section field, changing the tabular section row
order will not affect message visualization.

Fig. 148.  Messages in  the tabular section

If the row linked to the message is  deleted, the message will be linked to a  form
element (see page 1-402) displaying the tabular section.
In case the message is  linked to a  table row linked to the FormDataCollectio,
FormDataTree or FormDataStructureAndCollection type form attribute, the
interactive search is  performed by user (using a  corresponding standard command)
with the result of hiding the string, for which the message was created, then the
search operation will be automatically aborted and the message will be shown as
required. If a  program filtering is  set for the table (the RowFilter property), this
filter will not be cancelled when the message is  shown and the message is  posi-
tioned for the whole table.
Chapter 6. Command Interface 1-355

NOTE
You are recommended to display messages to notify a  user the requested action
cannot be completed, rather than to inform him/her of the actions in  progress.
In  the latter case you can use the ShowUserNotification() method instead.
If you want to associate an error message with the correct form element, the system
needs to know the following: the attribute, the owner infobase object and the form
element used to display the attribute. Filling in  the properties listed above helps
you answer all of the questions:
„„ Set the DataPath property to specify the form attribute that stores the infobase
object data.
„„ Set the Field property to specify the object's attribute for which the message
will be displayed. Thus we can say that the message will indicate DataPath.
Field data that are identified with the DataKey value. This  allows the system
to define the form element that displays the required information based on the
form structure data. Later, this form element is  used to display the message.
„„ The Field property can contain a description of the data in the following
format:
○○ For attributes, the AttributeName type string, for example, Vendor, Vendor.
Parent.
○○ For tabular section attributes, TabularSectionName[RowIndex].Attribute-
Name; e.g., Nomenclature[10].Count.
○○ For recordset rows, [RowIndex].AttributeName; e.g., [10].Currency.
„„ The AssignmentID property specifies which form a  message is  linked to. For
example, if a  message is  generated in  a form shown on the desktop, setting
the AssignmentID property will show a  message linked to the form where the
messaged was generated.
If the DataKey property is  filled in  the message and does not match the key value of
the current form main attribute (object reference or information register record key):
„„ A new object form, corresponding to the DataKey value, opens;
„„ If the DataPath property is not set in the message, it is filled in with the
main attribute name of the open object form;
„„ The message is  displayed in  the new form.
Additionally all messages where the DataKey value matches the value of this
property in  the current message are moved from the current form to the new form.
In  this case the DataPath property is  also filled in  these messages if not set.
To fill in  a data path, the system uses a  special mechanism that saves informa-
tion about form elements matching objects and then uses it  when the SetData()
method is  called. Therefore, before object module procedures that create messages
can be executed, form attributes should be mapped to objects, while the developer
needs to call the SetData() method within the module.
1-356 1C:Enterprise 8.3. Developer Guide

When you perform standard actions with an object in  a form, e.g., when you post
a document, the form extension creates and maps the object. In this case the
developer does not have to take any actions.
NOTE
If user messages were generated in  a transaction when a  new object was written
(exchange plan, catalog, document, account chart element, characteristic types
object element, calculation types list element, business process, job), when the
transaction is  cancelled in  messages, references to the object are cleared (the
DataKey property).

The following section describes how you can do the mapping if the object
is  created programmatically based on form data.
You can map an object to a  form explicitly, using a  method or implicitly.
If you want to use explicit mapping, call the SetObjectAndFormAttributeCon-
formity() method. Information about the form where the object is  displayed (the
FormID property) and which attribute stores the data object (the Attribute prop-
erty) is  passed as a  second parameter to the method to set the required mapping of
messages and form elements:
Parameters = New Structure;
Parameters.Insert("FormID", UUID);
Parameters.Insert("Attribute", "Object");
SetObjectAndFormConformity(Object, Parameters);

The mapping will exist for as long as the object for which it  is  set exists.
This method maps form attributes to data objects which ensures messages are
correctly mapped to the form elements. For a  message to use data on mappings
between an object and an attribute name, link the message to the data using the
SetData() method of the UserMessage object.

ObjectCatalog = CatalogRef.GetObject();
Parameters = New Structure;
Parameters.Insert("FormID", FormID);
Parameters.Insert("Attribute", "Object");
SetObjectAndFormConformity(ObjectCatalog, Parameters);
ObjectCatalog.FillCheck();

Please note that the SetObjectAndFormAttributeConformity() method must

specify an attribute name for the form that will open by default and display an
item of the catalog in  use (ObjectCatalog in  the example above). In  this case
messages generated in  the fill check handler (ObjectCatalog.FillCheck()) will
be correctly linked to the attributes of the new form. If the FormID property of
the Parameters structure (see the example above) contains a unique identifier
that does not match any form instance, a  new form will be created and opened to
display the message.
Chapter 6. Command Interface 1-357

You can retrieve a mapping using the GetObjectAndFormAttributeCon-

formity() method. You can only obtain the mapping until the object for which
it is set exists.
AttributeName = GetObjectAndFormAttributeConformity(Object);

If a  passed object has an attribute mapping, the attribute name is  returned by the
function. Additionally the mapping can be set by the form using the FormAttrib-
uteToValue() method. In  most cases you are recommended to use this method.
// Code in  document module.
&AtServer
Procedure Posting()
...
Message = New UserMessage();
Message.Text = "Row 10 of tabular section " + "Nomenclature lacks " + MissingNumber + " " + NomenclatureUOM;
Message.Field = "Nomenclature[10].Count";
Message.SetData(ThisObject);
Message.Message();

// The  message is  displayed in  the form and docked to

// the control associated with the
// Count field in  row 10 of the tabular section named
// Nomenclature.
...
EndProcedure;

If a user message is created (using the UserMessage object) in the course of

a  context or out-of-context server call from a  form, common module or common
command module, the message is not displayed. The generated messages are
displayed to the user after control is  transferred back to the client. To obtain a  list
of messages that have not been displayed, use the GetUserMessages() method.

6.3.5. How Keyboard Shortcuts Work

The following keyboard shortcuts are valid in  an independent auxiliary window:
„„ Navigation panel commands of the main window
„„ Actions panel commands of the main window
„„ Commands of the auxiliary window (both form commands and navigation panel
commands)
Please note that keyboard shortcuts for the main window commands work, even
if the command invoked by the shortcut is  not visible, e.g., hidden by the user.
Keyboard shortcuts for hidden navigation panel commands and hidden form
elements do not work in  auxiliary windows.
Blocking windows support internal keyboard shortcuts only; they do not support
shortcuts for the main window commands.
1-358 1C:Enterprise 8.3. Developer Guide

6.4. COMMAND INTERFACE DEVELOPMENT PROCEDURE

Development of a  command interface usually involves the following sequence of
actions:
„„ As you start to develop a configuration, you determine its structure within
a  specific subject area, i.e. create a  tree of configuration subsystems;
„„ You create a  set of roles, i.e. define who will use the configuration;
„„ Newly created configuration objects (catalogs, documents, etc.) are generally
attributed to specific subsystems and assigned role-based access rights;
„„ If the standard location and default visibility of commands does not meet your
requirements, you can edit the Command interface property of the relevant
subsystems and modify sets of commands in  the forms where parameterized
commands of the required objects (navigation to a  subordinate list and input on
basis) are automatically placed.
These minimal actions will display commands that open object list forms or can be
used to input new objects in  the relevant sections of the command interface (if the
commands are visible in  the editor of the command interface section). Addition-
ally if indicated in  the object's properties, commands for input on basis, navigation
to a  list filtered by recorder or owner and others will be added to forms of other
configuration objects.
Review an example of creating a  Shipment document. To create it, you need to do
the following:
„„ Indicate that the document belongs to Sales and Warehouse subsystems;
„„ Grant rights to work with the document to Sales manager and Administrator
roles;
„„ Specify the document is  based on Sales and Sales Order documents;
„„ Indicate it  is  a recorder for the Inventory register.
As a  result, a  Shipment command will appear in  the navigation panel of the Sales
section if a  user is  assigned the Sales manager role or has administrative permis-
sions.
Moreover, forms of Sales and Sales Order documents will display a  Generate
submenu command that can be used to enter an invoice. Therefore, you do not need
to edit interfaces for users with the specified roles or forms of Sales and Sales
Order documents.
A standard presentation of the command that opens the list of goods issue docu-
ments (Shipment) might look ambiguous. You can override it  by setting the List
presentation property of the Shipment document to Shipments.
Please note that by default the command is  added to the middle of the command
list in  the Sales section. Assume the command is  important for the section. Go to
the All Subsystems editor (or the command interface editor of the Sales subsystem)
Chapter 6. Command Interface 1-359

and move the command to the Important group. The  Warehouse section is left
unchanged, with the command at its default location.
Finally, review the default command visibility. The  form of the Shipment docu-
ment now contains a command used to navigate to a list of Inventory register
records; however, by default the command is hidden. Assume this command
is  important to the system administrator and is  irrelevant by default to a  manager.
To implement this, create a form of the Shipment document, start editing the
command interface and make the command used to navigate to the register list
visible for the Administrator role; do not change the settings for the manager role.
Since the system administrator is granted broad access rights, the number of
commands is  very big. Assume he/she will rarely use the command to go to a  list
of invoices. To lighten the command interface, start editing the commands in  the
All Subsystems editor and make the relevant command invisible for the Adminis-
trator role.
You can also display a  command that adds a  Shipment document in  the actions
panel for a sales manager, so that he/she could enter this document without
opening the document list.
The user can also customize command visibility while working with the configura-
tion.
1-360 1C:Enterprise 8.3. Developer Guide
Chapter  7

FORMS

Forms are objects created for entering and viewing information and for managing
various processes. The  program uses forms to ask the user for information it  needs
to continue processing or to display information the user can view and edit.
The main purpose of a form is to provide the user with a convenient tool for
entering and viewing data. As in  paper documents, you can use forms to quickly
enter the necessary information and to store it  for later processing and when neces-
sary, to restore the previously entered data for viewing or editing.s
The visible part of a form (displayed to users) is a tree with form elements.
The  items can include text boxes, check boxes, radio buttons, buttons, etc. More-
over, an item can be a  group consisting of other items. A group can be represented
as a  panel with borders, a  panel with pages (tabs), a  page or a  command bar. An
item can also represent a  table containing other items (columns). A structure of
items describes how a  form looks like. All form functionalities are described by
attributes and commands. Attributes are data used in  a form, while commands are
actions it  performs. Therefore, a  developer has to include the relevant attributes
and commands in  the form through the form editor, create form elements to display
them and group these elements, if necessary.
TIP
We recommend designing forms with the resolution set to 96 DPI.
The system can auto-generate forms for application objects; however, the devel-
oper can create a  custom form and define its attributes, commands and displayed
items. This  logical description is  used by the system to auto-generate the form as
it is displayed to users. The system checks various properties of the displayed
data (e.g., types) in the process in order to arrange form elements in the most
user-friendly way. The  developer can change the location of items through various
settings. He/she can define the order of items, specify their width and height. This,
however, is  additional information that helps the system display the form.
1-362 1C:Enterprise 8.3. Developer Guide

Within forms the developer can use both form commands and global commands
used in  the command interface of the entire configuration. Moreover, he/she can
create parameterized commands that open other forms based on the specific data
from the current form. For example, one of these commands can open an inventory
balances report for the warehouse currently selected in  an invoice form.
Forms support linking messages displayed to the user to form data. It  means the
system can visually mark and activate the form elements that contain user-made
errors.
Forms also automatically account for role-based data availability. Thus, if an
attribute of a displayed object cannot be viewed by a specific user, the system
automatically removes the corresponding form element and rebuilds the form.
You can create forms in  the form editor that is  available in  the Designer mode
(see page 2-937). This  editor defines the following objects:
„„ Form attributes that store data used in  the form (see page 1-362).
„„ Form parameters that link forms to each other and manage a  form's function-
ality on opening (see page 1-384).
„„ Form commands that perform various factions within a  form (see page 1-388).
„„ Form module that stores program code associated with form operation (see
page 1-390).
„„ Form elements that display form attributes and make them editable and can be
used to display and execute commands (see page 1-391).
„„ Command interface that contains commands which can be executed in  a form
and are provided by the global command interface and form commands (see
page 1-421).
IMPORTANT!
Forms exist both on the server and at the client concurrently. You should always
keep it  in  mind as you develop forms.

7.1. FORM ATTRIBUTES

The set of form's attributes describes the data displayed, edited and stored in  the
form. Independently, the form attributes cannot ensure data display or editing.
To display and edit data, use form elements associated with the form attributes.
The  set of all the form attributes is  known as form data.
IMPORTANT!
Please keep in  mind that all the form data have to be described as attributes. You
cannot use form module variables as sources of data for the form elements.
When you develop a  form, you can expressly specify that certain form attributes
can be viewed and edited in  specific fields; to do this, use the View and Edit prop-
Chapter 7. Forms 1-363

erties (for details see page 2-942). You can also customize an attribute availability
in  the form using functional options (for details on functional options page 1-211).
You can assign the Main attribute to a  form, i.e. the attribute that defines the form's
standard functionality (the form's extension).
IMPORTANT!
Please keep in  mind a  form cannot have more than one main attribute.
Form extension describes additional properties, methods and parameters for
a  ManagedForm object form; they are determined by the type of the form's main
item.

7.1.1. Form Data Types

Forms use a  limited set of data types:
„„ Types that are directly used in  forms are the types at the thin and web client
(e.g., Number, CatalogRef.Goods, GraphicalSchema, SpreadsheetDocu-
ment).
„„ Types to be converted to special data types, i.e. form data types. These types
are displayed in  the list of form attributes and are enclosed in  parentheses, e.g.
(CatalogObject.Goods).
„„ Dynamic list is a special data type that manages how random information
from database tables is displayed in a form. You must specify the table to
be displayed or describe the resulting selection in  the query language for this
data type. This  feature is  based on the data composition system and allows to
apply sorting, filtering, searching, grouping and conditional appearance to the
retrieved data.
Certain application types (e.g. CatalogObject and others) do not exist at the thin
and web clients. Therefore, the platform uses special data types designed to work
in  forms in  order to represent the application types. This  explains why application
objects need to be converted to form data (and backwards).
The following data types are available:
„„ FormDataStructure: Contains a  set of properties with arbitrary types. Prop-
erties can represent other structures, collections or structures with collections.
An example of this type in  a form would be CatalogObject.
„„ FormDataColletion: Represents a list of typed values, similar to an array.
You can access a collection item using its index or ID. If collections are
retrieved based on register record sets or object tabular sections, the collection
item's LineNumber field does not match the real index of the item. In  certain
case you cannot access items by IDs. It  is  defined by the type of the applica-
tion object represented by the collection. An ID can be any integer. An example
of this type in  a form would be a  tabular section.
1-364 1C:Enterprise 8.3. Developer Guide

„„ FormDataStructureandCollection: Represents an object as a  structure and

collection at the same time. You can handle the object as any of these entities.
An example of this type in  a form would be a  record set.
„„ FormDataTree: This  object is  used to store hierarchical data.
IMPORTANT!
It is not recommended to use these forms as parameters for procedures and
functions transferring control from the client to the server and as function return
values, if control is  given to the client.

IMPORTANT!
When server procedures and functions are called and control is  given back to the
client, only changes in  form data are transferred. If the Arbitrary type is  selected
as the form attribute type and the mutable value is  selected as the attribute value,
you need to assign the mutable value to the form attribute after the mutable value
is  changed, so data can be correctly transferred between the client and the server.
An application object can be represented by a  single or multiple form data items.
Generally, the hierarchy and make-up of form data depends on the complexity and
interrelation of the form's application objects.
For example, a document that includes a tabular section is represented by the
FormDataStructure object (the document proper) with a  subordinate FormDa-
taCollection object (the document's tabular section).
IMPORTANT!
As you develop the configuration, please keep in  mind that application objects
are only available on the server, while form data objects can be used both on the
server and at the client.
When form attributes are created, the following limitations apply:
„„ You are not allowed to assign Array and Map values to form attributes.
„„ You are not allowed to assign Array and Map values to arbitrary-type attributes
of FormDataStructure, FormDataCollectionItem, FormDataTreeItem
and FormDataStructureAndCollection objects.
„„ You are not recommended to use Array and Map values as items of Structure
or ValueList collections.
„„ In the above cases you are recommended to use fixed collections: FixedArray,
FixedMap.
„„ You are not recommended to use Structure or ValueList types in form
attribute data (i.e. attributes of attributes).
Form data can be viewed as a standardized presentation of data from various
application objects that the form uses identically and that exist both on the server
and at the client. In  other words, the form contains a  view of application object
data represented as its data types and converts these types as necessary. However,
Chapter 7. Forms 1-365

if a  configuration developer implements a  custom data processing algorithm, data

conversion (between special and application types) must also be custom.
When form attributes are edited, the developer can influence data transfer between
the server and the client during the form's operation. This  is  ensured by the Use
always column of the attribute editor. The  property's behavior differs depending on
the type of attributes:
„„ If the attribute is  subordinate to a  dynamic list (a column of the dynamic list):
○○ the property is  on: the attribute is  always read from the database and added
to the form data;
○○ the property is  off: the attribute is  read from the database and added to the
form data only when a  form element that is  associated with the attribute or
its subordinate attribute is  currently visible.
„„ If the attribute is  subordinate to a  collection of register records:
○○ the property is  on: the document register records are read from the database
and added to the form data;
○○ the property is off: the document register records are not read from the
database and are not added to the form data (if no form element references
the records).
„„ Other form attributes:
○○ the property is  on: the attribute is  added to the form data regardless of the
fact whether any form element is  associated with the attribute or its subor-
dinate attribute;
○○ the property is  off: the attribute is  added to the form data only when a  form
element is  associated with the attribute or its subordinate attribute. Unlike the
case of dynamic list attributes, the associated item visibility is  irrelevant here.
NOTE 1
Please remember that setting a  property for a  parent attribute affects all of its
subordinate attributes. For example, if you disables the Use always property for
a  document's tabular section, the system assumes the property is  disabled for all
the subordinate attributes (regardless of the actual property statuses).
NOTE 2
Form attributes of the object type (CatalogObject, DocumentObject, etc.)
always have Ref, DeletionMark and IsFolder attributes in  the form data (if
the object has the corresponding attribute), regardless of the Use always property
status.
NOTE 3
It is  forbidden to assign other form data objects to form data attributes.
If the attribute editor (Type column) displays the type description in  parentheses,
e.g. (CatalogObject.Goods), it  means the application type is  going to be converted
to the form data types.
1-366 1C:Enterprise 8.3. Developer Guide

If the form data contain an invalid type (e.g., an attribute of the form attribute), the
form attribute editor displays the (Not available in  form data) label next to the type
name of this attribute. In  the 1C:Enterprise mode the form field corresponding to
this attribute is  not created. No error messages are displayed in  this case. You need
to explicitly implement the program code that supports copying and processing of
such attributes in  the form when you copy or edit objects containing such data.
Let us review form attributes of different types:
„„ Form attributes of ValueTable and ValueTree types allow you to add columns
(the Add attribute column command). It  defines the data structure of the created
collection.
„„ Attributes of FormDataCollection (e.g., objects' tabular sections) and
FormDataStructureAndCollection types (e.g., register record sets) allow
you to set additional attribute columns (the Add attribute column command) that
are not associated with the data stored in  the infobase.
The system generates these columns when it  creates the form data. You can call
these attributes both at the client and on the server.
Below is  an example of how you can fill in  an attribute column unrelated to data:

&AtServer
Procedure OnReadAtServer(CurrentObject)

For Each String In  Object.Goods Do

// ProductType is  an attribute unrelated to data

String.ProductType = String.Product.Type;
EndDo

EndProcedure

„„ Attributes of the ValueList type allows you to set the value type (the Value
type property) to be stored in the list. In this case the system automatically
limits the type of data to be added interactively. Programmatic addition is  also
allowed, but the system attempts to convert the value of the added type to the
limiting type (or the composite type). You can also associate the Value type
property with a  form element. It  enables you to limit the type of data that can
be added to the value list interactively.
„„ Attributes of the DynamicList type allow you to set list parameters: main table,
settings, etc. For details see page 1-369.
IMPORTANT!
Attribute columns that are not associated with data are excluded from data con-
versions between form data and infobase objects.
For a  description of the View and Edit properties see page 2-942.
Chapter 7. Forms 1-367

Form data changes are displayed by form elements after execution of the
1C:Enterprise script or a forced call of the RefreshDataRepresentation()
method. Consider the following example.
Assume a  form contains a  Counter attribute of the Number type. This  attribute
is displayed in the form as a field of the Progress bar type. Assume you have
an action you want to be tracked in  the progress bar. This  action is  triggered by
clicking a  button in  the form:
Procedure FormCommandHandler()

For Counter=1 to 100 Do

ExecuteAction();

EndDo

EndProcedure

If you click the button that initiates this command in  the 1C:Enterprise mode, the
progress bar indicator is  first in  its leftmost position and then it  moves directly
to the rightmost position (assuming the ExecuteAction() method has been
operating for some time allowing to see the change in  the progress bar). In  other
words, the progress bar is  only updated after the command handler completes its
work.
For the progress bar to display the real progress of the process, you have to replace
the handler code with the following:
Procedure FormCommandHandler()

For Counter=1 to 100 Do

ExecuteAction();
RefreshDataRepresentation();

EndDo

EndProcedure

After this modification the progress bar will change in the course of command
handler's code execution.
NOTE
In the web client, calling the RefreshDataRepresenation() method will
refresh form elements only when built-in code execution is  completed.
1-368 1C:Enterprise 8.3. Developer Guide

7.1.2. Conversions Between Application Object Data

and Form Data
You can use a  set of global methods to convert application objects to form data and
backwards:
„„ ValueToFormData()
„„ FormDataToValue()
„„ CopyFormData()
Methods that work with application objects are only available within server proce-
dures. The  method that copies values between form data is  available both on the
server and at the client since it  does not use application objects as parameters.
When you convert form data to an application object, you should know whether
they are compatible.
„„ ValueToFormData(): converts an application-type object to form data;
„„ FormDataToValue(): converts form data to an application-type object;
„„ CopyFormData(): copies form data with a  compatible structure. It  returns True
if data are copied successfully or False if object structures are incompatible.
Conversion of form data to application objects and backwards uses object caching;
at the same time the object version in  the cache is  checked for relevance.
NOTE
Conversion is  automatic for standard operations (opening a  form, executing the
standard Write command, etc.) in  a form with the main attribute.
Below is  an example of how you can use data conversion in  custom algorithms.
&AtServer
Procedure OnCreateAtServer(Cancel, StandardProcessing)

ObjectProduct = Goods.FindByDescription("Coffeepot").GetObject();
ValueToFormData(ObjectProduct, Object);

EndProcedure

&AtClient
Procedure Write()

WriteAtServer();

EndProcedure

&AtServer
Procedure WriteAtServer()

ObjectProduct = FormDataToValue(Object, Type("CatalogObject.Goods"));

ObjectProduct.Write();

EndProcedure
Chapter 7. Forms 1-369

The ManagedForm object also has methods available on the server:

„„ ValueToFormAttribute(): converts an application-type object to a  specified
form attribute.
„„ FormAttributeToValue(): converts a form data attribute to an application-
type object.
Using these methods is generally more convenient as they contain information
about the form attribute type. Moreover, the FormAttributeToValue() attribute
matches form data and the object which is  useful for message generation (see page
1-353).
Please keep in  mind that when you convert ValueTable or ValueTree objects to
form data (using the ValueToFormData() or ValueToFormAttribute() method),
the converted object must contain all columns existing in  the form data.
IMPORTANT!
Attributes columns that are not associated with data (see page 1-363) are excluded
from data conversions between form data and infobase objects. Columns that are
not included in  object data are cleared when they are converted to form data.
NOTE
Only the following form attribute types can be the first parameter of the FormAt-
tributeToValue() and FormDataToValue() methods: FormDataStructure,
FormDataCollection, FormDataStructureandCollection, FormDataTree.

Review an example of using these methods.

&AtServer
Procedure RecalcAtServer()

// Converts the Object attribute to an application object.

Document = FormAttributeToValue("Object");

// Uses the recalculation method defined in  the document module.

Document.Recalc();

// Converts the application object to the attribute.

ValueToFormAttribute(Document, "Object");
EndProcedure

7.1.3. Dynamic List

Dynamic list is  a special data type that displays random information from data-
base tables in  a form. You must specify the table to be displayed or describe the
resulting selection in  the query language for this data type.
This feature is  based on the data composition system and allows to apply sorting,
filtering, searching, grouping and conditional appearance to the retrieved data.
The  source of data is  a query that can be auto-generated by the system (based on
the specified data) or written manually by a  developer.
1-370 1C:Enterprise 8.3. Developer Guide

Fig. 149.  Options of Dynamic List Creation

When creating a  DynamicList form attribute the developer can generate the data
query using one of two methods:
„„ Setting the main table – in  this case it  is  sufficient to specify the table (the
Main table property) that has to be used as a  data source; in  this case the system
will auto-generate the data query (see the right part of fig. 149);
„„ Generating the query manually – by setting the Custom query property (see the
left part of fig. 149). After this you can manually format the query that retrieves
data from the infobase.
The query can retrieve data from multiple tables; therefore, you can indicate the
main table. It  is  required so the dynamic list knows which data are primary and
which are secondary, so it  can select and display information correctly and provide
standard commands. However, defining the main table in  the query is  optional;
in  this case the dynamic list will have no commands related to the main table.
If you select manual query formatting, the following limitations apply:
„„ The dynamic list does not support batch queries.
„„ The dynamic list does not support unions in  a query if the main table is  speci-
fied.
„„ The dynamic list does not support grouping, sorting and filtering by attributes
of tabular sections.
„„ The dynamic list may not contain ORDER BY sections if the main table is  speci-
fied. In this case you should use queries without the main table or set the
required ordering using the dynamic list settings.
Chapter 7. Forms 1-371

„„ You cannot use subquery fields that return multiple values in a query. Use
queries without the main table.
„„ The query may not contain groupings and aggregate functions if the main table
is  specified. In  this case you should use queries without the main table or set
the required groupings using the dynamic list settings.
„„ If the dynamic list is  displayed as a  hierarchical list or tree, the query may not
contain filters by its parent.
„„ If a dynamic list is shown as a hierarchical list or a tree, the query should
be generated in  such a  way that query results will contain elements and their
parents.
„„ The dynamic list does not support sorting if the query contain aggregate func-
tions.
„„ If the main table is  specified in  the dynamic list, the query may not include
TOP and DISTINCT instructions.
„„ If the arbitrary query is  specified, the query should not include the TOP instruc-
tion.
„„ Specifying a  dynamic list table used in  the query only in  an external connec-
tion as a  main table.
„„ It is  not recommended that you use table joins inside the FROM block of the
dynamic list query if such joins are specified using the extension of the data
composition system query language (in squiggle brackets). We recommend
overwriting the query so as to get rid of such joins.
Make sure that you consider the following when creating a  dynamic list:
„„ You cannot specify tabular sections of objects in  the main table of a  dynamic
list.
„„ You cannot use change registration tables (used in  data exchange mechanisms),
sequence tables and recalculation tables (used in  periodic calculation mecha-
nisms).
„„ If the query specified for the dynamic list does not ensure uniqueness of the
selected strings, the strings in  the list and scrolling will be incorrect. In  this
case you have to disable use of the main table.
In other words, a dynamic list with a specified main table will only work
correctly if the query specified as a  data source does not increase the number of
rows received from the main table (with applied filter).
„„ In this case you must disable use of the main table.
„„ When dynamic list properties are modified programmatically, any command
bars associated with the dynamic list are not updated automatically.
„„ The interactive list setup is  not available for a  dynamic list showing enumera-
tion lists.
If a  list form assumes filtering of linked data (for example, filter by owner in  a
subordinate catalog list), a dynamic list generation query should include a field
1-372 1C:Enterprise 8.3. Developer Guide

with a reference to the parent object. This field should have the name of the
corresponding standard attribute: Owner, Parent, BusinessProcess, etc. If this
requirement is  not fulfilled, the standard command for switching to any subordi-
nate list will work, but filtering will not be set. If for any reason it  is  impossible to
fulfill the requirement, you should not use standard commands and instead imple-
ment your own commands to open such lists.
If a dynamic list displays data sourced from a virtual table (the Main table
property, see page 1-441), for which the BeginOfPeriod and EndOfPeriod
parameters are set, these specified period borders are inserted directly into the
parameters of a  virtual table when a  user sets the display period using the Set date
range command).
You can use an array or a  list of values as a  parameter of the dynamic list. But if
a  list of values is  a parameter, only the first list value will be used as a  filter value.
If a dynamic list uses a query with parameters, initial setting of the parameter
values should be done in  the OnCreateAtServer handler.
If the dynamic list is  the main form attribute, you can set filter values for it  using
the form's Filter parameter (for details on form parameters see page 1-384).
In  this case the structure's property name stored in  the Filter parameter should
march the filter field name in  the dynamic list. If these names match, the value of
the structure property is  set as the right value of the filter item. If an array, a  fixed
array or a  value list is  passed as the value for the Filter parameter item of the
dynamic list form, a  condition with the In  list option is  added to the filter; the right
value of the condition is  placed in  the value list (which results from conversion of
an array or a  fixed array).
A query using a  parameter to generate any field value can be used as a  custom
query in  a dynamic list, for example:
SELECT
CASE
WHEN Delivery.Rate = 1
THEN &Presentation
ELSE Delivery. Rate
END AS Rate
FROM
Document.ProductDelivery AS Delivery

If the parameter value type is different from the object attribute type, (e.g.,
Attribute1 has the Number type and parameter value has the String type), you
should explicitly cast the parameter value to the required type to correctly display
the field:
SELECT
CASE
WHEN Delivery.Rate = 1
THEN CAST(&Presentation AS String(100))
Chapter 7. Forms 1-373

ELSE Delivery. Rate

END AS Rate
FROM
Document.ProductDelivery AS Delivery

If the field used in  the filter is  disabled with the help of functional options, the
filter is  not set, even if the filter value is  passed as a  form parameter or a  selec-
tion parameter link.
The Read data dynamically property specifies if data for the dynamic list have to
be read by small chunks. Regardless of this setting, the following conditions apply:
„„ If you set the hierarchical list view, the system reads data from the current
folder only.
„„ If you set the tree view, the system reads data from the open tree nodes only.
„„ Simultaneously loading a  dynamic list data is  not supported if the hierarchical
view is  set (the Display property is  set to Tree or Hierarchical list) and initial
tree representation set to Expand all levels. To obtain the data, the server will be
queried for the number of times that there are nodes in  the list displayed.
To get displayed data dynamic lists use one of these three methods:
1. Data are read from a  database by chunks where the data item count is  equal
to the number of rows shown by the list simultaneously. Server-side caching
is  not used.
2. Data are read from the database in 1000-data-item chunks. Server-side caching
is  used.
3. Data are read from the database in  chunks. The  first chunk contains 1000
items. Each subsequent chunk is  increased by 1000 items (when the previous
selection reaches its end). The  closer the "view point" moves to the end of the
displayed data sequence, the bigger the selection that is  read from the database
is; eventually, it  becomes as large as the size of the data displayed. Server-side
caching is  used.
Different data reading methods are used based on what the dynamic list main table
selects and what the value of the Read data dynamically property is:
„„ One of the following tables is  specified as the value of the Main table property:
the exchange plan, catalog, document list, document journal, chart of character-
istic types, chart of accounts, chart of calculation types, business process, job or
business process point table:
○○ A key identifying the table row: Reference.
○○ The Read data dynamically property is set: method 1 is used (see the
description above).
○○ The Read data dynamically property is  not set: method 2 is  used (see the
description above).
„„ One of the following tables is  specified as the value of the Main table property:
the main table of the information register, accumulation register, accounting
1-374 1C:Enterprise 8.3. Developer Guide

register, calculation register or RecordsWithExtDimensions accounting

register table:
○○ A key identifying the table row: RecordKey.
○○ The Read data dynamically property is set: method 1 is used (see the
description above).
○○ The Read data dynamically property is  not set: method 2 is  used (see the
description above).
„„ The filter criteria table is  specified as the value of the Main table property:
○○ A key identifying the table row: Reference.
○○ The Read data dynamically property is  not applicable.
○○ Method 2 is  used (see the description above).
„„ The SliceFirst or SliceLast virtual information register table is  specified
as the Main table property:
○○ A key identifying the table row: RecordKey.
○○ The Read data dynamically property is  not applicable.
○○ Method 2 is  used (see the description above).
„„ One of the virtual register tables is specified as the value of the Main table
property, excluding the tables stated above:
○○ A key identifying the table row: Count.
○○ The Read data dynamically property is  not applicable.
○○ Method 3 is  used (see the description above).
„„ The Main table property is  not set, a  custom query is  used:
○○ A key identifying the table row: Count.
○○ The Read data dynamically property is  not applicable.
○○ Method 3 is  used (see the description above).
Displayed data are transferred to the client in  chunks whose size is  defined as the
number of data items displayed by the list at any one time and incremented by two
rows.
When a form is created that contains a dynamic list, initially 32 data items of
every dynamic list (if the list contains more than 42 items) are transferred to the
client. If a  dynamic list shows more than 42 items, data are transferred to the client
when a form is opened using the standard algorithm: the number of data items
shown simultaneously by the list increased by two rows.
Dynamic lists use values of the following properties belonging to metadata object
attributes:
„„ Format
„„ Edit format
„„ Tool tip
„„ Negative value selection flag
Chapter 7. Forms 1-375

„„ Mask
„„ Multi-line mode flag
„„ Extended edit flag
„„ Password mode
When you display and edit filters or parameter of the data composition system, edit
format of the relevant field is  applied.
List setup property: Click the Open hyperlink to open the display settings form
for the dynamic list. Setting up the list is  similar to other operations in  the data
composition system.

Fig. 150.  Conditional Appearance of Dynamic List

Setting up the dynamic list in  the configuration, the developer can do the following:
„„ Specify the fields to order by;
„„ Describe the list filtering;
„„ Specify conditional appearance settings;
„„ Specify the fields for grouping the data.
The developer must specify the sort settings if the default sorting set up by the
system is  not acceptable.
TIP
Please keep in  mind that an inappropriate selection of the sorting fields (as well
as fields of data filtering and grouping) negatively affects efficiency of dynamic
selection.

IMPORTANT!
Sorting and grouping by fields that contain strings of unlimited length is  not
allowed.
1-376 1C:Enterprise 8.3. Developer Guide

From the point of view of the application developer, dynamic list settings consist
of several interrelated parts. The  main property to be used to manage dynamic list
settings is  SettingsComposer. This object contains three sets of settings that
define the final system settings applied to the dynamic list:
„„ Settings – settings created in  Designer mode.
„„ UserSettings – are settings changed by the user in  1C:Enterprise mode.
„„ FixedSettings – are settings set programmatically by means of the script.
Filter values transferred to the form via its parameters are also included in  this
property. The Filter, Order, Parameters, and ConditionalAppear-
ance dynamic list properties provide easy access to the fixed settings of the
dynamic list settings composer. In other words, these requests are identical:
List.SettingsComposer.FixedSettings.Filter and List.Filter.
When a  final setting of the dynamic list is  created, different variants of the settings
are combined as follows:
„„ If a certain type of settings is marked in full as a custom set, the resulting
settings will contain these custom settings (List.SettingsComposer.
UserSettings). If any items of the settings are marked as unavailable, these
settings will be added to the resulting settings from the List.SettingsCom-
poser.Settings property.
„„ If a  certain type of settings is  marked as a  custom type on a  by-element basis:
□□ Items marked as custom itemss will be added to the resulting settings
from the List.SettingsComposer.UserSettings property.
□□ Items marked as unavailable will be added to the resulting settings from
the List.SettingsComposer.Settings property.
„„ Fixed settings (List.SettingsComposer.FixedSettings) are added to
the resulting settings as is. Fixed and user settings cannot have settings with
the same names, i.e. a  filter with a  similar left value in  the condition.
Whether or no settings are available to the user is  controlled in  the dynamic list
settings window (see fig. 151).
An option in  the lower part of the window (see fig. 151) controls the layout of the
entire settings view in  the settings area (standard or quick). This  option is  available
for the purposes of filtering, ordering, grouping, and conditional formatting. If settings
are specified in  the Quick access editing mode, specify an empty group of the form
where the elements connected to the quick user settings of a dynamic list will be
located, in  the List setup property of a  form table that displays the dynamic list. If the
group is  not set, quick user settings will not be displayed in  the form. You can also
explicitly initiate the creation of user settings with the help of a  script by using the
CreateFormControlsOfUserSettings() method for dynamic list expansion.
Furthermore, you can enable the placing of specific settings elements in user
settings. This option is available for filter items and conditional formatting
(see fig. 151).
Chapter 7. Forms 1-377

Fig. 151.  Managing inclusions in  custom settings

There are two ways to enforce the downloading of special settings when a  dynamic
list is  opened:
„„ With the help of a  parameter of a  UserSettings dynamic list form. The  data
contained in  this parameter will be added to the dynamic list’s user settings.
„„ With the help of a  parameter of a  UserSettingsKey dynamic list form. If
this parameter is  specified when a  form is  opened, the user settings from the
settings storage with the specified key will be loaded to a  dynamic list (which
is  the form’s main attribute).

7.1.4. Attribute Properties

This section describes certain properties of form attributes.
Title: Text used as a  title for a  form element associated with this attribute if the
form element Title property is  not set.
Main attribute: Determines whether this form attribute is the main attribute and
defines the form extension.
Saved data – Where this property is  set for the attribute, changing it  interactively
will result in:
„„ An attempt to block the linked form attribute.
„„ Setting the change flag for the form (the Modified flag).
„„ If an attribute has the Saved data property set and the form is  in  the View only
mode, all of the form elements related to the attribute also are in  the View only
mode.
1-378 1C:Enterprise 8.3. Developer Guide

Fill сheck: Defines whether the attribute has to be checked for completeness (the
property value is  Display error). You can perform fill checks for the following
attribute types only:
„„ Primitive data types (Number, String, Boolean, Date, any reference types and
a  standard period)
„„ List of values
„„ Value tree
„„ Value table
NOTE
Attribute fill checking is  similar to the ValueIsFilled() function. In  tabular
section fill checking a  tabular section is  filled if it  contains at least one row.

7.1.5. Form Conditional Appearance

You can set conditional appearance of items in a form. Conditional appearance
settings are similar to conditional appearance settings in the data composition
system. These settings can be accessed from the properties palette of the form's root
item.
The following types of conditional appearance are available:
„„ Background color: It  changes the background color and can be applied to the
following form elements: text boxes, text document fields, tables, usual buttons
and table fields (label fields, text boxes, radio button fields and picture boxes).
„„ Text color: It  changes the text color and can be applied to the following form
elements: label fields, text boxes, text document fields, picture boxes, radio
button fields, tables, usual buttons, hyperlinks, text decorations, picture decora-
tions and table fields (label fields, text boxes and radio button fields).
„„ Font: It  changes the font and can be applied to the following form elements:
label fields, text boxes, text document fields, picture boxes, radio button fields,
calendar fields, tables, usual buttons, hyperlinks, text decorations, picture deco-
rations and table fields (label fields and text boxes).
NOTE
Changes of form element font done with conditional appearance is  not considered
when item size is  determined.
„„ Mark negatives: It  specifies if negative values are marked. It  can be applied
to the following form elements: label fields, text boxes and table fields (label
fields and text boxes).
„„ Horizontal position: It sets horizontal alignment for a value and can be
applied to the following:
○○ form elements: label field, text box, text decoration
○○ table fields: label field and text box
Chapter 7. Forms 1-379

„„ Unfilled mark: It sets incomplete value marks and can be applied to the
following:
○○ form elements: text box, table
○○ table fields: text box
TIP
If the Unfilled mark property is  managed via the conditional appearance, set the
Automark unfilled property of the field processed to No.

„„ Text: It is used to specify the text and can be applied to table fields (label
fields and text boxes).
„„ Format: It  changes the value output format can be applied to the following:
○○ form elements: group of Page type, group of Regular group type,
○○ table fields: label field and text box.
„„ Visibility – this is used only to disable rendering of table fields: the label
field, text box, switch field and picture box. The  location of cells with disabled
rendering is  allocated by changing the size of adjacent cells. The  cell stretching
algorithm can be different in  different client applications.
„„ Accessibility – this is  used only to disable the availability of table fields: the
label field, text box, switch field and picture box.
„„ Read Only – this is  used only to enable View only mode for table fields: label
field, text box, switch field, picture box.
„„ Show – this is  used only to disable rendering of table fields: the label field, text
box, switch field and picture box.
NOTE
Conditional appearance uses the current date of the computer adjusted to the time
zone of the 1C:Enterprise session. For details on time zones see page 1-292.
If conditional appearance is used to format a form table, the current table data
containing the column is  used when the condition is  calculated. If the formatted
field does not belong to the table, first table form (in the order specified in  the form
editor) data are used to calculate the condition.
You can use conditional appearance to specify certain appearance types for form
elements depending on the values of the form attributes; in  this case form appear-
ance is  dynamic, i.e. changes in  form data are tracked. You do not need to perform
any special actions to modify the form's appearance.
Consider an example of this type of appearance.
Assume you need to highlight rows in  a tabular section of a  Goods Issue docu-
ment if the count in  these rows is  less than 10.
To do this, you need to set the following conditions in the form's conditional
appearance:
„„ Conditional appearance type: text color. Select a  custom color.
1-380 1C:Enterprise 8.3. Developer Guide

„„ Set the following expression as a  condition: Object.Goods.Quantity Less than

"10". In this expression, Object is the form's main attribute, Goods is the
tabular section and Quantity is  the tabular section's attribute.
„„ Select the entire Goods tabular section as the formatted fields.

Fig. 152.  Conditional Appearance Settings

For the resulting view of the conditional appearance, see fig. 153.

Fig. 153.  Conditional Appearance Results

As you can see, the font color in  the first row of the tabular section is  now red,
because the count of goods in  this row is  below 10.
However, in  some cases you cannot highlight the entire row with a  special color;
instead, you need to highlight the tabular section cell than contains the count.
To do this, change the previous conditional appearance: select the Quantity field as
the formatted field instead of the entire Goods tabular section.
In this case a  single field is  highlighted (see fig. 154).
Please note that you can also use values of columns that are not associated with the
infobase data in  conditional expressions.
Chapter 7. Forms 1-381

Fig. 154.  Appearance of Single Field in  Tabular Section

7.1.6. Formatted Documents

In the process of application development, there is  a need to provide users with
the ability to edit formatted texts and documents. An example of this need is  the
creation of e-mails, different service notes and covering documents.
The FormattedDocument object is  designed to work with formatted documents,
it  is  used to programmatically process documents. The  Field of formatted docu-
ment text box is  used to interactively edit formatted documents.
It is  recommended to store formatted documents in  an infobase as
a  ValueStorage type attribute containing a  FormattedDocument type object.
Do the following to allow users to edit documents interactively:
„„ Create a FormattedDocument type form attribute and set the Saved data
property.
„„ Create a Text box type form element of the Field of formatted document type
and link it  to the attribute created.
„„ When form data are read (the OnReadAtServer() handler), load the document
to be edited (the SetHTML() method) to the form attribute, having previously
received the document from the infobase.
„„ Before you can write form data (the BeforeWriteAtServer() method), first
receive the result (the GetHTML() method) of the document editing and put
it  into the attribute stored in  the infobase.
You can use tabs while working with a  document. A tab is  a position in  a docu-
ment. When you define a  tab, consider the following:
„„ Document contents is  considered to be a  one character sequence.
„„ Line wrap is  considered to be one character.
„„ A picture is  considered to be one character.
1-382 1C:Enterprise 8.3. Developer Guide

You can use tabs to set and get a  selection or cursor position in  the editor or to
add or delete text items in  a document.
When the selection start position and end position match, it  means that there is  no
selection and cursor position is received. The same goes for setting the selec-
tion: if the selection start and end match, the cursor position is  changed with no
selection. You should also remember that if the text selected is  changed program-
matically, the selection is  not cancelled. The  selection keeps the positions which
were set before the text was changed programmatically.
An example of getting and setting the selection in  the formatted document editor
is  given below:
// Content – form attribute of FormattedDocument type
// Editor – form item of Formatted document type
// Begin – attribute forms of Number type. Specifies the position of the start selection.
// Finish – attribute forms of Number type. Specifies the position of the end of the selection.

&AtClient
Procedure GetSelection()

StartPosition = 0;
EndPosition = 0;
Items.Editor.GetTextSelectionBounds(StartPosition,EndPosition);
Beginning = Content.GetBookmarkPosition(StartPosition);
Finish = Content.GetBookmarkPosition(EndPosition);

EndProcedure

&AtClient
Procedure SetSelection()

StartPosition = Content.GetPositionBookmark(Beginning);
EndPosition = Content.GetPositionBookmark(Finish);
Items.Editor.SetTextSelectionBounds(StartPosition,EndPosition);

EndProcedure

When delete operations are used, the tab describing the start of the fragment being
deleted may be incorrect. If you need to keep the deleted fragment's starting point,
use the fragment start position. Thus an example of replacing selected text with
another text will look as follows:
Procedure InsertStringAtCurrentPosition(Editor, Content, String)
Var Beginning, End;

Editor.GetTextSelectionBounds(Beginning, End);
Position = Content.GetBookmarkPosition(Beginning);

Content.Delete(Beginning, End);

Beginning = Content.GetPositionBookmark(Position);
Chapter 7. Forms 1-383

Content.Insert(Beginning, String);

Bookmark = Content.GetPositionBookmark(Position + StrLen(String));

Editor.SetTextSelectionBounds(Bookmark, Bookmark);

EndProcedure

If a formatted document contains hyperlinks and it is displayed in View only

mode, the hyperlinks can be used for movement. This movement is performed
in  a new browser window.
Program access to the text of the formatted document is also available. The text
consists of FormattedDocumentParagraph type objects accessible via the Items
property of the FormattedDocument object. Every paragraph includes objects of the
following types: FormattedDocumentText, FormattedDocumentLinefeed and
FormattedDocumentPicture (items of the formatted document). This  collection
can be accessed through the Items property of the FormattedDocumentPara-
graph object. The  item boundary is  not necessarily a  word boundary.
The example below illustrates sorting of all the paragraphs of a  formatted docu-
ment with the text and a  separate processing of each paragraph.
Example:
For each Paragraph From Document.Items Do
If Paragraph.ParagraphType = ParagraphType.Normal Then
ProcessOrdinaryParagraph(Paragraph);
ElseIf Paragraph.ParagraphType = ParagraphType.BulletedList Then
ProcessList(Paragraph);
ElseIf Paragraph.ParagraphType = ParagraphType.NumberedList Then
ProcessList(Paragraph);
Else
Continue;
EndIf;
EndDo;

It could be useful to process items of a  formatted document that is  a part of the
paragraph if you need to delete all formatting such as italics or the bold font.
Example:
Bold = New Font(, , True);
Italic = New Font(, , , True);
Normal = New Font;
For each Item From Paragraph.Items Do
If TypeOf(Item) = Type("FormattedDocumentLinefeed") Then
Continue;
EndIf;
If Item.Font = Bold OR Item.Font = Italic Then
Item.Font = Normal;
EndIf;
EndDo;
1-384 1C:Enterprise 8.3. Developer Guide

The GetItems() and GenerateItems() methods can also help in  working with
a  text. These methods return the array of formatted document items. To understand
the difference between these methods, look at a  formatted sample document with
the string: 012 456 890. The string consists of 10 characters with "5" and "7"
characters replaced with spaces. Items located between positions 2 and 9 in the
document must be obtained.
BeginPosition = Document.GetPositionBookmark(2);
EndPosition = Document.GetPositionBookmark(9);
Result = Document.GetItems(BeginPosition, EndPosition);
For each Item From Result Do
Message("Text – " + Item.Text);
EndDo;

Result = Document.GenerateItems(BeginPosition, EndPosition);

For each Item From Result Do
Message("Text – " + Item.Text);
EndDo;

These methods differ in  that the GetItems() method returns all the items detected
between specified bookmarks (including all border items), i.e. in the example
considered the following text will be displayed:
Text – 012 456 890

And if the GenerateItems() method is  applied, the result will be as follows:
Text – 2 456 8

In other words, when you apply the GenerateItems() method, the system gener-
ates a  set of items in  such a  way as to include only the content of the formatted
document located between the bookmarks.
Please note that the GenerateItems() method changes the formatted document at
the time of the call, and if (in the given example) the GetItems() method is  called
again after the GenerateItems() method, the result will be as follows:
Text – 2 456 8

You get this result even if no changes have been made to the set of items received
after calling GenerateItems().

7.2. FORM PARAMETERS

Form parameters (the Parameters tab) serve two purposes:
„„ They describe a  set of data that define how the form opens (form parameteriza-
tion). It  requires listing all the necessary parameters and specifying their types.
„„ They define the parameters that affect the form's unique key. It  requires setting
the Key parameter property for the parameters to be included in generation
Chapter 7. Forms 1-385

of the form's unique key. When you attempt to open a  form, the system searches
the right form using the generated unique key. If the form with the obtained
unique key exists in  the system, it  is  the one to be returned; otherwise a  new
form is  created.
When you call a form, you can specify values of the parameters created by
a  developer in  the parameter structure along with the form's system parameters (if
any).
The form's parameters can be passed to the form when it  is  created. The  passed
parameters can be analyzed in  the OnCreateAtServer() event (the Parameters
collection is  a property of the ManagedForm object):

// At the call location.

// Generate a  form parameter.

Parameters = New Structure();
Parameters.Insert("Importance",
PredefinedValue("Enum.Importance.Important"));

// Open the form specifying the parameters.

OpenForm("CommonForm.ViewForm", Parameters);

// In  the form module.

&AtServer
Procedure OnCreateAtServer(Cancel, StandardProcessing)

If Parameters.Importance = Enums.Importance.Important Then

…
EndIf;

EndProcedure

IMPORTANT!
After you call the OnCreateAtServer event handler all the non-key parameters
of the form are removed from the Parameters collection.
TIP
The form's non-key parameters required in  further work should be saved in  the
form data.

7.2.1. Standard Form Parameters

To support automatic interaction between forms, the system provides a  number of
standard parameters that manage forms at the opening step. The  system uses these
parameters to select selection forms in  the form fields, open object forms, operate
standard commands, etc. In  other words, these parameters are used to implement
various interface operation scenarios within the system. However, the developer
1-386 1C:Enterprise 8.3. Developer Guide

can also use these parameters in  the 1C:Enterprise script by passing them when
calling the OpenForm() method.
For a  list of standard form parameters depending on the form extension type, see
section Script – Interface (managed) – Managed form – …extension… of the built-
in help.

7.2.2. Form Parameters Handling: Example

To demonstrate how form parameters work, we will implement an item selection
operation in the text box. The basis of this example is implementation of item
selection from a  list in  the 1C:Enterprise script.
Before you start your work with the example, you need to have a  configuration
with the following characteristics:
„„ A Goods catalog with a  hierarchy of folders and items;
„„ A Substitutes catalog with the SelectedProduct attribute of the Cata-
logRef.Goods type;
„„ Both catalogs have item forms.
Now, use the 1C:Enterprise script to implement all the mechanisms used by the
platform to select items from a  list. You will see the following:
„„ How standard form parameters are used;
„„ How the system uses the parameters;
„„ How the developer can use the parameters.
Add another parameter to manage how the selection form is  closed after an item
is selected. Name this parameter CloseAfterSelection (Boolean type). Add
it  to the ChoiceForm of the Goods catalog.
To open the item selection form, you need to create a  StartChoiceStartChoice
event handler for the SelectedProduct form element at the Substitutes catalog
item form:
&AtClient
Procedure SelectedProductStartChoice(Item, StandardProcessing)

StandardProcessing = False;

ChoiceParameters = New Structure();

ChoiceParameters.Insert("SelectionMode", True);
ChoiceParameters.Insert("ChoiceFoldersAndItems", FoldersAndItemsUse.Items);
ChoiceParameters.Insert("AllowRootSelection", False);
ChoiceParameters.Insert("CurrentRow", Object.SelectedProduct);
ChoiceParameters.Insert("CloseAfterSelection", False);

OpenForm("Catalog.Goods.ChoiceForm", ChoiceParameters, Items.SelectedProduct);

EndProcedure
Chapter 7. Forms 1-387

Special attention should be paid to the third parameter of the OpenForm() method.
This  parameter determines the owner of the selection form that will get notifica-
tions of the selection made. In  the above example the selection form owner is  the
form element; however, you can also specify the form in  this parameter. In  this
case you need to implement the ChoiceProcessing handler of the form module
and use it  to decide what form attribute to use to store the selected data.
NOTE
If the StartChoice event handler is  not implemented, the system performs its
actions instead. The  same is  true for all the other handlers used in  the example
above.
Now you need to process the passed parameters in  the selection form. You can do
this in  the OnCreateAtServer() handler of the selection form module:

&AtServer
Procedure OnCreateAtServer(Cancel, StandardProcessing)

StandardProcessing = False;

Items.List.ChoiceFoldersAndItems = Parameters.ChoiceFoldersAndItems;
Items.List.AllowRootSelection = Parameters.AllowRootSelection;
Items.List.CurrentRow = Parameters.CurrentRow;

CloseOnSelection = Parameters.CloseAfterSelection;

EndProcedure

To check whether the specified form parameters are valid, set the ChoiceFolder-
sAndItems property to Folders for the selection form's List table (catalog item
selection is  unavailable without the parameter).
NOTE
If the SelectionMode property is  not set to True for the List table that displays
the list of goods, product selection is  unavailable.
Now you need to process selection of the required item in the selection form.
To do this, define the ValueChoice event handler for the form table:

&AtClient
Procedure ListValueChoice(Item, StandardProcessing,Value)

StandardProcessing = False;
NotifySelection(Value);

EndProcedure

Finally, you need to process item selection in  the text box. To do this, you need to
process the ChoiceProcessing event for the SelectedProduct text box.
1-388 1C:Enterprise 8.3. Developer Guide

&AtClient
Procedure SelectedProductChoiceProcessing(Item, ValueSelected, StandardProcessing)

StandardProcessing = False;
Object.SelectedProduct = ValueSelected;

EndProcedure

Now you have implemented the system mechanism of value selection in  the form
text box.
IMPORTANT!
This example is not complete. It only demonstrates how to work with form
parameters.
When creating parameters (SelectedGoodStartChoice() handler), you can
replace the following string:
ChoiceParameters.Insert("CloseAfterSelection", True);

with the string:

ChoiceParameters.Insert("CloseAfterSelection", False);

In this case the selection form will not close after you make the selection. For
example, you can use this string to implement a  multiple-selection form (when you
need to select multiple products without closing the selection form).

7.3. FORM COMMANDS

You can use form commands to perform actions in  a form. The  commands only
describe the required actions. For a  command to perform its function, it  has to be
bound to a  form element (e.g., Button). Commands in  a form can be divided into
several groups.
„„ Commands created by a developer while he/she designs the form. These
commands require a  handler in  the form module.
„„ Standard commands provided by the form main attribute extension and list
attribute extensions (e.g., an object tabular section, dynamic list, information
register record set, etc.) if this attribute has an associated form element.
„„ Global commands provided by the global command interface (for details on
the command interface see page 1-83). These commands can be non-parameter-
ized or parameterized. Parameterized global commands are available in  a form,
only if the form has parameter sources with the appropriate types.
Availability of the standard commands and form elements is determined by the
Command set property of the relevant form element.
Chapter 7. Forms 1-389

Commands provided by the global command interface (the Global commands tab)
can be located anywhere in  the form, just as the form commands.
The Action property specifies the handler that implements the action of the
command. If no handler is  set, the command is  unavailable. You can only select
client-side procedures and functions without parameters in this field (for details
see page 1-390).
If the command modifies the form data, you should specify it in the Modifies
saved data property. When you attempt to execute the command, the following will
occur:
„„ An attempt to block the linked form attribute is  made. Where the attempt fails,
the command will not be executed.
„„ The change flag for the form (the Modified flag) is  set.
If the command property is  set to Saved data and the form is  in  the View only
mode, all form items connected with this command will have the status View only.
In addition, when a  global parametrized command whose parameter is  provided
by an attribute with the property set to Save data is  executed for a  new unsaved
object, the execution will result in  an attempt to write the object. In  this case the
user will be asked whether writing is  necessary. If the answer is  no, the command
will not be executed.
NOTE
If command bars and context menus with the specified command source are filled
in  automatically, standard commands are not added if the item has buttons with
the same commands added manually. This  logic does not apply to the commands
added from a  fragment of the global command interface.
To facilitate development of various dialogs, standard form commands include
Yes, No, OK, Cancel, Retry, Abort and Ignore. If a  command of this type is  added
to the form, clicking the button does the following:
„„ If the form is opened in the modal mode, it is closed and a value of the
DialogReturnCode type is  returned;
„„ If the form is  opened in  the non-modal mode, it  is  only closed.
The command's Name property is used to generate a name for the command
execution handler.
Use: For details see page 2-942.
Functional options: Defines what functional options are associated with this form
attribute. For details on functional options page 1-211.
1-390 1C:Enterprise 8.3. Developer Guide

7.4. FORM MODULE

A form module is  a set of procedures and functions. Module variables and module
body are allowed.
Each procedure, function or variable declaration of a form module must be
preceded by one of the following compiler directives:
„„ AtClient: Specifies the method is executed at the client, while the variable
lives as long as the client-side form.
You are allowed to call any methods from a  client method.
„„ AtServer: Specifies the method is  executed on the server, while the lifetime of
a  variable lasts as long as a  server call execution.
Calls of server-side, server-side out-of-context and сlient/server out-of-context
methods are allowed for server-side methods.
„„ AtServerNoContext: The  method is  executed on the server outside the form
context. Variables cannot be preceded by this compilation directive.
The form's context is  not available to such methods. When these methods are
called, there is  no data roundtrip. Using out-of-context methods gives a  signifi-
cant decrease in overheads when calling a server-side procedure from the
client-side application environment.
It is  allowed to call server-side methods of common modules from server-side
out-of-context form methods.
„„ AtClientAtServerNoContext: The method is executed both at the client
and at the server, outside the form context. Variables cannot be preceded by this
compilation directive.
Moreover, this method has no access to the form module variables.
You can call methods of non-global server-side common modules and methods
of non-global common modules with the Server and Client (Managed applica-
tion) check boxes from the сlient/server out-of-context method.
If a  procedure is  not preceded by a  compiler directive, it  means that the default
directive is  used. The  default directive is  AtServer.
If you use the context call to transfer control from the client to the server, please
note that before the call the form data are passed to the server which is  followed
by the server call execution, and then the form data are passed back to the client.
This  might take quite a  long time. However, an out-of-context server-side call
does not require this kind of transfer; therefore, it  is  faster.
You are allowed to use preprocessor instructions in the form's program module
(i.e. a  code fragment outside procedures and functions) to expressly mark the code
areas that initialize the relevant variables.
IMPORTANT!
You cannot save data between two calls of the server-side form in  the server-side
form variable.
Chapter 7. Forms 1-391

You are not allowed to use multiple compiler directives before a  single method or
variable. You are not allowed to have multiple methods or variables with the same
names differing only in  compiler directives.
Form command handlers created by the developer can only be included in the
client-side methods of a  form module.
In the form module, you are recommended to use preprocessor directives within
procedures and functions only.
NOTE
To understand the possible results in case when the preprocessor instructions
cross the procedure boundaries, you should take into account that the preproces-
sor instructions are processed before compiler directives.
For a  complete list of compiler directives and preprocessor instructions, see page
1-157.
Review the following example of using compiler directives:
&AtServer
Var ServerSideVariable;

&AtClient
Var ClientSideVariable;

&AtServer
Procedure ServerSide()
Message(ServerSideVariable);
EndProcedure

&AtClient
Procedure Command1Execute()
Message(ClientSideVariable);
ServerSide();
EndProcedure

#If Server Then

ServerSideVariable = "Server";
#EndIf

#If AtClient Then

ClientSideVariable = "Client";
#EndIf

7.5. FORM ELEMENTS

Hierarchy of form elements defines the appearance and set of controls displayed
in  the form. There are several types of form elements:
„„ form is  the form proper which is  a root item in  the item tree
„„ form field
„„ form decoration
1-392 1C:Enterprise 8.3. Developer Guide

„„ form table
„„ form button
„„ form groups
Form fields and tables are always associated with the form data. If the associated
attribute is not specified, is unavailable at the client due to right restrictions or
is excluded from the set of attributes (the View and Edit properties of the form
attributes), the field is not displayed in the form and is automatically removed
when the form is  created in  the execution mode.

7.5.1. Common Properties of Form Elements

This section describes common properties of form elements. Properties which
is  specific for the elements are described below.

7.5.1.1. General Property Category

The Title position property determines how an element title is  displayed. The  title
is a synonym of data associated with the selected element if the Title property
is  not defined for the form element. The  title always ends with the ":" character (it
is  automatically appended by the system).
When you add a  element, use the Data property to specify a  reference to the form
attribute associated with the element. If the from element has no attribute associa-
tions, it  will not be displayed in  the form. When you add a  button to the form, use
the Command property to specify a  reference to the command to be executed when
the button is clicked. If the button has no command association, it will not be
displayed in  the form.
A form element can be View only (no changes allowed) if its View only property
is  set (in the Designer or programmatically), the owner group View only property
is set or if the associated form attribute has the Saved data flag and the form
is  View only.
You can manage form element visibility in  two properties: Visible and User visibility.
The first property can be edited in the form editor (the Designer) or program-
matically. The  User visibility property is set up in the Designer only and defines
the initial visibility of the form element for roles. The  final form element visibility
results from AND concatenation of Visible and User visibility properties for a  specific
user. For a description of how to edit the User visibility property see page 2-942.
Moreover, editing form element visibility in  the Customize form dialog box, the user
actually modifies the User visibility property for a  specific form element.
For a  description of the Height and Width properties (or Height in  table rows) see
page 1-408.
You can use the Skip on input property to skip the element when using the Enter
key to tab between form elements. If the property is  set to Yes, the item will be
Chapter 7. Forms 1-393

skipped when pressing Enter (but it  will be available when pressing the Tab key
or pointing to it  with the mouse). If the property is  set to No, the item will not
be skipped when you press Enter. There is  also the option to specify automatic
skipping of form elements. For this you need to set the property to Auto. In  this
case the following algorithm is  used:
„„ The Field type element will be skipped if it  is  a label field or a  picture box,
depending on the Display warnings during editing property (see page 1-400).
„„ The Button element will not be skipped if it  is  a default button.
„„ The Decoration element will be skipped.
„„ The Table element will not be skipped.

Special Modes of Elements-Attribute Associations

As noted above, any element that displays data has to be associated with a  form
data attribute. In addition to the standard attribute association, several special
modes are available.

Association with Current Table Data

A form element can be associated with an attribute representing a column in a
table placed in the form. In this case the element displays the field data from
the current table row. This  type of association is  allowed both for fields and for
tables; the relevant column does not have to be displayed in  the table. The  element
associated with the current data can be in  either the View only or the edit mode.
Assume you need to add a field that displays the price for the current product
row to the form. To do this, insert the field (it can be a  Label field or a  Text
box) in the appropriate location in the form elements hierarchy and select
Object.Goods.Price as the field data (in the Attribute selection dialog box). Here,
Object is  a form's Document attribute for a  specific type, Goods is  the docu-
ment's tabular section and Price is  the tabular section's attribute.

Attribute Associations with Specific Table Row

The form item can be linked with an attribute representing a  column of a  speci-
fied table that is  a form attribute. This  link is  allowed both for fields and tables.
Moreover, the corresponding column does not have to be displayed in  the table.
The  specific row is  defined by the row index (e.g. ValueTable[1]) or an index
sequence for hierarchical tables (e.g. ValueTable[2].TotalsList[4]). The item
linked with current data may be both in  the View only mode and in  the edit mode.
NOTE
This link is  not supported for dynamic lists.
For instance, you need to place in  the form a  field that displays a  value of the
Debt field from Row 4 of the Contragent value table. To do this, add a  field
1-394 1C:Enterprise 8.3. Developer Guide

(the field type can be both Label field and Text box) to the required location in  the
hierarchy and select Contractors[3].Debt (in the Attribute selection dialog) as
data for this field. Here Contractors stands for an attribute of the (ValueTable)
type, and Debt is a  column of the value table.
If these fields reference to a  missing row, they cannot be edited even when a  text
box is selected, otherwise any change made in the text box will also be made
in  the table to which the text box provides the reference.
In the example above, if the user changes the text box, the value from this text box
is  passed to the Debt column of Row 4 in  the Contractors value table.
Attribute Association Through Reference
If the form data have reference-type attributes (e.g., CatalogRef), a  form element
can be associated with the attribute retrieved using the reference. Data for these
elements are automatically retrieved and updated whenever the reference modifies.
Attribute association through reference can have any level of nesting. Elements
associated with this type of attributes are always View only.
NOTE
Attribute retrieval through references is  not allowed for composite-type attributes
(including CatalogRef, DocumentRef, etc.).
Assume you need to add a  field that displays the article for the current product
row to the form. To do this, insert a  Label field in  the appropriate location in  the
elements hierarchy and select Object.Goods.Product.Article as the field
data (in the Attribute selection dialog box). Here, Object is  a form's Document
attribute for a specific type, Goods is the document's tabular section, Product
is  the tabular section's attribute and Article is  an attribute of the Goods catalog.
Association with Collection Totals
An element can be associated with attributes representing the collection's totals: the
tabular sections, recordsets and list of values (only the number of rows in  a collec-
tion). These attributes can include:
„„ Totals for the numerical fields;
„„ Row count in  the collection.
Elements associated with this type of attributes are always View only.
As an example, add a  field that displays totals for the Goods tabular section to the
form. To do this, select Object.Goods.TotalsSum as the form field data, where
Objectis the form's main attribute, Goods is the document tabular section and
TotalsSum is a special attribute. In addition to the element associations, other
association types are allowed, too. You can set associations to display data in  a
table footer or tab header (Page type groups).
Depending on the type of data displayed by the form element (text box, button or
group), you can use the Type property to specify the data display method.
Chapter 7. Forms 1-395

7.5.1.2. Use Property Category

For details on how to use the Quick choice property see page 1-274.
For information about the Choice parameters links and Selection parameters
properties see page 1-274. If the Choice parameters links and Selection parameters
properties are set both in  the properties of a  metadata object attribute and in  the
form element properties, their values are combined. The  OR concatenation is  used
(by parameter names).
You can specify an extended tooltip for the following form items:
„„ Field
„„ Table
„„ Group
„„ Button
„„ Decoration
The extended tooltip is  defined via the Extended tooltip property of the respective
form item. To be able to specify this tooltip, select Show extended tooltip in  the
context menu of the form item. In  this case the extended tooltip represents a  form
decoration of the Text type. It allows you to specify a tooltip using various
appearance types (color, font, etc.). This  can be done by selecting the Formatted
row value of the radio button in  the extended tooltip editing window. The  text of
the extended tooltip should be specified in  the Title decoration property. You can
also specify the tooltip display mode for the foregoing form items: around the form
item, a  button near the form item, a  pop-up window, or the display mode will be
selected automatically. Where the Button display mode is  specified, the Title prop-
erty of the extended tooltip with formatting will be displayed. Where the Pop-up
display mode is  specified, the system will display the Title property of the extended
tooltip but in  the form of an ordinary row (without formatting).
When the Tooltip property and the Title property of the extended tooltip are speci-
fied simultaneously, the text from the extended tooltip will be displayed.

7.5.1.3. Events Property Category

This group combines references to handlers provided by form elements.

7.5.1.4. Element Pictures

You can use pictures to represent form elements. You can select pictures using one
of two methods:
„„ The Designer
„„ Programmatic selection
If you select a picture programmatically, it can be either a blank picture or
a  picture from the configuration picture library.
1-396 1C:Enterprise 8.3. Developer Guide

If a  picture is  selected in  the Designer, you can use another option of selecting
a  file on the hard drive (an external picture). You are only recommended to use
pictures of this type when you develop external reports or data processors that can
be used in  various configurations and the picture is  a meaningful formatting item;
in  other cases using these pictures is  undesirable. You cannot select an external
picture for form commands and global commands.

7.5.2. Form
It describes the form's visual properties. Element of this type is always unique;
it is located in the element hierarchy root. The form properties also describe
handlers of form events.
The form opening mode is  controlled by a  special property: Window open mode.
This property defines how the window is  opened:
„„ Independent: The  form opens in  a non-modal window that represents an auxil-
iary application window:
○○ Forms in  separate windows. A form is opened in a non-modal window
which is  the application’s auxiliary window.
○○ Forms in  tabs. A form is  opened in  a separate tab.
○○ Taxi. The  form is  opened in  the work area of the main application window.
„„ Lock parent window: The  form opens in  a non-modal window, but this mode
locks operations with the form used to open the current form. This mode
is intended for the forms that are used for short periods of time and do not
require a  lot of data to be entered, e.g. forms for entering items in  catalogs with
a  small number of attributes. This  mode is  similar to the modal form opening
mode; however, when you open a  module from the 1C:Enterprise script, the
module operation is  not interrupted while you are using the opened form. All
other actions with the form are identical to the operations with non-modal
forms. In  this case the form is  also opened in  an auxiliary window.
If you open a form in this mode, it is not included in the search of forms
that have already been opened. If you try to open an identical form (even if the
unique parameter is  set to False), the form opened in  the Lock parent window
mode will not be found and a  new form will be displayed.
This mode is  set by default for the following forms:
○○ Catalog item and folder
○○ Exchange plan node
○○ Item and folder of a  chart of characteristic types
○○ Account
○○ Calculation type
○○ Task
○○ Record of an independent information register
Chapter 7. Forms 1-397

„„ Lock the entire interface – similar to the form that is  opened in  the Lock parent
window mode, but in  this case one is  blocked from working with the parent
form and the full interface of the application. This mode for opening is not
used as a  default setting.
The following algorithm is used to define the locked window when you open
a  form in  the lock mode:
„„ If the FormOwner property specifies a form which is not closed, the form
window is  locked;
„„ If the FormOwner property specifies a  form element in  a form and the form
is  not closed, the owner form window is  locked;
„„ In other cases (if the FormOwner property is  Undefined or the owner form
is  closed) the current window of the client application is  locked.
The Window opening mode property does not affect the way a  form opens if the
modal mode is used or if the form is opened in an existing main or auxiliary
window.
For a  description of automatic title generation see page 2-1195.
The Vertical scrolling form property determines how form elements will behave if
the form is  collapsed vertically. If the property is  set to Use or Auto (determined
for a  specific form as Use), a  vertical scroll bar is  visible after the vertical size
of form elements reaches the size specified when the form was edited in  Designer
(this refers to the elements whose height is also determined automatically). If
a  property is  set to UseIfNecessary, the form elements will shrink vertically to
their minimal size before a  scroll bar appears.
For instance, there is a form with the attribute List of type DynamicList.
This  attribute is  shown in  the form as table List, for which the height is  set to
8 table lines. If the form’s Vertical scrolling property is  set to Use, the form will
hardly decrease in  size at all:

Fig. 155.  Vertical scroll in  a form. Use

In this case, the vertical scroll bar appeared almost immediately after an attempt
was made to vertically shrink the form.
If the form’s Vertical scrolling property is  set to UseIfNecessary, the form will
first shrink vertically to its minimum, and then a  vertical scroll bar appears.
1-398 1C:Enterprise 8.3. Developer Guide

Fig. 156.  Vertical scroll in  a form. Use if necessary

If the property is  set to Auto, the form’s behavior is  defined by the system based
on the type of the main form attribute:
„„ If the main attribute of the form is  of type DynamicList or of type Repor-
tObject, and the ReportResult property is specified for the report form
extension, Auto is  treated as UseIfNecessary;
„„ In all other cases Auto is  treated as Use.
You can display a  command bar for a  form (you can use the Command bar posi-
tion property to manage the bar location in  the form). The  set of standard form
commands is  managed using the form's Command set property.
If the Enable form change property is  off, the user cannot change the make-up and
relative position of form elements in  the 1C:Enterprise mode.
The Check fill automatically property checks how form data are filled. For details on
the fill check see page 1-270.
If the form Save form data in  the settings property is set to Use list, the Save
column becomes available in  the attribute list. The  attributes with the Save prop-
erty set to True are saved in the form data storage (for details see page 1-223).
In  this case the system uses either the storage from the form's Settings repository
property or the storage from the configuration's Form data settings storage property.
NOTE
You can't check the Save checkbox for object tabular sections.
You can make the form View only using its ReadOnly property which can only be
changed programmatically. If this property is  set to True, the following standard
commands become unavailable (including the cases when you try to invoke them
using the keyboard shortcuts):
„„ For all forms:
○○ Restore settings
„„ For table boxes:
○○ Add
○○ Copy
○○ Delete
Chapter 7. Forms 1-399

„„ Generate commands
„„ For object form extensions, information register records and constants:
○○ Write
○○ Write and Close
○○ Post
○○ Post and Close
○○ Clear posting
○○ Activate
○○ Completed
„„ For selection form/settings extensions:
○○ Finish editing
○○ Select settings
„„ For table box extensions in  dynamic lists:
○○ Mark for deletion
○○ Post
○○ Clear posting
○○ Create group
○○ Move to folder
„„ For table box extensions in  value lists:
○○ Edit
○○ Move up
○○ Move down
○○ Sort descending
○○ Sort ascending
○○ Pickup
„„ For all the commands that modify the following collections of the data compo-
sition system:
○○ Settings collections
○○ Collections of available fields
„„ For table box extensions for FormDataCollection, FormDataTree, FormDa-
taStructureAndCollection:
○○ Edit
○○ Move up
○○ Move down
○○ Sort descending
○○ Sort ascending
Form element associated with these commands are also unavailable.
1-400 1C:Enterprise 8.3. Developer Guide

If the form is  Read Only and its main attribute is  a dynamic list, all tables asso-
ciated with the list also become read-only. Moreover, if the Folder List property
is filled, the form element indicated in this property also becomes read-only.
However, the View only property of the form elements remains unchanged.

7.5.3. Field
The Field form element is  used to display and edit a  form attribute. A form field
can have one of the following types:
„„ Text box
„„ Label field
„„ Check box field
„„ Image field
„„ Radio buttons
„„ Text document field
„„ Spreadsheet document field
„„ Calendar field
„„ Progress bar field
„„ Track bar field
„„ Chart field
„„ Gantt chart field
„„ Dendrogram field
„„ Flowchart field
„„ Geographical schema field
„„ HTML document field
If the field is subordinate to a Table form element, it can be assigned the
following types:
„„ Input field
„„ Picture field
„„ Label field
„„ Check box field
If you insert a  Radio buttons field, you should specify the form element Selec-
tion list property that defines the number and contents of values for radio buttons.
By default radio buttons are positioned horizontally. If you want to arrange them
vertically, change the value of the Column count property.
You can specify a viewing type for fields like Checkbox and Radio buttons.
Use the Check box type property of the corresponding form element to do this. You
can select a  checkbox view or a  toggle switch view for the checkbox field.
Chapter 7. Forms 1-401

Fig. 157.  Checkbox or toggle switch

Fig. 157 shows different variants for representing the checkbox field. The  upper
part of the picture shows the checkbox field as a  toggle switch, and the lower part
as a  checkbox. You can select a  radio button view or a  toggle switch view for the
checkbox field.

Fig. 158.  Radio button or toggle switch

Fig. 158 shows different variants for representing the radio button field. The  upper
part of the picture shows the radio button field as a  toggle switch, and the lower
one – as a  radio button.
If you want to add a  text box to the form (available field types: spreadsheet docu-
ment field, chart field, Gantt chart field, dendrogram field, graphical schema field,
geographical schema field), you have to create an appropriate form attribute and set
it  as the form element data.
If you want to add an HTML document field to the form, you have to create
a  String-type attribute and an HTML document field and set the generated attribute
as the field data. You can use a  URL or HTML document text as a  value for the
form attribute.
NOTE
Please note that some HTML functionalities may not be supported if an HTML
document field is  used. In  particular, this includes status scripts (variables that
store values required in  different event handlers), the parentWindow property of
an HTML document, and any work done with SVG markup language.
If you want to place a  formatted document field on the form, you have to create
a  FormattedDocument-type form attribute, create a  Field of formatted document-
type text box and set the generated attribute as the field's data.
NOTE
You can work with the GeographicalSchema attribute on the server only.
If you use the form text box to edit an auto-filled attribute that can be filled manu-
ally (in rare cases), you can implement this behavior using the text box Display
warnings during editing and Warnings during editing properties. If the Display
warnings during editing property is  set to Show and you attempt to edit the field,
1-402 1C:Enterprise 8.3. Developer Guide

1C:Enterprise displays a  warning with the string that is  specified in  the Warnings
during editing property or auto-generated.
If the AutoMarkIncomplete property of the input field is set to False,
its MarkIncomplete property will be automatically actualized when a value
is  transferred from an attribute to the input field.
For the standard Code and Number fields (for objects with auto-numbering), the
auto-generated string is  Number filled automatically when writing, while for other
fields it  is  Edit field Field Name not recommended.
If the Display warnings during editing property is  set to Auto, the standard Code and
Number attributes will use the Show value, while other fields will use Do not show.
The Display warnings during editing property also affects the text box Skip on input
property. When the Skip on input property is  set to Auto, the field is  skipped on
input if the Display warnings during editing property is  set to Show (or Auto for the
standard Code and Number fields).
You can use one of two methods to edit the form's StandardPeriod
or StandardBeginningDate attributes:
„„ Use a  single form field that will be added to the form and directly associated
with the edited attribute. In  this case all editing is  performed in  this field.
„„ Use multiple fields. You can add fields associated with the attribute properties
to the form. In  this case a  developer can independently implement the required
logic of interaction between the standard period option and date values.
The property of the Entry suggestion text box allows you to specify a  tooltip to be
generated just "inside" the text box provided that the following prerequisites are met:
„„ The linked attribute type is  neither Number nor Date.
„„ The linked attribute value does not include a  default value for this type.
„„ The input focus is  not on this text box.

7.5.4. Decoration
Decoration represents an appearance form element. It  is  not associated with data
(form attributes). It  can be a  label or a  picture.
TIP
You are recommended to use decorations for constant text explanations. If text
can be modified programmatically, it  is  recommended to represent it  as a  label
field.

7.5.5. Table
The Table form element visualizes table data. It  can be represented as a  dynamic
list, tabular section, value list, etc.
The position of the table command bar is  managed in  the Command bar position
form element. The  set of standard commands in  the table command bar is  defined
Chapter 7. Forms 1-403

in the Command set property. Commands disabled in this property become

unavailable.
You can group columns using the Group form element. For details see page 1-409.
You can specify how to display the form's ValueList attribute. If you select Table,
the value list will be displayed as a  table with the following columns: Value, Pres-
entation, Check and Picture. Please remember about the way of displaying values
in Value column. This column shows the values of the Presentation column.
The  value itself does not change. You select Input Field, a  special window appears
where you can edit the list.
A standard set of editing commands, including the commands of selecting and
clearing check boxes, is available for a table associated with a ValueList
attribute.
If the table is  associated with a  DynamicList attribute that has grouping set in  the
list settings (the form attribute's List setup property), the list is  always displayed as
a  Tree (the Display form element property), regardless of the display mode set by
the developer. If the table box associated with the dynamic list is  View only and
you open object forms from this list, their ReadOnly parameter is  automatically
selected.
You can also manage list updates when data change for tables associated with
dynamic lists. To do this, use the Update when data is  changed property. If this
property is set to Auto, the list is auto-updated when any changes are made to
the displayed data. If the property value is  Do not update, the list is not auto-
updated; in  this case updating the list requires explicit execution of the Refresh()
command. If the dynamic list is auto-updated with a regular interval and its
Update when data is  changed property is  set to Auto, the interval starts after the
last data change; however, if the property value is  Do not update, the interval starts
after the last call of auto-update or execution of the Refresh() command.
If the table is associated with the main form attribute of the dynamic list type,
you can manage the multiple selection mode using the relevant form parameter.
The  value of the form's MultipleChoice parameter is  copied to the table property
with the same name. In  this case the Selection mode property if set to Multiple if
the form MultipleChoice parameter is  True.
When you open the form, only data for visible tables linked with dynamic lists
can be read. As for tables that remain invisible when the form is  open, data can
be read only when tables are displayed for the user. In  particular, the value of the
CurrentRow property will be Undefined for invisible tables. This should be
noted when developing the form logic.
If the dynamic list is  in  the selection mode and you add a  new object, the system
checks the added object to the specified selection criteria; if the object matches the
criteria, the cursor is  placed over it  in  the table that displays the dynamic list.
If the form for a  chart of accounts list or a  catalog with item hierarchy is  opened
and its AllowRootChoice and SelectionMode parameters are set to True,
1-404 1C:Enterprise 8.3. Developer Guide

the following property values are modified in  all the form tables associated with
the form's main attribute (of the DynamicList type):
„„ The ShowRoot property is  set to True;
„„ The AllowRootChoice property is  set to True;
„„ The Representation property is  set to Tree.
If a  table displays a  hierarchical list with a  set picture row, this set picture will be
ignored for table rows displaying groups and the standard group picture will always
be shown.
NOTE
If a table displays a dynamic list (see page 1-369) and the Initial tree display
property is  set to Expand all levels, only a  list of rows shown on the first level
will be received when a  form is  created on the server, and then when the form
is  opened the rest of the rows displayed will be received. A separate server query
will be run for every group displayed.
When forms are being designed, certain situations can arise when you need to stop
scrolling some columns in a table. For example, you need to lock the Number,
Nomenclature and Sum columns in  a tabular section.
You also need to align Number and Nomenclature to the left side of the table, and
align Sum to the right side of the table.
FixedInTable properties are used for this operation. This  property is  available for
a  field located in  the table and for Column group-type groups (see page 1-406).
In  this example, we need to set the FixedInTable property to Left for the Number
and Nomenclature columns, and to Left for the Sum column. The  columns will be
aligned with the corresponding side of the table regardless of their location in  the
form editor. But these fixed columns are shown in the order in which they are
located in  the editor.
If the alignment attribute is  set for a  group, the whole group will be aligned (with
all the subordinate form elements) and the FixedInTable property value for any
subordinate items will be ignored. If the alignment attribute is  set for a  column
included in  a group with the FixedInTable property set to No, the column will be
processed as a  separate column not included in  a group.
The Search when typing property is used to determine how the system handles
character input from the keyboard, if a  table is  the active item and direct keyboard
input is  not available:
„„ Auto – in this case the search window is opened for the table linked to the
dynamic list, for other tables the search window is  not opened.
„„ Use – the search window is  opened for any type of attribute linked to the table.
„„ Do not use – the search window is  not opened for any type of attribute linked
to the table.
Chapter 7. Forms 1-405

7.5.6. Button
Each command in  a form is  displayed by the Button form element. A button can
be displayed in the command bar or the form itself. If the button is displayed
in  the form, it  can be represented as a  hyperlink (use the Type property to change
the setting).
Use the Command property to specify the command invoked by clicking the button.
If the Only in  "All actions" property is  set, it  means by default the button is  added
to the More (All actions) menu; however, the user can add the button to the bar
using a  special editor.

7.5.7. Group
When developing a  form, you can group items in  various ways. You can group
fields, form pages, commands or columns.
The form can contain groups of controls. These can be groups of fields, pages or
commands. You can also create groups of columns for Table elements.
You can create the following groups in  the editor:
„„ Regular group is  used to group form elements. It  can be formatted in  various
ways:
○○ None – the group is  not highlighted in  any special way;
○○ Light marking – the group’s header is  displayed in  a large green font;
○○ Normal marking  – the group’s header is  displayed in  a large green font;
Indents are placed around group elements (on either side);
○○ Strong marking – the group’s header is displayed in a large green font;
A green line is placed on the left (for the entire height of the group).
An indent is  placed at the bottom.
A regular group can be setup to enable the user (in 1C:Enterprise mode) to
collapse or expand such a  group. For instance, you can use such a  collaps-
ible group to place information that is  not important in  terms of the regular
form use but may be required every once in  a while for data review and
analysis.
Group behavior (regular or collapsible) is defined via property Behavior.
The  initial group state is  defined by the Collapsed checkbox. A group cannot
be collapsed or expanded if it does not display a header or if the header
is  empty. The  application developer cannot determine the current group state
from the script. She or he cannot forcibly collapse or expand a  group.
Use a  special image or a  hyperlink to control the group’s state (collapsed
or expanded). To specify the element that controls the group’s state, use the
Display mode control property. You can also specify the title of the group
(the Collapsed title property) to be displayed if the group is collapsed.
1-406 1C:Enterprise 8.3. Developer Guide

If the Collapsed title property is empty, a regular group title will be

displayed in  the collapsed state.
„„ Command bar is a form element that contains buttons and groups.
The  command bar's Command source property defines the form element (Form
or Table form element) that provides its own commands to be displayed in  the
command bar. The set of commands to be displayed in the command bar
is  defined by the Command set property of the form element that represents
a  command source.
You can add one of the following group types to the command bar:
○○ Submenu is  a group that allows you to create dropdown menus;
○○ Button group can be used to create a  group of buttons with the following
properties:
□□ The button group is  marked by separators on the left and on the right;
□□ Each button group can have a  separate command source.
○○ The Pages group is used to arrange a tabbed bar. Tabs can be located
vertically or horizontally. Scroll buttons are shown if tabs do not fit in  the
dedicated form area (based on the Pages group width or height).When you
add pages to the bar of this type, the number of nested groups to be added
has to match the number of pages in  the bar. The  Pages group can only
contain Pages groups:
□□ Page is a special group used to generate bar pages. This group can
contain other nested items.
„„ Column group can be used to group columns in  a table. You can use this group
to modify the column grouping rule (vertical or horizontal).
Groups can be nested.
You can move the form elements between groups. The system automatically
checks if such a movement is possible. If the movement requires any changes
in  the element properties (e.g. its Type), this change is  applied automatically. If
this causes changes in  requirements to child items, these items are either changed
automatically or deleted.
The group's View only property affects all child items in  the group.
The Enable content change group property controls how you can change group
content when a  user configures the form. If the property is  disabled, users can't
change the content or order of items inside the group. But this property does not
affect the ability of users to change the visibility of items inside the group.
If the Title data property is  specified for the group, these data are automatically
displayed in  the group title. If the Title property is  set for the group, Title data are
displayed in  parentheses after the title: Title (Title data).
All button groups (a command bar, popup, button group, context menu) are filled
in  using the same rules. Buttons are displayed in  the following order:
1. Buttons provided by the command source associated with the group.
Chapter 7. Forms 1-407

2. Buttons of the command interface if it  is  enabled for the command source.
3. Custom commands added to the group.
4. Commands of the More (All actions) menu (for a  command bar only).
5. The Help command is the last to be displayed (if it is provided by the
command source).
If the above auto-ordering of buttons in  a group is  unacceptable, you can use the
following options:
„„ Disable the Autofill check box for the form's command bar, context menu or
command bar of the element and add the required commands manually (in the
appropriate order);
„„ Disable the command source of the command bar, add the required commands
manually (in the appropriate order), then add a Button group and specify
a  command source for the group;
„„ You can manually position a  button associated with a  standard command from
the command source in  the required location of the command bar. In  this case
the command in  question is  not automatically added to the command bar.

7.5.8. Special Command Bars

In addition to creating custom command bars (the Group form element of the
Command bar type), the form editor can also be used to work with special
command bars:
„„ Form command bar: The system provides a form command bar. You can
manage its visibility, location and content. To manage the bar visibility and
location, use the form's Command bar position property; to manage the content,
use the Autofill property for a special Command bar group. Apart from the
standard commands that can be added to the form command bar, you can
also auto-add commands from the Form command bar section of the global
command interface.
If the form's main attribute is  a dynamic list and the form command bar has its
Autofill property set, the commands provided by the dynamic list are auto-added
to the bar. If the form also contains a  form element that displays as a  tree, the
form command bar will include the commands provided by the attribute associ-
ated with the element.
„„ Table command bar: The  system automatically provides a command bar for
a  Table form element. You can manage its visibility, location and content.
To manage the bar's visibility and location, use the form's Command bar posi-
tion property; to manage the content, use the Autofill property for a special
Command bar group.
„„ Element context menu: You can modify the standard context menu for a  form
element. To do this, display the context menu in the element tree using the
Show context menu command from the context menu for the form element.
1-408 1C:Enterprise 8.3. Developer Guide

If you add a  Group-type element in the element's context menu and specify
another element as a  command source for this group, the group added will be
populated with commands (in 1C:Enterprise mode) based on the same rules that
are applied for the element's context menu selected as the command source.
You can add custom commands created in  the command editor to all of the above
listed command bars.
If you want to add commands located in  the form command bar (see page 1-89) to
another command bar, do the following:
„„ Add a  Group – Command bar item to the command bar;
„„ Select this group as the Global commands of the form commands bar source.
If the command bar or the context menu that contains the group with the Global
commands of the form commands bar source also includes a group with the
Form command source and you fill in  this group, the commands from the form's
command interface are not added to the group.

7.5.9. Form Element Behavior

In the ReadOnly mode that is  set for both the specific item and the entire form,
form fields of the label, picture, label decoration and picture decoration types are
displayed as allowed.
If the Hyperlink property is  set to True for a  label or picture field, selecting the
hyperlink (using Enter on the keyboard or double-clicking it) will launch the form
element Click event handler. The  developer has to process the ReadOnly property
for the form or the relevant item and perform the appropriate actions (e.g., locking
data to prevent editing).
A Button form element associated with a  command with the Modifies saved data
property set to True is  displayed as disallowed if the ReadOnly property for this
element (or the entire form) is  True.
If actions that trigger server calls and form rebuild are performed in  the OnChange
form handler located in the form table, the OnEditEnd and BeforeEditEnd
handlers will not be called.
A spreadsheet document located in  the form scrolls vertically row by row.

7.5.10. Rules of Form Elements Placement

In the most general case the rules of form elements placement can be defined as
follows:
„„ Form elements are placed horizontally (each new form element to the right
of the previous form element) or vertically (each new form element below
the previous form element) depending on the form's Group property, with no
restrictions applied to the number of the displayed form elements.
Chapter 7. Forms 1-409

„„ The element display order is  defined by their order at the Elements tab of the
form editor.
„„ The form size (and form elements size) can be limited in  the Width and Height
properties (or the Height in  table rows property).
„„ If element placement results in  exceeding the specified form size, scroll bars
are used.
„„ If the displayed element is  a group, element placement rules within the group
are identical to those within the form.
Although this algorithm is simple, the developer can modify it using multiple
methods and improve the form's readability:
„„ form elements groups
„„ form elements sizes
„„ child elements width
Below each of the options is  described in  more detail.
IMPORTANT!
When you place form elements in  the form, both the main placement rules and
the additional rules covered below are applied.

7.5.10.1. Groups and Form Element Consolidation

Form elements can be consolidated using multiple types of the Group element:
„„ Command bar prevents modification of the placement rules selected for the
parent form element (another group or form).
„„ Page can be used to change the element placement rules.
„„ Regular group can be used to change the element placement rules.
„„ Column group can be used to change the placement rules for elements (form
table columns).
You can set item grouping (the Grouping property) and child item width (the Width
of subordinate elements property) for the Regular group or Page groups. Review an
example of using this grouping type (see fig. 159).
Consider how a  document form is  created. The  form element grouping is  set to
Vertical, but you want to place the document's Date and Number attributes in a
single row instead of two rows.
To do this, create a  group named DateAndNumber, set the Grouping property to
Horizontal and add the form Number and Date items to this group (see fig. 160).
1-410 1C:Enterprise 8.3. Developer Guide

Fig. 159.  Vertical Grouping

Fig. 160.  Horizontal Grouping

NOTE
Please note that groups can have any number of nested levels. The  Grouping
property can have a  different value for each nested group.
Chapter 7. Forms 1-411

7.5.10.2. Form Element Sizes

You can specify the size of each form element: its height and width. The size
is measured in abstract units of measure. The actual form element size in the
1C:Enterprise mode can differ from the specified dimensions. When the size of an
element is  defined, the system considers font (and its size) to be set in  the form
element properties.
NOTE
Any changes of form element font made with conditional appearance are not
considered when element size is  determined.
If the size is zero, the platform calculates the value automatically and tries to
achieve the best representation of the form on the screen.
If the size is  other than zero, the following rules apply:
„„ The size of the parent item limits the sizes of the child items;
„„ The child item size changes the parent item size until the previous requirement
is met.
If the parent item size is  too small to hold the child items, the following rules apply:
„„ If the items' height value is  too large, a  vertical scroll bar is  added;
„„ If the items' width value is  too large, their size is  reduced to fit them in  without
using a  horizontal scroll bar. However, the horizontal scroll bar appears in  the
form if its width is  reduced to the value that cannot accommodate the widths of
the other items.

7.5.10.3. Child Item Width

When you design a  form, you might want to place form elements in  two columns
and use the column width to highlight their importance.
To complete the first task (two-column placement), you should use groups; while
the second task requires use of the Width of subordinate elements property (for the
groups with horizontal item grouping).
IMPORTANT!
Please keep in  mind that the Width of subordinate elements property affects the
form element placement only when the parent group has horizontal grouping and
there are only two subordinate groups.
This property can have the following values:
„„ Auto: Item width is  auto-selected by the system.
„„ Equal: Equal width is  selected for the items.
„„ Left wide: The  correlation of the left and right item widths is  3:2.
„„ Left widest: The  correlation of the left and right item widths is  2:1.
1-412 1C:Enterprise 8.3. Developer Guide

„„ Left narrow: The  correlation of the left and right item widths is  2:3.
„„ Left narrowest: The  correlation of the left and right item widths is  1:2.
Review the following example.

Fig. 161.  Child Item Width

Assume you want to have two columns in  the document header. One of them (to
the left) should include the Buyer and Warehouse attributes, while the other (to
the right) should include the Price type and Settlement currency attributes. Since
the left-side column is  more important, you want to increase its width.
To do this, create a  Header group and set the Horizontal grouping type. Create
two more groups inside the first group: Left and Right. Each group is  assigned the
Vertical grouping type. Add the Buyer and Warehouse attribute to the Left group
and the PriceType and Currency – to the Right group.
After that set the Width of subordinate elements property of the Header group to
Left widest.
NOTE
The main purpose of the Width of subordinate elements property is  to specify the
dimensions to be used when the platform generates the form.

7.5.11. Form Element Boundaries Alignment

When you place an element in a form, the 1C:Enterprise system automatically
aligns the left boundaries of form element data based on the form element type and
certain rules. This  section discusses form element boundary alignment rules.
A form element consists of a data area – a form element area where data are
shown, and a  title area (title) – a  form element area where the title form is  shown
(see fig. 162).
Chapter 7. Forms 1-413

Data area standard width specifies the data area width and has the following
properties:
„„ is determined by attribute data type linked to the form element or by the Width
property of the form control
„„ does not depend on the Stretch horizontally property of the form element.

Fig. 162.  Form element structure

7.5.11.1. Data Area, Left Side Alignment

Common Rules
If you add several elements displayed on the left of the data area to a  Regular group-
type or Page-type form or a  group with vertical grouping (if the Grouping property
is  set to Vertical), then the left side of the form element data area will be aligned:

Fig. 163.  Left side alignment

But the following rules should be followed for such alignment:

„„ Extending the title will not make the data area width less than the default data
width:

Fig. 164.  Data area width is  less than default data area width

In the example shown in  the fig. 164 the data width becomes less than default
data area width.
Alignment will stop working when the first element title line is extended.
The  Name field data area width should be less than default data area width, if
alignment was applied. This  proportion adds one letter i to the title.
1-414 1C:Enterprise 8.3. Developer Guide

The title width will not be significantly larger than the maximum value of
default data area width and this field's title width:

Fig. 165.  Title larger than default area width

In the example shown in fig. 165, alignment stops working when the second
element title line expands in such a way that the First name, patronimyc, last
name field title width becomes significantly larger than the default data area width.
This  proportion changes when patronymic is  added to the title.
If it  is  impossible to determine single title width for several vertically positioned
elements based on the above rules, the system will define element sets inside which
the conditions are met. Grouping into sets does not depend on element vertical
order. Grouping starts with the control with the least width. Elements in  one set do
not necessarily follow each other.

Fig. 166.  Element set alignment

You should note the following when aligning elements:

„„ If a  form element has no title or the title is  not located at the left side, this
control is  not aligned.
The form table is  not aligned, even if it  has the title located at the left side.

Fig. 167.  Tables are not aligned

Chapter 7. Forms 1-415

„„ If there is an element for which alignment is not applicable between the
elements, it  does not affect the alignment.

Fig. 168.  Alignment is  not applicable for a  form element

„„ For a checkbox, displayed data are a rectangular area where the checkbox
is shown.

Fig. 169.  Checkbox alignment

Nested Groups
If form elements (with titles to the left) are located in  a Regular group-type group,
elements will be aligned along with border elements only if the Display property for
the group is  set to None. Otherwise, alignment of elements in  the group will not
consider elements around the group.

Fig. 170.  Alignment with element groups

7.5.11.2. Form Element Right Boundaries Alignment

Alignment of form element right borders does not depend on the Stretch horizon-
tally property of the form element. If the Stretch horizontally property is  set to Auto,
the system controls element right border alignment.
If the property is  set to No, this element does not change horizontal size, and if
there are nested elements it  does not allow you to change the horizontal size of
these elements.
1-416 1C:Enterprise 8.3. Developer Guide

If the property is  set to Yes, then:

1. The right border of the form element changes its position, until it  leans against
the other element (or form border), thus preventing further change in  its posi-
tion.

Fig. 171.  Stretching element to the right until delimiter is  reached

2. Nested form elements with the Stretch horizontally property set to Yes (or Auto
for some elements) also change the position of their right border if the parent
form element size changes.

Fig. 172.  Stretching subordinate elements

3. If there are other elements that can be changed to the right of the element, the
element is relocated until a restriction from p.1 is applied for the rightmost
element (the form element "pushes" its right-side neighbors).
Chapter 7. Forms 1-417

Fig. 173.  Right-side element movement

4. If the property Stretch horizontally is set to Yes for two or more adjacent
elements, when parent element horizontal size changes these elements adjust
their width simultaneously and proportionally.

Fig. 174.  Proportional adjustment

In the example in fig. 174, the Cancel button between decorations does not
change its size, since it  does not have the Stretch horizontally property.

7.5.11.3. Form Element Lower Boundaries Alignment

Alignment of form element lower borders does not depend on the Stretch vertically
property of the form element. If the Stretch vertically property is  set to Auto, the
system controls element lower border alignment.
If the property is  set to No, this element does not change vertical size, and if there
are nested elements it does not allow you to change the vertical size of these
elements.
1-418 1C:Enterprise 8.3. Developer Guide

If the property is  set to Yes, then:

1. The lower border of the form element changes its position until it  leans against
the other element (or form border), thus preventing further change in  its posi-
tion.

Fig. 175.  Element stretching

2. Nested form elements with the Stretch vertically property set to Yes (or Auto for
some elements) also change the position of their lower border if the parent form
element size changes.

Fig. 176.  Adjusting nesting element

3. If there are other elements that can be changed under the element, the element
is  relocated until a  restriction from p.1 is  applied for the lowest element (the
form element "pushes" its lower side neighbors). This situation is shown
in  fig. 176 (the Warehouse element).
Chapter 7. Forms 1-419

7.5.12. Drag-and-Drop Mechanism

1C:Enterprise supports drag-and-drop operations. You can use these operations
to transfer data between various elements. For example, you can drag and drop
catalog list items from one folder into another, drag and drop data from a  table
box to a  spreadsheet document field or transfer a  list of selected files from Micro-
soft Windows Explorer to any element.
Drag-and-drop operations are supported by the following elements:
„„ Form table
„„ Spreadsheet document field
„„ Calendar field
„„ Picture field
„„ Picture decoration
The following terms apply to the drag-and-drop operations:
„„ Data source: A form element that is  the starting point of the data drag-and-
drop;
„„ Data target: A form element that is  the destination of the data drag-and-drop.
You can enable or disable the element ability to provide or receive data, i.e. to be
a  data source or target. To do this, you can use the following element properties:
„„ Enable start dragging: Enables the element to provide data.
„„ Enable dragging: Enables the element to receive data. You can set these proper-
ties in  the properties palette or the 1C:Enterprise script.
When you click the selected area of the control, it calls the DragStart event
handler for the data source. This event passes DragParameters and Stan-
dardProcessing objects as its parameters. The  DragParameters parameter has
the following properties:
„„ Values: Contains the value to be dragged-and-dropped, e.g., it can be
a reference to an object for a table box or a spreadsheet document area for
a  spreadsheet document or a  date for a  calendar. You can assign a  custom value
to this property (e.g., a structure); in this case this value becomes the object
to be dragged-and-dropped. For a managed form table linked to a  FormDa-
taCollection, FormDataTree or FormDataStructureWithCollection type
form attribute the following items are passed as drag-and-drop values:
○○ row ID (or ID array), if drag-and-drop is  done within one table.
○○ collection item (or item array), if drag-and-drop is  done between different
tables.
„„ Action: Specifies the drag-and-drop action and is  a value of the DragAction
type.
„„ AllowedActions: Specifies valid drag-and-drop actions and is  a value of the
DragAllowedActions type. You can use this property to specify the opera-
tions that can be performed with the data from the source (e.g., copying only).
1-420 1C:Enterprise 8.3. Developer Guide

The StandardProcessing parameter enables or disables standard processing

of the drag-and-drop operation from the control. Standard processing for the
DragStart event is  the start of data drag-and-drop.
Then the data target calls the DragCheck event handler. This  handler is  invoked
every time the cursor points to a  new object in  the data target (e.g., a  new table
cell or a  spreadsheet document field or a  new date in  the calendar field). A set of
parameters for this event depends on the data target; however, the first two param-
eters are always the same. These are DragParameters and StandardProcessing
objects. Other parameters describe the object under the cursor. When processing
this event, you can manage the cursor shape; for example, you can specify that
dragging into a specific control is not permitted or only copying is allowed.
To do this, specify the required action in  the Action property of the DragParam-
eters parameter. Please note that the specified drag-and-drop action has to be
allowed, i.e. it  must not conflict with the value of the AllowedActions property.
For example, the Copy action does not conflict with the CopyAndMove value for
the allowed actions, while Move conflicts with Copy. The  StandardProcessing
parameter specifies whether the form element can perform standard processing of
the event. Standard processing of drag-and-drop operations depends on the control
type:
„„ For a table, it checks whether a value can be inserted, i.e. it checks the
value type; if the type matches the displayed data type, standard actions are
performed. Standard actions for hierarchical dynamic lists include moving to
a group; for tables that display record sets or tabular sections these include
reordering rows and copying.
If a  table has the ChangeRowOrder property set to False, when drag-and-drop
is  done within the table the Drag event will not be called.
If a table has the ChangeRowOrder property set to True, or drag-and-drop
is  done outside the table, default handling does not cancel drag-and-drop opera-
tion.
Default handling does not cancel drag-and-drop operation if the Selecti-
onMode is set to Multiple, the ChangeRowOrder property is set to True
or drag-and-drop is  done outside the table and only one item is  dragged.
„„ For a  spreadsheet document field, it  checks whether the passed value can be
inserted.
„„ For picture and calendar fields, there is  no standard processing.
If you release the mouse button in the form element, it calls the Drag event
handler. This event has the same set of parameters as the DragCheck event.
The  StandardProcessing parameter enables or disables standard processing
of the event by the form element. For a description of standard drag-and-drop
actions see above.
Then the data source control calls the DragEnd event handler. When processing
this event, the form element can delete the moved data or clear some variables.
Chapter 7. Forms 1-421

7.6. FORM COMMAND INTERFACE

The form's command interface includes:
„„ The form navigation panel
„„ The form command bar
You can edit the form's command interface by adding new or using existing
commands, etc.
Please note that the form's command interface should be edited in  a separate tab
of the form editor; it  describes the contents of the navigation panel in  the auxiliary
window that displays the form and partially describes the contents of the form's
command bar. This mechanism is primarily used to set up global interface
commands that need to be displayed in  these two panels of the form. The  contents
of the form's command bar is  determined both in  the item structure directly and
in  the command interface editor.
A command is  automatically added to the form command interface if the parameter
type of the parameterized command matches the form main attribute type.
Moreover, you can deliberately add a  command to the command interface panel
you choose. To do this, you just need to move it  to the right group in  the required
command bar.
If the Autoposition flag is  selected, it  means the system-generated default sequence
of commands will be used. If you uncheck this box, you can edit the command
sequence.
To set up visibility for the commands from the command interface panels, you can
uncheck the Autovisibility box and change the value in  the Visible column.

7.7. DIFFERENT APPROACHES TO MODALITY

7.7.1. Overview
One often needs to open a  form that would provide several functional capabilities
at the same time in  the applications developed with the help of 1C:Enterprise.
„„ Block working with other application interface fragments.
„„ Enable data input (e.g., responding to a  question).
„„ Stop application code execution before work with an open form is  completed.
These forms may be created by the application developer in 1C:Enterprise
script and be part of the platform (e.g., the forms that open methods Warning(),
Question(), etc.).
1C:Enterprise supports two ways to use such forms:
„„ Modal windows
„„ Blocking windows
1-422 1C:Enterprise 8.3. Developer Guide

Either a  single approach or mixed model can be used for an application. A special
configuration property is  used to control such functionality – Modality usage mode
(see page 1-169).
The first approach to modality usage (modal windows) includes the use of special
types of OS windows, i.e. modal windows. If this schema is used, script code
execution stops until the modal form is closed. A return value will be received
directly where the modal form was opened, and any actions using this value can be
performed immediately afterwards (with the same method): analyzing, part of an
algorithm, etc. Modal windows can be opened with the help of OpenFormModal()
or Warning() methods. However, modal windows are not supported on iPads and
are poorly supported in  a web client.
In these cases, we recommend that blocking windows be used. A blocking window
differs from the modal window as follows: when a  blocking window is  opened,
script code execution goes on. A callback procedure is  used to obtain the result of
the blocking window’s operations. This  peculiarity results in  the fact that an algo-
rithm that uses modal calls to control its work will have to be completely reworked
to be used with blocking windows. The  difference between the two ways of using
modal windows, from the point of view of the developer, is  shown in  the example
below. For example, there is  a certain client handler that asks the user a  question
and performs one or another application code branch, depending on the response
received.
Modal windows (example):
&OnClient
Procedure ExecuteAlgorithm()
Result = Question ("Execute fast or not slow?", DialogModeQuestion.YesNo);
If Result = DialogReturnCode.Yes Then
// First variant of the algorithm
Else
// Second variant of the algorithm
EndIf;
EndProcedure

In this mode (modal windows) script execution will stop at the Result = Ques-
tion() line and will continue only after the user responds to the question.

Blocking windows (example):

&OnClient
Procedure ExecuteAlgorithm(Command)
Callback = New NotificationDescription ("ExecuteAlgorithmCallback", ThisObject);
ShowQuestion(Callback, "Execute fast or not slow?", DialogModeQuestion.YesNo);
EndProcedure

&OnClient
Procedure ExecuteAlgorithmCallback(Result, AdditionalParameters) Export
If Result = DialogReturnCode.Yes Then
// First variant of the algorithm
Chapter 7. Forms 1-423

Else
// Second variant of the algorithm
EndIf;
EndProcedure

In this example (where blocking windows are used), an algorithm is  divided into
two parts:
„„ A place where a  question to the user is  displayed
„„ A place where the user’s response is  processed
However, these are different fragments of the application code. When
the ShowQuestion() method is called, script code execution does not stop.
However, the user will be able to answer the question only when the script code
execution is completed and control is transferred to 1C:Enterprise. That means,
the results of a  user using an open form cannot be obtained in  the point where the
method displaying the question form was called.
When the user answers the question, an export procedure will be called. The  appli-
cation developer should transfer the description to the blocking window opening
method. The  NotifyDescription object is  used to describe a  callback method.
A callback method may be located in a form module, a command module, or
a  common module. If you need to specify that a  callback method and blocking
window call method are in  the same module, use the ThisObject value. Also, you
can transfer different auxiliary data to the callback handler. This  data will be avail-
able in  the handler via a  formal parameter, AdditionalParameters. These may
be input data for the algorithm operations, different parameters, etc.
As a rule, after any method that is used for working with blocking windows
is  called, the method that contains such a  call shall be completed with immediate
effect, and the rest of code shall be placed in  a notification handler.
If a cascade call of callback methods is required, use the ExecuteNoti-
fyProcessing() method. This method can also be used if an action may be
implemented immediately before or after a  prompt concerning actions to be taken
is  displayed. For instance, if you try to reread a  data file, the current state of the
editor is  checked, and if the data in  the editor has been changed, the system asks
whether it  should reread the data.
Example:
&OnClient
Procedure RereadData(Command)

Callback = New NotifyDescription ("RereadDataEnd", ThisObject, FileDataName);
If Modified Then
ShowQuestion (Callback, "Data modified. Reread?" QuestionDialogMode.YesNo);
Else
ExecuteNotifyProcessing(Callback, DialogReturnCode.Yes);
EndIf;

EndProcedure
1-424 1C:Enterprise 8.3. Developer Guide

&OnClient
Procedure RereadDataEnd(Result, FileName) Export

If Result = DialogReturnCode.Yes Then
// perform data read
Modified = False;
EndIf;

EndProcedure

7.7.2. Using blocking windows

In thin and thick clients (unlike a  web client), the BeginPutFile() method stops
string code execution. However, it  will still be executed after the callback proce-
dure call operation transferred to the BeginPutFile() method is  completed. To
avoid behavioral differences when working in  a thin client and web client, place all
the code to be executed upon file placement directly to the callback handler.
If the application build logic requires that the user is asked a question when
a  form is  closed, this should be done in  a special way, as shown in  the example:
&OnClient
Var ResponseBeforeClose;

&OnClient
Procedure BeforeClose(Refusal, StandardProcessing)
If ResponseBeforeClose <> True Then
Refusal = True;
Callback = New NotificationDescription ("BeforeCloseEnd", ThisObject);
ShowQuestion(Callback, "CloseForm?", QuestionDialogMode.YesNo);
EndIf;
EndProcedure

&OnClient
Procedure BeforeCloseEnd(Result, AdditionalParameters) Export
If Result = DialogReturnCode.Yes Then
ResponseBeforeClose = True;
Close();
Else
ResponseBeforeClose = Undefined;
EndIf;
EndProcedure

Actually, a  form is  closed in  two steps:

„„ A question on whether a  form should (and can) be closed is  asked, and form
closing is  cancelled.
„„ When a user answers the question, the system marks, in a special client
variable, that the "real" closing of the form will be performed, and the form
is  closed once again.
Chapter 7. Forms 1-425

A value of the main property of the dialog to be closed is transferred as the

first parameter to a callback handler that is transferred when the Show()
method is  called, if ОК is  pressed in  the dialog, or in  other cases, Undefined.
This is true for the StandardPeriodEditDialog, FormatStringWizard,
FontChooseDialog, ColorChooseDialog, and ScheduledJobDialog objects.
For instance, if a  standard period is  edited, the StandardPeriod (or Undefined)
object functions as the first parameter of the callback handler.

7.7.3. Method mapping

When the existing algorithms that use modal windows are reworked into blocking
windows, the following table that maps the modal and blocking methods of the
global context and different objects should be consulted:
Object Modal method Blocking method
Global context OpenFormModal() OpenForm()
Question() ShowQueryBox()
OpenValue() ShowValue()
DoMessageBox() ShowMessageBox()
InputDate() ShowInputDate()
InputValue ShowInputValue()
InputString() ShowInputString()
InputNumber() ShowInputNumber()
InstallAddIn() BeginInstallAddIn()
InstallFileSystemExten- BeginInstallFileSystemEx-
sion() tension()
In s t allCr y p t o E x t e n - BeginInstallCryptoExten-
sion() sion()
PutFile() BeginPutFile()
StandardPeriodEdit- Edit() Show()
Dialog
FormatStringWizard DoModal() Show()
DataCompositionDe- ChooseAction(0 ShowActionChoice()
tailsProcess
FontChooseDialog Choose() Show()
ColorChooseDialog Choose() Show()
ScheduledJobDialog DoModal() Show()
ValueList CheckItems() ShowCheckItems()
ChooseItem() ShowChooseItem()
ManagedForm DoModal() Open()
ChooseFromMenu() ShowChooseFromMenu()
ChooseFromList() ShowChooseFromList()
1-426 1C:Enterprise 8.3. Developer Guide

7.8. WORK WITH FORM FROM 1C:ENTEPRISE SCRIPT

7.8.1. How to Open a  Form
You can open a  form using one of two methods:
„„ Use the OpenForm()/OpenFormModal() method;
„„ Use a  combination of the GetForm() method and the Open() method or the
DoModal() of the ManagedForm object.
In both cases you can pass form parameters to the form you are opening.
You are recommended to use the OpenForm() method in  all cases, except when
you need to open a  form in  the modal mode and then retrieve its results through
the attributes of a  form being opened.
This requirement has to be met because the modal form return value is  the data
returned by the form, and the developer has no access to the ManagedForm object
that retrieves the form attributes. If you first retrieve the form using the GetForm()
method, you can access the attribute after the DoModal() method is  completed.
Example 1:
// Open a  list form for the Goods catalog
// as read-only

Parameters = New Structure("ReadOnly", True);

OpenForm("Catalog.Goods.ListForm", Parameters);

Example 2:
// Open a  modal form and after it  closes
// access the form attributes

Form = GetForm("CommonForm.PeriodSelection");

Result = Form.DoModal();
If Result = DialogReturnCode.Yes Then

BeginDate = Form.BeginDate;
EndDate = Form.EndDate;

EndIf;

For a  description of how to work with form parameters see page 1-384.

NOTE
Do not open and close the same form programmatically in  the same script call.
Chapter 7. Forms 1-427

7.8.2. Redefining an Opened Form

There could be a  task in  application systems to open different forms with different
object parameters (or the current environment). For example, you need to open
different forms for the Nomenclature catalog item, for products and services. Or
for some automated workplaces you need to open different forms based on current
user settings.
To perform this task you need to create an FormReceiveProcessing event
handler in  the object manager module. You need to perform all the required valida-
tions in  this handler and make a  decision about which form to open. This  handler
is  called only if there is  an attempt to open a  default object form using default
form names.
Thus, when a  Nomenclature catalog item of the form element is opened, the
handler will be called in  the following situation:
OpenForm("Catalog.Items.ObjectForm");

But it  will not be called if you try to open the form as follows:
OpenForm("Catalog.Goods.Form.ItemForm");

Let's look at the example with different catalog item forms in  more detail.
When the form is opened, the View attribute of the Nomenclature catalog
is  analyzed. If this property is  equal to Enumeration.ProductTypes.Service,
open the ServiceForm form of the Nomenclature catalog.
Procedure FormGetProcessing(FormType, Parameters, SelectedForm, AdditionalInformation, StandardProcessing)

If FormType = "ObjectForm" And Parameters.Key.Type = Enums.GoodsTypes.Service Then

SelectedForm = Metadata.Catalogs.Goods.Forms.ServiceForm;
StandardProcessing = False;

EndIf;

EndProcedure

This handler should be placed in  the Nomenclature catalog manager module.
NOTE
The FormReceiveProcessing handler is  not called if you try to open common
forms, constant forms, settings storage forms, external reports and external pro-
cessings.
1-428 1C:Enterprise 8.3. Developer Guide

7.8.3. Modification of Form Elements Properties

While you work with a  form you might want to modify certain properties of form
elements, e.g., their availability.
To do this, use the Items collection. This  collection grants you access to the list of
all form elements (regardless of their hierarchy).
You can access the items hierarchy using the Parent and ChildItems properties
(for group, table and form elements).
Thus, you can make the form's Driver form element unavailable using the code
below:
Elements.Driver.Enabled = False;

Please note how ReadOnly, Enabled and Visible properties are specified for
elements with child items. Setting the property for the parent elements affects
all the child form elements. However, the value of the modified property in  the
element does not change. In other words, the actual value of the ReadOnly,
Enabled and Visible properties for a  specific form element is  defined based on
AND concatenation of values for these properties of all the element parents.
Assume a DocumentCurrency folder contains Currency and ExchangeRate
text boxes. If you want to make the entire group unavailable, you can use the
following code:
Elements.DocumentCurrency.Enabled = False;

TIP
When you modify form elements properties programmatically, please avoid
unjustified modification of the properties that have the following message
in  the Syntax Assistant: Calling the server is  required on client property modification.
It  slows down form performance and requires extra requests to the server.

NOTE
If changing a  form element changes the control location in  the form (e.g., when
form control visibility is  modified), different event handlers can be called related
to element activation (e.g., the OnActivateRow event will be called for a  table).
If you change the View property programmatically for a form element with an
extension (field, table, group or decoration), a  new form element extension will be
created. Form element properties related to the extension are set to default values
and not propagated from the element extension modified before the View property
was changed.
NOTE
Note that form element properties related to data being displayed (e.g., DataPath,
TitleDataPath, etc.) can be modified only for new form elements and after the
form control view has been changed.
Chapter 7. Forms 1-429

7.8.4. Form Modification

You can modify a  form programmatically. The  following items can be modified
(created, changed or deleted):
„„ Form attributes
„„ Local form commands
„„ Form elements
NOTE
You can only delete the objects created programmatically.
Below is  a general outline of how you can work with a  form programmatically:
„„ Change the contents of the form attributes
„„ Change the contents of the form commands
„„ Change the contents of the form elements
Please note that addition, change or deletion of the form components can only be
performed on the server. It  is  worth noting that the form program model is  not
affected by the form user settings and functional options.
When the user sets up custom settings, they apply to the currently displayed
form (with regard to the form's program modifications). If a  user adds any form
elements, accessing these elements from the 1C:Enterprise script is  not available.
You should remember this also when developing user interaction mechanisms.
Thus, for example, if a user adds a page to a  Page-type Group form element,
when users open this page the CurrentPage property will be set to Undefined.
The  CurrentControl property of the form will also be set to Undefined if the
active control is  the user-defined element.
All the form modification steps are reviewed in  detail below.

7.8.4.1. Change of Attribute Set

You can use the ChangeAttributes() method of the ManagedForm object
to change (add or delete) attributes. In this case addition and deletions opera-
tions are included into a  single call. Therefore, you can change properties of the
form's attributes. Please note that attribute contents change is  a resource-intensive
operation (it comprises a  complete form creation operation); this is  why attribute
contents change operations are usually batch-based.
Review a  detailed description of attribute creation methods.
First, you need to create the required number of FormAttribute objects. When
an attribute is  created, you should indicate its name, type and position in  the form
attribute hierarchy (see page 1-362).
1-430 1C:Enterprise 8.3. Developer Guide

Thus, to create a  value table comprising two columns, you can use the following
program code:
MyAttributes = New Array;
MyAttributes.Add(New FormAttribute("DataTable",
New TypeDescription("ValueTable"),
,
"Value table",
False));
MyAttributes.Add(New FormAttribute("Vendor",
New TypeDescription("CatalogRef.Contractors"),
"DataTable",
"Vendor organization",
False));
MyAttributes.Add(New FormAttribute("Product",
New TypeDescription("CatalogRef.Goods"),
"DataTable",
"Product name",
False));

Please note that for the last two attributes the last but one parameter specifies the
attribute for which columns are created. In  other words, you can add columns for
the attribute types that allow it.
Fig. 177 shows attributes created in  the form editor using the code above.

Fig. 177.  Program Code Equivalent

After you have created all the required attributes in  the form, you have to modify
the attribute list:
ChangeAttributes(AddedAttributes, DeletedAttributes);

When this code is executed, the system first deletes the attributes listed in the
DeletedAttributes array and then adds the attributes from the AddedAttrib-
utes array. After this the form is  rebuilt.
When attributes are deleted, data they contain are lost; however, if the added and
deleted attributes have compatible types or the added attribute differs from the
deleted attribute by properties only (not the type), the data stored in  the attribute
are preserved.
After the attribute is  added, it  can only be included in  the program code using the
ThisObject.AttributeName construct. The  ThisObject. expression is  manda-
tory for attributes added programmatically.
Chapter 7. Forms 1-431

If you want to change the contents or properties of the attributes, you should first
obtain the attributes to be modified. To do this, you can use the GetAttributes()
method.
Please note that the obtained list has two special characteristics:
„„ This list is  not dynamic; it  does not track the attribute changes that take place
after the method is  called;
„„ Although you can modify the obtained list, the changes you make have no effect
on the real properties of the form attributes.
After you obtain the form attribute list you want, you can perform actions with the
attributes (e.g., modify their titles) and then run the attribute modification method.
Attribute changes should be preceded by their deletion.
For example, if you want to change the properties of the OrderParameter
attribute, you should use the following code:
AttributeArray = GetAttributes("OrderParameter");

...
// Modify the attribute
...

DeletedAttributes = New Array;

DeletedAttributes.Add("OrderParameter");

ChangeAttributes(AttributeArray, DeletedAttributes);

7.8.4.2. Change of Command Set

To manage the form's set of commands, use a  special Commands collection of the
ManagedForm object. This  collection can be used to add, delete and change the
form's commands.
Thus, if you want to add a  StatusSettingCommand with the Set status title that
must be called by a  handler named ProgramCommandHandler, run the following
program code:
&AtServer
Procedure OnCreateAtServer(Cancel, StandardProcessing)

Command = Commands.Add("StatusSettingCommand");
Command.Action = "ProgramCommandHandler";
Command.Title = "Set status";

EndProcedure

&AtClient
Procedure ProgramCommandHandler(Command)
EndProcedure
1-432 1C:Enterprise 8.3. Developer Guide

The command handler must exist in  the form module and must be preceded by the
&AtClient compiler directive.
NOTE
A single handler can be used for multiple commands added programmatically.

7.8.4.3. Work with Form Elements

After all the required attributes and commands are created, you can start to add
controls.
To manage form elements, you can use the Items collection of the ManagedForm
collection. The  latter can be used to add, delete and change properties of the form
elements and move form elements between parents.
Using the Items collection you can access a  list of form elements that does not
account for the possible elements hierarchy. If you need to work with the hierarchy,
you can use two properties of the Items collection: Parent and ChildItems.
The first property specifies the parent form element, e.g., the Parent property for
a  form field included in  a group specifies a  FormGroup form element.
The ChildItems property exists for the form elements that can have child items.
For example, the ChildItems collection for a FormGroup form element will
include the items from this group.
If you want to move an element between collections (e.g., between groups), you can
use the Move() method. Parameters of this method describe the item to be moved,
the new parent of the item and the form element that must follow the moved item.
If the last parameter of the method is  not specified, the moved item is  added to the
end of the new parent item collection.
NOTE
When form element content is  changed programmatically, different event han-
dlers can be called related to element activation (e.g., the OnActivateRow event
will be called for a  table).
Review the control addition method in  details.
The example below demonstrates how you can add two elements to a  form:
„„ A form field associated with a  form attribute;
„„ A button associated with a  form command.

&AtServer
Procedure OnCreateAtServer(Cancel, StandardProcessing)

MyAttributes = New Array;

TypeString = New TypeDescription("String",

,
New StringQualifiers());
Chapter 7. Forms 1-433

MyAttributes.Add(New FormAttribute("ObjectDescription",
TypeString,
"",
"Object Description", False));
ChangeAttributes(MyAttributes);

Command = Commands.Add("ChangeRow");
Command.Action = "ProgramCommandHandler";
Command.Title = "Change row";

Item = Items.Add("ObjectDescription", Type("FormField"));

Item.Type= FormFieldType.InputField;
Item.DataPath = "ObjectDescription";

Item = Items.Add("ChangeRow", Type("FormButton"));

Item.CommandName = "ChangeRow";

EndProcedure

...

&AtClient
Procedure ProgramCommandHandler(Command)

ThisForm.ObjectDescription = "Command-generated object description";

EndProcedure

The form where this code is  added will look as shown on fig. 178. This is the
form view after the user clicks the Change row button.

Fig. 178.  Result of Program Form Modification

7.8.5. Working with Dynamic Lists

This section provides examples of some operations related to a dynamic list
located in  a form.
NOTE
The examples given below are not exhaustive. They only demonstrate various
methods of working with dynamic lists.
1-434 1C:Enterprise 8.3. Developer Guide

7.8.5.1. The Dynamic List Query Parameter

This example shows how to set a  dynamic list query parameter.
Assume that the following data query is  specified for a  dynamic list:
SELECT
Goods.Code As Code,
Goods.Description As Description,
Goods.SKU As SKU,
InventoryBalance.QuantityBalance As Quantity,
GoodsPricesSliceLast.Price As Price,
Goods.IsFolder
FROM
Catalog.Goods As Goods
LEFT JOIN AccumulationRegister.Inventory.Balance(, Warehouse = &Warehouse) As
InventoryBalance
BY (InventoryBalance.GoodsItem = Goods.Ref)
LEFT JOIN InformationRegister.GoodsPrices.SliceLast(, PriceType = &PriceType) As
GoodsPricesSliceLast
BY Goods.Ref = GoodsPricesSliceLast.GoodsItem

EndProcedure

Then, to set this query parameter you should (in the OnCreateAtServer()
handler) specify the Warehouse and PriceType parameters as follows:
// ItemsList – form attribute of DynamicList type
// Parameters.Warehouse and Parameters.PriceType – form parameters of corresponding types
&AtServer
Procedure OnCreateAtServer(Cancel, StandardProcessing)

ItemsList.Parameters.SetParameterValue("Warehouse", Parameters.Warehouse);
ItemsList.Parameters.SetParameterValue("PriceType", Parameters.PriceType);

EndProcedure

7.8.5.2. Filter
This section provides examples that show you how to set and delete filters in  a
dynamic list.

Setting
The function adds a  filter to a  dynamic list and returns the filter item created.
Function AddFilter(FiltersList, FieldName, Value, ComparisonType = Undefined, Use = True)

NewItem = FiltersList.Items.Add(Type("DataCompositionFilterItem"));
NewItem.LeftValue = New DataCompositionField(FieldName);
NewItem.ComparisonType = ?(ComparisonType = Undefined,
Chapter 7. Forms 1-435

DataCompositionComparisonType.Equal, ComparisonType);
NewItem.RightValue = Value;
NewItem.Use = Use;

Return NewItem;

EndFunction

Usage example:
// DynamicList – form attribute of "DynamicList" type
// The  "Contractor" column should be in  the list

// Sets a  filter by the "Contractor" field , filter value

// is  located in  the "ContractorRef" variable, filter is  enabled,
// filter condition – equal.
AddFilter(DynamicList.SettingsComposer.FixedSettings.Filter, "Contractor", ContractorRef);

Deleting
This procedure deletes a  dynamic list filter and returns the deletion result. If a  field
name with the filter being removed is  not specified, the filter list is  cleared.
Function DeleteFilter(FiltersList, FieldName = "")

If IsEmptyString(FieldName) Then

FiltersList.Items.Clear();
Return True;

EndIf;

Field = New DataCompositionField(FieldName);

FilterDeleted = False;
For Each FilterItem In  FiltersList.Items Do

If FilterItem.Use And FilterItem.LeftValue = Field Then

FiltersList.Items.Delete(FilterItem);
FilterDeleted = True;

EndIf;

EndDo;

Return FilterDeleted;

EndFunction
1-436 1C:Enterprise 8.3. Developer Guide

Usage example:
// DynamicList – form attribute of "DynamicList" type
// The  "Contractor" column should be in  the list

// The  filter by "Contractor".field is  deleted

Result = DeleteFilter(DynamicList.SettingsComposer.FixedSettings.Filter, "Contractor");

7.8.5.3. Group
This section provides examples that show how to set and delete groups in a
dynamic list.

Setting
This function adds a  group to a  dynamic list and returns the group item created.
Function AddGroup(GroupList, FieldName, Use = True, GroupType = Undefined)

Field = New DataCompositionField(FieldName);

NewItem = GroupList.Items.Add(Type("DataCompositionGroupField"));
NewItem.Use = Use;
NewItem.Field = Field;
NewItem.GroupType = ?(GroupType = Undefined, DataCompositionGroupType.Items, GroupType);

Return NewItem;

EndFunction

Usage example:
// DynamicList – form attribute of "DynamicList" type
// The  "Contractor" column should be in  the list
//
// The  group by field "Contractor" is  created, the created
// group will be used, group type – only items
AddGroup(DynamicList.SettingsComposer.FixedSettings.Group, "Contractor");

Deleting
This procedure deletes a dynamic list group and returns the deletion result.
If a field name with the group being removed is not specified, the group list
is cleared.
Function DeleteGroup(GroupList, FieldName = "")

If IsBlankString(FieldName) Then

GroupList.Items.Clear();
Return True;
Chapter 7. Forms 1-437

EndIf;

Field = New DataCompositionField(FieldName);

GroupDeleted = False;
ItemsToDeleteArray = New Array;

For Each GroupItem In  GroupList.Items Do

If GroupItem.Field = Field Then

ItemsToDeleteArray.Add(GroupItem);

EndIf;

EndDo;

For Each ItemToDelete In  ItemsToDeleteArray Do

GroupList.Items.Delete(ItemToDelete);
GroupDeleted = True;

EndDo;

Return GroupDeleted;

EndFunction

Usage example:
// DynamicList – form attribute of "DynamicList" type
//
// Deletes all groups in  the dynamic list
Result = DeleteGroup(DynamicList.SettingsComposer.FixedSettings.Group);

7.8.5.4. Order (sorting)

This section provides examples of how to set and delete sortings in  a dynamic list.

Setting
This function adds a sorting field to a dynamic list and returns the order item
created.
Function AddOrder(OrdersList, FieldName, Use = True, OrderType = Undefined)

Field = New DataCompositionField(Field);

NewItem = OrdersList.Items.Add(Type("DataCompositionOrderItem"));
NewItem.Use = Use;
NewItem.Field = Field;
1-438 1C:Enterprise 8.3. Developer Guide

NewItem.OrderType = ?(OrderType = Undefined, DataCompositionSortDirection.Asc, OrderType);

Return NewItem;

EndFunction

Usage example:
// DynamicList – form attribute of "DynamicList" type
// The  "Description" column should be in  the list
//
// Sets sorting on field "Description",
// sorting direction – descending , sorting is  used
AddOrder(DynamicList.SettingsComposer.FixedSettings.Order, "Description", DataCompositionSortDirection.Desc);

Deleting
This procedure deletes a dynamic list sorting and returns the deletion result.
If a  sorting field name is  not specified, the order list is  cleared.
&AtClient
Function DeleteOrder(OrdersList, FieldName = "")

If IsBlankString(FieldName) Then

OrdersList.Items.Clear();
Return True;

EndIf;

Field = New DataCompositionField(FieldName);

OrderDeleted = False;
ItemsToDeleteArray = New Array;

For Each OrderingItem In  OrdersList.Items Do

If OrderingItem.Field = Field Then

ItemsToDeleteArray.Add(OrderingItem);

EndIf;

EndDo;

For Each ItemToDelete In  ItemsToDeleteArray Do

OrdersList.Items.Delete(ItemToDelete);
OrderDeleted = True;

EndDo;

Return OrderDeleted;

EndFunction
Chapter 7. Forms 1-439

Usage example:
// DynamicList – form attribute of "DynamicList" type
//
// Performs deletion (not disabling)of order by "Description" field
Result = DeleteOrder(DynamicList.SettingsComposer.FixedSettings.Order, "Description");

7.8.5.5. Conditional Appearance

This example shows how to set the dynamic list conditional appearance. The  List
dynamic list is  used in  the conditional appearance containing the Organization
and Sum fields (Number-type). The example sets three conditional appearance
items:
„„ If the Sum value is  less than 500, the Organization and Sum fields are high-
lighted in  red.
„„ If the Sum value is  more than 500 but less than 10000, the text of all row fields
is highlighted in blue.
„„ If the Sum value is  more than 10000, the Organization and Sum fields are
highlighted in  green.
The example also uses the filter setting function (see page 1-434).
Function SetConditionalAppearance(AppearanceList, CustomizedFieldsNames, AppearanceStructure, Use = True) Export

NewItem = AppearanceList.Items.Add();
NewItem.Use = Use;

// Set fields to change appearance, specified by the array of field names

For Each FieldName In  CustomizedFieldsNames Do

CustomizableField = NewItem.Fields.Items.Add();
CustomizableField.Use = True;
CustomizableField.Field = New DataCompositionField(FieldName);

EndDo;

// Set appearance specified by the structure,

// where – Key: appearance parameter name,
// and Value – appearance parameter value
For Each AppearanceItem In  AppearanceStructure Do

NewItem.Appearance.SetParameterValue(AppearanceItem.Key, AppearanceItem.Value);

EndDo;

Return NewItem;

EndFunction
1-440 1C:Enterprise 8.3. Developer Guide

An example of setting a  conditional appearance:

ConditionalAppearanceItems = List.SettingsComposer.FixedSettings.ConditionalAppearance;
CustomizableFields = New Array;
CustomizableFields.Add("Amount");
CustomizableFields.Add("Organization");

// ***** Set Red colors for the amount of less 500
Appearance = New Structure;
Appearance.Insert("TextColor", New Color(128,0,0));
NewItem = List.SetConditionalAppearance(ConditionalAppearanceItems, CustomizableFields, Appearance);

// Set condition for appearance: Amount < 500

List.AddFilter(NewItem.Filter, "Amount", 500, DataCompositionComparisonType.Less);

// ***** Set Green colors for the amount of more than 10 000
Appearance = New Structure;
Appearance.Insert("TextColor", New Color(0,128,0));
NewItem = List.SetConditionalAppearance(ConditionalAppearanceItems, CustomizableFields, Appearance);

// Set condition for appearance: Amount > 10000

List.AddFilter(NewItem.Filter, "Amount", 10000, DataCompositionComparisonType.Greater);

// Set Blue color, if the amount is  in  interval from 500 to 10 000
Appearance = New Structure;
Appearance.Insert("TextColor", New Color(0,0,128));

// Transferring empty array as list of fields to change appearance

// means changing the appearance of all fields in  a row
NewItem = List.SetConditionalAppearance(ConditionalAppearanceItems, New Array, Appearance);

// Create the "AND" conditions group

FiltersGroup = NewItem.Filter.Items.Add(Type("DataCompositionFilterItemGroup"));
FiltersGroup.GroupType = DataCompositionFilterItemsGroupType.AndGroup;

// Set appearance condition: Amount > 500 AND Amount < 10000
List.AddFilter(FiltersGroup, "Amount", 500, DataCompositionComparisonType.Greater);
List.AddFilter(FiltersGroup, "Amount", 10000, DataCompositionComparisonType.Less);
Chapter  8

WORK WITH QUERIES

A special Query object is  used by the system to generate and execute database
table queries. Query objects are convenient to use when you need to get a  complex
data selection grouped and sorted as needed. The summary of the accounting
register condition for a specific point in time is a classical example of query
use. You can also use the query mechanism to get information for different points
in time.

8.1. QUERY DATA SOURCES (TABLES)

You can use database tables as query language data sources. The  tables are divided
into two main classes: real and virtual.
Real tables are stored in  the database, i.e. are interpreted on the basis of an existing
database table. If a  real table is  used, calculated fields may be present and their
values are calculated as a  function of several real fields.
Virtual tables are not stored in  the database. When calling information from virtual
tables, the system automatically collects information from real database tables to
execute the query. A virtual table can be parameterized, i.e. real filling of a  virtual
table can be defined by values of parameters whose actual values are specified
in  the query text.
Each virtual table has a name which is used in queries for identification
purposes. The  table name can be defined in  English and Russian. For example,
Catalog.Goods. Table and field names may not be the same as query language
keywords.
The so-called object tables form a separate subclass of tables. A real database
table must be used as an object table. The  notional difference of object tables from
any other tables is  expressed in  the term itself – object tables are used to store
1C:Enterprise system object statuses, such as catalogs, documents and so on. Each
object table has a  matching object type in  the 1C:Enterprise system. For example,
1-442 1C:Enterprise 8.3. Developer Guide

one table corresponds to the objects of Catalog.Goods type, while another table
corresponds to the objects of Catalog.Contractors type. Each individual record
of an object table stores the status of an individual object of a  corresponding type.
Accordingly, each object table has a  Ref field which is  a reference to the current
record. Moreover, object tables have a  way of obtaining the user representation of
an object from the record field contents.
Object tables can also be hierarchical. Hierarchical tables have a  special Parent
field that contains a  reference to the record which, according to the hierarchy, is  a
parent of the current record.
The following can be used as table fields:
„„ A virtual or real table field
„„ A nested table.
The main difference between a  standard field and a  nested table is  that a  standard
field corresponds to a single value within a record, while a nested table corre-
sponds to a QueryResult type value with a predefined set of columns. An
example of a  nested table is  a document or catalog tabular section.
The NULL type value can be used as a table field value type. Such values are
included in  table record fields, for which the given field is  undefined or mean-
ingless. For example, values of this type are included in  the records (belonging to
catalog folders) for the fields that are defined only for the items of this catalog.

8.2. QUERY LANGUAGE

As described earlier, executing a  query requires generating query text. Query text
represents guidelines used for query execution. The  query text describes infobase
tables used as query data sources, table fields that require processing, grouping
rules, result sorting, etc.
The guidelines are composed in  a special language – query language and consist
of separate parts – sections, clauses, words, functions and comments. This  chapter
will describe functions and methods to use with all query language constructs.

8.2.1. Syntax Diagram for Query Language Constructs

This chapter describes query language syntax using a set of rules. Each rule
describes one language construct.
Each construct can contain keywords, separators (periods, commas, parentheses)
and other language constructs.
<Language Construct>
THIS_IS_KEYWORD
<This_is_language_construct>, <This_is_language_statement>
THIS_IS_FUNCTION ( <This_is_language_construct> )
Chapter 8. Work with Queries 1-443

The rules that describe the query language include language constructs enclosed
in  angle brackets. Keywords and function names are capitalized.
Language constructs can contain optional items, e.g. keywords. The rules that
describe the query language include optional items enclosed in  brackets:

[THIS_IS_OPTIONAL_WORD]
[<This_is_optional_construct>]

In some cases, alternative elements can be used in a language construct. These
elements are separated by a  vertical bar:
THIS_WORD | OR_THIS_WORD
<This_construct> | <Or_this_construct>

Descriptions of all constructs include examples explaining their order of use in  the
query language.

8.2.2. Comments in  Query Language

Query text can include comments. Comments are sections of strings, beginning
with the a  sequence of // characters and continuing to the end of the string:
// This  is  a comment

Comments are ignored when executing the query.

NOTE
The query wizard removes comments from the text.

8.2.3. Use of Predefined Configuration Data

Query text can contain the following predefined configuration data:
„„ enumeration values
„„ predefined data for:
○○ catalogs
○○ charts of characteristic types
○○ charts of accounts
○○ charts of calculation types
„„ empty references
„„ business process route point values
The query text can also contain system enumeration values which can be assigned
to fields in the database tables: AccumulationRecordType, AccountType and
AccountingRecordType.
1-444 1C:Enterprise 8.3. Developer Guide

Predefined configuration data and system enumeration values can be referenced

in  queries using literals of functional type:
VALUE(<ValuePresentation>)

For system enumerations, the value presentation looks like the following:
<SystemEnumName>.<Value>

Valid names of system enumerations are listed above. The  list of allowable values
is  given in  each description.
For predefined configuration data, the value presentation looks like the following:
<PredefinedValueType>.<MetadataObjectName>.<Value>

Predefined values can have one of the following types:

„„ Catalog
„„ ChartOfCharacteristicTypes
„„ ChartOfAccounts
„„ ChartOfCalculationTypes
„„ Enum
The name of a  metadata object matches the name indicated in  the Designer.
For enumerations defined in  the configuration, the value is  specified as the name
of the corresponding metadata object of the EnumValue type. For other types of
predefined values, the value is  specified as a  predefined data item name indicated
in  the Designer or as EmptyRef (specifies an empty reference).
For business process route points, the value presentation looks like the following:
BusinessProcess.<MetadataObjectName>.RoutePoint.<RoutePointName>

Some fragments of queries explaining the use of predefined data in queries are
given below:
WHERE City = VALUE(Catalog.Cities.Moscow)

WHERE City = VALUE(Catalog.Cities.EmptyRef)

WHERE ProductType = VALUE(Enum.ProductTypes.Service)

WHERE RecordType = VALUE(AccumulationRecordType.Receipt)

WHERE RoutePoint = VALUE(BusinessProcess.Match.RoutePoint.Accept)

Chapter 8. Work with Queries 1-445

8.2.4. Query language keywords

The list below provides query language keywords.
AUTOORDER MAX AUTOORDER MAX
BOOLEAN BETWEEN BOOLEAN BETWEEN
IN MONTH IN MONTH
OUTER MIN OUTER MIN
INNER MINUTE INNER MINUTE
ASC BEGINOFPERIOD ASC BEGINOFPERIOD
ALL NOT ALL NOT
CASE WEEK CASE WEEK
SELECT UNDEFINED SELECT UNDEFINED
CAST OVERALL CAST OVERALL
WHERE UNION WHERE UNION
YEAR TOP YEAR TOP
DATE PERIODS DATE PERIODS
DATETIME LIKE DATETIME LIKE
TENDAYS FULL TENDAYS FULL
DAY HALFYEAR DAY HALFYEAR
DAYOFYEAR INTO DAYOFYEAR INTO
WEEKDAY RIGHT WEEKDAY RIGHT
FOR UPDATE [OF] PRESENTATION FOR UPDATE [OF] PRESENTATION
DATEADD EMPTYTABLE DATEADD EMPTYTABLE
IS DISTINCT IS DISTINCT
ISNULL ALLOWED ISNULL ALLOWED
VALUE GROUP BY VALUE GROUP BY
AND SECOND AND SECOND
HIERARCHY JOIN … ON HIERARCHY JOIN … ON
HIERARCHY ESCAPE HIERARCHY ESCAPE
FROM SUBSTRING FROM SUBSTRING
OR SECOND OR SECOND
HAVING AVG HAVING AVG
ELSE REFS ELSE REFS
INDEX BY STRING INDEX BY STRING
TRUE SUM TRUE SUM
TOTALS … BY TYPE TOTALS … BY TYPE
AS VALUETYPE AS VALUETYPE
QUARTER THEN QUARTER THEN
WHEN ONLY WHEN ONLY
COUNT DESC COUNT DESC
ENDOFPERIOD ORDER BY ENDOFPERIOD ORDER BY
END HOUR END HOUR
LEFT NUMBER LEFT NUMBER
FALSE DROP FALSE DROP

NOTE
Keyword names are not case sensitive.
1-446 1C:Enterprise 8.3. Developer Guide

8.2.5. Main Sections of Query Text

You can describe the query text using the following rule:
<Query text>
<Query description>
[<Query union>]
[<Results ordering>]
[AUTOORDER]
[<Totals description>]

As you can see from this rule, the query text consists of several parts or sections:
„„ <Query description> – this is  the only required section in  the query text and
in  many cases this is  all you need. The  section describes query data sources,
selection fields, groups, etc. In  its turn, it  is  described by a  whole set of rules
as explained below.
„„ <Query union> – the query language allows you to consolidate the results of
several queries. For a  description of the query union see page 1-463.
„„ The <Results ordering> section helps define the string ordering conditions
in  the query result. For a  description of query result ordering see page 1-464.
„„ AUTOORDER allows you to include automatic ordering string mode in  the query
result. For a  description of this mode see page 1-467.
„„ The <Totals description> section lets you specify what totals must be calculated
in  the query. For a  description of this section see page 1-468.

8.2.6. Query Description

As was earlier noted, a  query description section must be included in  the query
text, defining the following:
„„ fields to be included in  the query result
„„ query data sources – source tables
„„ conditions affecting data selection in  the query
„„ order for groups of query results
The query description section consists of several interrelated clauses:
<Query description>
SELECT [ALLOWED] [DISTINCT] [TOP <Count>]
<List of selection fields>
[FROM <Source list>]
[WHERE <Filter criterion>]
[GROUP BY <Group fields>]
[HAVING <Filter criterion>]
[FOR UPDATE [<Top level tables list>]]
Chapter 8. Work with Queries 1-447

The query begins with the required SELECT keyword.

The ALLOWED keyword means that the query selects only those records for which
the current user has rights. If you do not indicate this keyword, the query selects
records for which the user does not have rights and an error occurs. This  keyword
can only be present in  the top-level SELECT clause and is  applied throughout the
entire query, including the nested queries.
Using the DISTINCT keyword, you can indicate that duplicate strings must not be
included in  the result.
The TOP <Count> clause allows you to give the maximum number of rows in  the
query result. The first rows will be shown (according to the ordering rules for
query results). The  Count value should be an integer. You can also use the query
language to order nested queries if they contain the TOP statement.
The <List of selection fields> section describes the fields which must be
included in  the query result (for rules of selection field description see page 1-450).
The FROM <Source list> clause indicates the data sources, i.e. infobase tables
processed in  the query. You can omit the source description only if the sources
are completely defined in  the list of selection fields (for rules of query data source
description see page 1-453).
The WHERE <Filter criterion> clause allows you to filter off the query results.
Records are only included in  the result if this clause is  true for them (for rules of
filter criteria description see page 1-460).
You can use the FOR UPDATE clause to indicate the need to lock the data which
you read during the transaction. These data become inaccessible for other sessions.
In  the file mode version, the specified tables are locked, while in  the client/server
mode the lock is  only applied to the selected records. The  lock is  released after
the transaction is  completed.
The GROUP clause allows you to describe the order of query result grouping (see
page 1-461).
The HAVING clause allows you to apply conditions to group results (see page 1-462).
All the examples in  this chapter contain query text and query result. It  is  implied
that the query text is passed to the Execute() method of the Query object as
a parameter.
The following is a simple example of a query consisting of a single SELECT
operator and a  list of selection fields.
Example:
// A list of consignment notes must be added to the report.

Select
Document.Invoice.Ref
1-448 1C:Enterprise 8.3. Developer Guide

Result:

Fig. 179.  Query Result

8.2.6.1. Using DISTINCT Keyword

In many situations it  is  desirable not to include duplicate rows in  a report.
Example:
// It  is  necessary to find out to what contractors
// the goods were shipped in  a particular period.

Select
Document.Invoice.Contractor

Result:

Fig. 180.  Query Result

Chapter 8. Work with Queries 1-449

As you can see, there are many duplicate lines in the query result, reducing its
clarity. To prevent repetition, you can use the DISTINCT keyword in the query
description.
Example:
Select Distinct
Document.Invoice.Contractor

Result:

Fig. 181.  Query Result

8.2.6.2. Using TOP Keyword

Sometimes you need to limit the count of rows in  a report. To accomplish this you
must specify the TOP keyword in  the query description, followed by the required
count of rows.
Example:
// You want to select five most expensive goods.
// Selection must be in  the descending order of goods price.

Select Top 5
Catalog.Nomenclature.Description,
Catalog.Nomenclature.PurchasePurchasePrice

Order by
Catalog.Nomenclature.PurchasePurchasePrice Desc

Result:

Fig. 182.  Query Result

1-450 1C:Enterprise 8.3. Developer Guide

8.2.7. Selection Fields Description

A list of selection fields is  given after the required SELECT keyword (and clarifying
words DISTINCT and TOP) in  the query text. These fields will be processed when
selecting data in the query. The query result will also have a field set defined
in  this list. Selection fields are described as follows:
<List of selection fields>
<Selection field>[, <Selection field>[, …]] | *

<Selection field>
<<Field description>> [[AS] <Field alias>]

<Field description>
<Expression>[.<Fields group>]|<Empty table description>

<Empty table description>

EMPTYTABLE.(<Aliases list>)

<Aliases List>
[<Field alias>][,<Aliases list>]

The selection field list consists of one or more comma-separated items. Each selec-
tion field consists of the selection field description and an optional field alias.
Instead of fields listing, you can use an asterisk (*) in  the selection list. It  means
that the query result should contain all fields that exist in  the query's source tables
(data sources) included in  the list of sources.
NOTE 1
When using an asterisk (*) in  the selection fields list, the result will not include
virtual fields of the source tables.
NOTE 2
Retrieval of large selections (more than 64 MB) requires sufficient free space on
the hard drive used to store the server and client's temporary files.
Field description describes how field values must be generated. In the simplest
case, a  selection field is  a reference to a  field in  the source table. The  reference
can include specification of the table containing this field or it can be defined
without specifying the table. For information about dereferencing fields see page
1-474.
In general, a  selection field can represent an expression, rather than just a  source
table field reference (for details see page 1-470).
Chapter 8. Work with Queries 1-451

Query results can be grouped (see page 1-461) using aggregate functions (see page
1-474) specified in  the selection fields as expressions.
You can assign an alias to any selection field (see page 1-451). You can use the
field alias for easy access to the field.
You can use fields group only when the selection field references a  nested table
(see page 1-452). In  this case you can define which fields must be processed in  the
selection from the nested table. If the fields group is omitted, all fields of the
nested table are processed.

8.2.7.1. Field Aliases in  the Selection List

If you assign an alias to a  selection field, then you can access this field, using its
alias, in  the ORDER BY and TOTALS clauses as well as when working with query
results. This  can be more convenient and in  some cases it  is  the only option.
The AS keyword can precede the field alias. You can omit this word, but when
indicated it  improves the clarity and readability of the query text.
Field aliases are defined according to the rules of variable identifier assignment.
Aliases in  a query cannot be the same.
Assigning aliases does not affect data selection in  the query.
Example:
// You want to select
// product and group names from the Goods catalog.

Select
Catalog.Nomenclature.Name AS Product,
Catalog.Nomenclature.Parent.Name As Group
From
Catalog.Nomenclature

Result:

Fig. 183.  Query Result (Fragment)

1-452 1C:Enterprise 8.3. Developer Guide

Please note that fields in  the query result are named Product and Group. If you
did not specify field aliases, the fields in  the query result would be named Name
and Name1 (field names in  the query result cannot be same, therefore 1 is  auto-
matically added to the second field name) which is  much less convenient.

8.2.7.2. Nested Tables in  the Selection Fields List

A field in  the selection list can refer to nested tables of query data sources. In  this
case the field in the query result will have the QueryResult type, containing
a  nested query result, generated based on the nested source table.
By default, all fields of the nested table (data source) are included in  the nested
result. You can overtly define field groups which must be included in  the nested
query result. The  group of nested result fields is  described by the following rules:
<Fields group>
( <List of nested fields> ) | *

<List of nested fields>

<Nested field>[, <Nested field>[, …]]

<Nested field>
<Expression> [[AS] <Field alias>]

A list of nested fields consists of one or more comma-separated items. If the list
consists of one item, then it  does not need to be enclosed in  parentheses.
Instead of nested fields listing, you can use an asterisk ("*"); this means that the
nested query result must contain all fields of the nested table.
A nested field can represent an expression (see page 1-473). In  the simplest case an
expression is  a reference to the nested table field.
Each nested field can have an alias. Like the field aliases of the selection list, these
field aliases can be used to access the fields more conveniently (see page 1-451).
You can assign aliases to nested fields regardless of whether or not the alias of the
nested table itself is  given.
Example:
// Consignment note specifications (the document, assortment and //quantity) must be added to the report.

Select
Document.Invoice.Ref,
Document.Invoice.Contents.(Nomenclature As Product, Count)
Chapter 8. Work with Queries 1-453

Result:

Fig. 184.  Query Result (Fragment)

Please note that the Content field in  the query result appears as a  nested table
with Nomenclature and Count fields.

8.2.7.3. Empty Nested Tables in  the Selection List

If the query contains a  union and some parts of the union include nested tables,
while others do not, it  is  necessary to add empty nested tables to the selection list
fields. Use the EMPTYTABLE keyword followed by the field aliases in  parentheses;
these fields will make up the nested table.
Example:
SELECT Ref.Number, EMPTYTABLE.(Number, Article, Quantity) AS Content
FROM Document.Invoice
UNION ALL
SELECT Ref.Number, Content.(LineNumber, Nomenclature, Quantity)
FROM Document.Invoice

8.2.8. Query Sources Description

The purpose of the FROM clause is  to designate a  list of source tables (data sources)
used in  the SELECT operator.
The FROM clause is optional in the query language. It can be omitted if data
sources are fully qualified in  the description of the selection fields list specified
in the SELECT clause. Please note that the set of examples in  the previous sections
did not contain the FROM clause.
1-454 1C:Enterprise 8.3. Developer Guide

The FROM keyword is followed by the source list. Generally, the source list
is  described by the following set of rules:
<Source list>
<Source>[, <Source>[, …]]

<Source>
<Source description> [ <Joining list> ]

<Source description>
<Table> [[AS] <Source alias>]

<Table>
<Table name>[(<Parameters>)] | ( <Query description> )

Query data sources are listed in  the list of sources (comma-separated). Each source
in  the list must include a  description; additionally you can indicate a  joining list –
rules for joining a  source with other sources. For a  description of join specification
see page 1-454.
If you use an infobase table as a data source, the source description contains
a  table name.
If the source table is virtual, then you can indicate its formation parameters.
For a detailed description of virtual table parameters, see Script  – Working with
Queries – Query tables in  the built-in help.
You can also use a  nested query as a  query data source. In  this case the source
description contains a  description of the query. For a  description of nested queries
see page 1-460.
The data source description can also contain a  source alias. The  alias can be used
to access this source more conveniently.

8.2.8.1. Join Specifications

When defining several sources in the source list, there is a selection from the
second source table for each record from the first source table and so on. This  way,
all possible combinations of all records from all specified sources are included
in  the query result.
Example:
SELECT
Contractors.Ref as Contractor,
PriceTypes.Ref AS PriceType
FROM
Catalog.Contractors AS Contractors,
Catalog.PriceTypes AS PriceTypesResult
Chapter 8. Work with Queries 1-455

Result:

Fig. 185.  Query Result (Fragment)

The query result contains combinations of all contractors with all price types.
This  result does not have meaning on its own. Usually, combinations of records
from different source tables must be limited by certain conditions. In the query
language you can describe a  joining of sources, by indicating the sources them-
selves and defining conditions by which record combinations are included in  the
query result.
There are different ways of joining; these are described by the following rules:
<Joining list>
<Join> [<Joining list>]

<Join>
[INNER] JOIN <Source description> BY <Filter criterion> |
LEFT [OUTER] JOIN <Source description> BY <Filter criterion> |
RIGHT [OUTER] JOIN <Source description> BY <Filter criterion> |
FULL [OUTER] JOIN <Source description> BY <Filter criterion>

Generally, a  joining list can contain and describe a  single join (two sources) or
multiple joins of multiple sources.
Source description contains a  description of the source table (see page 1-453).
Filter criterion contains conditions used to join data from the query source tables
in  the selection. For information about rules of condition description in  the query
language see page 1-488.
The LEFT, RIGHT and FULL keywords specify the nature of the join. INNER and
OUTER are optional; they improve the clarity and readability of the query text.
Joined sources are not equal and in  some cases the result depends on which table
is  indicated first, before the JOIN keyword (to the left) and which is  second (to the
right of the keyword).
1-456 1C:Enterprise 8.3. Developer Guide

Two simple tables can be used to describe the joins. One of the tables is  named
Companies, consists of two fields (Name and Telephone Number) and contains
the following data:

Fig. 186.  Companies Table

The other table is  named Contacts, consists of three fields (Name, Telephone
Number and Company), the latter being a  reference to a  Companies table item.
The  table contains the following data:

Fig. 187.  Contacts Table

NOTE
In 1C:Enterprise terms, both tables are catalogs.

Inner Join
An inner join means that only record combinations meeting the specified condi-
tion from both initial data source tables must be included in the query result.
The  remaining records are not included in  the result.
Example:
SELECT
Companies.Name AS Company,
Contacts.Name AS Contact
FROM
Catalog.Contacts AS Contacts
INNER JOIN Catalog.Companies AS Companies
BY Contacts.Company = Companies.Ref

Result:

Fig. 188.  Query Result

Chapter 8. Work with Queries 1-457

Left Outer Join

A left outer join means that record combinations from both source tables meeting
the specified criterion must be included in  the query result. However, as opposed
to inner joining, records from the first source (indicated on the left of the JOIN
keyword) without corresponding records from the second source must also be
included in  the query result.
This way, all records from the first source will be included in the query result;
these will be joined with the records from the second source when executing the
specified condition. Query result strings without the corresponding record from the
second source will contain NULL in  the fields based on the records from this source.
Example:
SELECT
Contacts.Name AS Contact,
Companies.Name AS Company
FROM
Catalog.Contacts AS Contacts
LEFT JOIN Catalog.Companies AS Companies
BY Contacts.Company = Companies.Ref

Result:

Fig. 189.  Query Result

Right Outer Join

A right outer join means that record combinations from both source tables meeting
the specified criterion must be included in  the query result. Additionally records
from the second source (indicated on the right of the JOIN keyword) without the
corresponding records from the first source must be included in  the query result.
Therefore, all records from the second source will be included in  the query result;
these will be joined with the records from the first source which meet the specified
condition. Query result strings without the corresponding records from the first
source will contain NULL in  the fields based on the records from this source.
NOTE
In practice, the right outer join can be cast to the left outer join. This  is  exactly
what the Designer's query wizard does.
1-458 1C:Enterprise 8.3. Developer Guide

Example:
SELECT
Contacts.Name AS Contact,
Companies.Name AS Company
FROM
Catalog.Contacts AS Contacts
RIGHT JOIN Catalog.Companies AS Companies
BY Contacts.TelephoneNumber = Companies.TelephoneNumber

Result:

Fig. 190.  Query Result

Full Outer Join

A full outer join means that record combinations from both source tables meeting
the specified criterion must be included in  the query result. Additionally records
without matches from both sources must also be included in  the query result.
Therefore, all records from both sources will be included in  the query result; these
will be joined with each other if the specified condition is  met. Query result strings
without the corresponding records from any source will contain NULL in  the fields
based on the records from this source.
Example:
SELECT
Contacts.Name AS Contact,
Companies.Name AS Company
FROM
Catalog.Companies AS Companies
FULL JOIN Catalog.Contacts AS Contacts
BY (Contacts.TelephoneNumber = Companies.TelephoneNumber)

Result:

Fig. 191.  Query Result

8.2.8.2. Data Source Aliases

If you assign an alias to a  data source, you will be able to access this source using
the alias in  the future (and you will not be able to access it  by the table name).
This  can be more convenient and in  some cases it  is  the only option.
Chapter 8. Work with Queries 1-459

Aliases are defined according to rules of variable identifier assignment. Aliases

in  a query cannot be the same.
The AS keyword can precede the source alias. You can omit this word, but when
indicated it  improves the clarity and readability of the query text.
Assigning source aliases in  itself does not affect data selection in  the query.
Example:
SELECT
Product.Name,
Product.Parent
FROM
Catalog.Nomenclature AS Product

This example demonstrates the use of the Product alias assigned to the Catalog.
Nomenclature source table in  the selection fields list.

8.2.8.3. Nested Tables in  the Source List

The source list can also include nested tables, i.e. tabular sections of catalogs and
documents.
Example:
// Consignment note specifications (the document, assortment and quantity)
// must be added to the report.
// The  source list includes the Content nested table –
// a  tabular section of a  consignment Note:
// The  selection is  limited to eight records to prevent overloading the example.

SELECT TOP 8
InvoiceContent.Ref,
InvoiceContent.Nomenclature,
InvoiceContent.Count
FROM
Document.Invoice.Content AS InvoiceContent

Result:

Fig. 192.  Query Result

1-460 1C:Enterprise 8.3. Developer Guide

Please note that when you indicate a nested table in the source list, you can
access both fields from the nested table and fields from the top-level table
(containing the nested table) through the Ref field. In this case you access the
Ref.FieldDescription field of the document itself.

8.2.8.4. Nested Queries in  the Source List

You can use a  nested query as a  source table in  the source list. In  this case the
source description contains a description of the nested query. A description of
a  nested query is  composed just like any other description (see page 1-446).
Using a  nested query as a  data source does not differ from using an infobase table.
All fields described in  the selection fields list of the nested query are accessible as
fields of such a  source.
Example:
SELECT
NestedSelect.Ref,
NestedSelect.Nomenclature,
NestedSelect.Count
FROM
(SELECT TOP 8
InvoiceContent.Ref AS Ref,
InvoiceContent.Nomenclature AS Nomenclature,
InvoiceContent.Count AS Count
FROM
Document.Invoice.Content AS InvoiceContent) AS NestedSelect

The result will be exactly like in  the previous example.

8.2.9. Query Result Filtration

The WHERE <Filter criterion> clause allows you to specify filter criteria for
data from the source tables (query sources); the query will only process the records
if they meet the specified condition.
Example:
// You want to know which contractors are persons.

SELECT
Contractors.Description
FROM
Catalog.Contractors AS Contractors
WHERE Contractors.Type = VALUE(Enum.ContractorTypes.Person)
Chapter 8. Work with Queries 1-461

Result:

Fig. 193.  Query Result

NOTE
The field in  the clause WHERE does not have to be entered into the selection list.
You can define a  filter criterion as a  simple logical expression or a  more complex
expression, where simple logical expressions are connected to each other by the
logical operators AND or, NOT. For a  description of criteria in  the query language
see page 1-488.

8.2.10. Query Result Groups

Source data in the query can be grouped using aggregate functions specified as
fields in  the selection list. This  means that strings in  the query result will contain
calculation results of the indicated aggregate functions, calculated (grouped) by
source table record.
Aggregate functions themselves are specified in  the selection fields list. You must
indicate the fields to be used for grouping in  the GROUP BY <Grouping fields>
clause. Source table records containing similar values for the specified fields, will
be grouped in  the query.
The grouping fields list contains references to comma-separated source table fields
(query sources):
<Grouping fields>
<Dereferencing fields> [, <Dereferencing fields> [, …]]
IMPORTANT!
When grouping the query results, you must specify the aggregate functions in  the
selection fields list; additionally you can only indicate the fields used for grouping.
The only exception is  when aggregate functions are applied to nested table fields.
In  this case you can access top-level table fields in  the selection fields list, without
grouping the results by these fields.
When using aggregate functions, you do not have to specify the GROUP BY clause;
in  this case all query results will be grouped into a  single string.
1-462 1C:Enterprise 8.3. Developer Guide

Example:
// You want to obtain statistics on the product sales:
// maximum, minimum and average prices in  invoices.

Select
Invoice.Nomenclature,
Avg (Invoice.Price) As Avg,
Max (Invoice.Price) As Max,
Min (Invoice.Price) As Min,

From
Document.Invoice.Content AS Invoice

Group By
Invoice.Nomenclature

Result:

Fig. 194.  Query Result (Fragment)

8.2.11. Conditions for Aggregate Function Values

The HAVING <Filter criterion> clause allows you to apply conditions to
aggregate function values. You cannot indicate aggregate function conditions
in  other query language constructs, e.g., in  the WHERE clause.
Example:
// You want to select the goods that have had more than 20 pieces sold.

SELECT
Invoice.Nomenclature,
SUM(Invoice.Count) AS Count
FROM
Document.Invoice.Content AS Invoice

GROUP BY
Invoice.Nomenclature

HAVING
SUM(Invoice.Count) > 20
Chapter 8. Work with Queries 1-463

Result:

Fig. 195.  Query Result

IMPORTANT!
You can only use aggregate functions and fields used for grouping in  filter criteria.

8.2.12. Query Union

In the query language, you can merge several queries; in  this case records received
from each of the merged queries will be consolidated into a  single query result.
Each query in  a union gathers data independently, but operations such as ordering
results and calculating totals take place within the results of merged queries.
Query result fields will be named as described in  the selection fields list of the
first query. Selection fields from the remaining queries are mapped to the result
fields according to their order in  the selection fields list. Merged queries must have
a  similar count of fields in  the selection fields list.
If merged query selection fields have a  different type, then query result fields will
have a  composite type.
Query union is  described by the following rule:
<Query union>
UNION [ALL]
<Query description>
[<Query union>]

Query union begins with the required UNION keyword, followed by a  description
of the query to be merged with. Then you can join another query, etc.
By default, identical strings in  the query result generated by different queries are
replaced by one string. If you need to leave duplicate strings, use the ALL keyword.
Example:
SELECT
Receipt.Nomenclature AS Product,
SUM(Receipt.Count) AS Receipt,
SUM(0) AS GoodsConsumption
FROM
Document.ReceiptOfGoods.Content AS Receipt
1-464 1C:Enterprise 8.3. Developer Guide

GROUP BY
Receipt.Nomenclature

UNION

SELECT
GoodsConsumption.Nomenclature,
SUM(0),
SUM(GoodsConsumption.Count)
FROM
Document.Invoice.Content AS GoodsConsumption

GROUP BY
GoodsConsumption.Nomenclature

Result:

Fig. 196.  Query Result (Fragment)

8.2.13. Query Result Ordering

The ORDER BY clause allows you to sort lines in  the query result.
<Results ordering>
ORDER BY <Order conditions>

<Order conditions>
<Order field> [<Order>]
[, <Order field> [<Order>][, …]]

<Order field>
<Expression> <Order> ASC | DESC | HIERARCHY | HIERARCHY DESC

In the ORDER BY clause, conditions for ordering query results are separated by
comma. Selections are first ordered by the first condition, then by the second, etc.
The order condition generally can appear as an expression (see page 1-470). Lines
of the query result will be ordered by the expression values calculated for each line.
You can order values in ascending or descending order or, if the hierarchical
structure property is  set for a  table, you can use ordering by hierarchy (see page
Chapter 8. Work with Queries 1-465

1-465). You can indicate order for each field independently. For a  description of
value comparison rules see page 1-490.
Ordering condition fields do not have to be included in  the query result.
Example:
// Select five most expensive goods,
// ordering them in  descending order by their price.

SELECT TOP 5
Nomenclature.Description,
Nomenclature.PurchasePurchasePrice
FROM
Catalog.Nomenclature AS Nomenclature

ORDER BY
Nomenclature.PurchasePurchasePrice DESC

Result:

Fig. 197.  Query Result

8.2.13.1. Ordering by Hierarchy

You can order catalogs by catalog hierarchy.
Example:
SELECT
Catalog.Nomenclature.Description,
Catalog.Nomenclature.FullDescr
ORDER BY
Catalog.Nomenclature.Description Hierarchy

Result:

Fig. 198.  Query Result (Fragment)

1-466 1C:Enterprise 8.3. Developer Guide

You can only sort hierarchically by field, but not by operation: the order field must
contain a  reference to the source table field (query data source).
IMPORTANT!
It makes sense to order by hierarchy only if the catalog table is  defined as the
source, rather than some other table containing a  reference to the catalog only.

Example:
SELECT
Invoice.Contractor.Description,
Invoice.Number,
Invoice.Warehouse,
FROM
Document.Invoice AS Invoice

In this example, hierarchical ordering is  not possible, since there is  no a  link to
the catalog and folders from this catalog are not included in  the query result.
To apply ordering by hierarchy, you must link to the catalog.
Example:
SELECT
Contractors.Description AS Description,
Invoice.Number,
Invoice.Warehouse
FROM
Catalog.Contractors AS Contractors
LEFT JOIN Document.Invoice AS Invoice
BY Contractors.Ref = Invoice.Contractor
ORDER BY
Description HIERARCHY

Result:

Fig. 199.  Query Result (Fragment)

Chapter 8. Work with Queries 1-467

8.2.13.2. Ordering within Nested Tables

In the ORDER BY clause, you can define ordering conditions for records from nested
tables; moreover, they can be combined with ordering conditions from the top-level
table.
The order of table fields from one level (nested or top level) relative to each other
is  important, but the order of table fields from one level relative to another level is  not
important: ordering always takes place first by top level table, then by nested table.
Example:
// Consignment note specifications (the document, assortment and // quantity) must be added to the report.
// The  documents must be ordered by number,
// while its content must be ordered by goods names.

Select
Document.Invoice.Ref,
Dcument.Invoice.Content.(Nomenclature As Product, Count)
Order By
Document.Invoice.Number,
Document.Invoice.Content.Nomenclature.Description

8.2.14. Autoorder Results

The AUTOORDER clause allows you to enable automatic field generation for ordering
query results.
Autoorder functions according to the following principles:
„„ If the ORDER BY clause is  indicated in  the query, then each reference to a  table
located in  this clause will be replaced by fields used to sort the table by default
(for catalogs it  is  a code or description, for documents it  is  a document date).
If the field for ordering refers to a  hierarchical catalog, then hierarchical sorting
by this catalog will take place.
„„ If the ORDER BY clause is  not included in  the query, but the TOTALS clause is,
then the query result will be ordered by fields included in  the TOTALS clause
and following the BY keyword, in  the same sequence; if totals are calculated
by reference fields ordering by default sorting fields of the referenced tables
is applied.
„„ If ORDER BY and TOTALS are not included in  the query, but the GROUP BY
clause is, then the query result will be ordered by fields included in  the clause,
in  the same sequence; if grouping by reference fields is  applied, the result will
be ordered by default sorting fields of the referenced tables.
„„ If none of the aforementioned clauses (ORDER BY, TOTALS and GROUP BY)
is  included in  the query, then the result is  ordered by default sorting fields for the
tables from which data are selected, in  the order of their appearance in  the query.
1-468 1C:Enterprise 8.3. Developer Guide

8.2.15. Calculation of Query Totals

The TOTALS clause allows you to define which totals must be calculated in  the query.
In  calculating totals, aggregate functions are calculated by selection with identical
field values (check points). Totals are added to the query result as totals rows.
The totals calculation procedure is  described by the following rules:
<Totals description>
<Totals> [<Totals description>]

<Totals>
TOTALS [<List_of_totals_fields>] BY [OVERALL] <List of check points>

<List of totals_fields>
<Totals_field> [,<List_of_totals_fields> [, …]]

<Totals_field>
<Aggregate_function> | <Expression> [[AS] <Field_alias>]

<List of check points>

<Check point> [, <Check point> [, …]]

<Check point>
<Expression> [[ONLY] HIERARCHY] | [PERIODS(Second | Minute | Hour | Day | Week | Month |
Quarter | Year | TenDays| HalfYear
[,<DATE type literal> | <Parameter ID>]
[,<DATE type literal> | <Parameter ID>])] [[AS] Field alias]

The totals description begins with the required TOTALS keyword.

A list of aggregate functions contains a  list of aggregate functions (see page 1-474)
which must be calculated in  the totals.
The OVERALL keyword means that an overall totals row must be generated for the
entire query result. For a  description of overalls calculation see page 1-471.
In addition to overalls, you can also calculate totals by check points. To do this,
indicate <List of check points> after the required BY keyword. Each check
point contains an expression calculated when executing the query. Totals rows will
be calculated and added to the query result for each combination of expression
values.
If a  check point is  a reference to a  catalog, you can calculate totals by catalog
hierarchy (see page 1-469). To do this, use the HIERARCHY keyword after the refer-
ence.
Chapter 8. Work with Queries 1-469

8.2.15.1. Totals Calculation in  Nested Tables

The current program version does not support totals calculation by nested tables.

8.2.15.2. Totals by Hierarchy

You can calculate totals by hierarchy. To do so, you must indicate the HIERARCHY
keyword after the name of the field to be calculated. Totals by check points and
totals by hierarchy for check points will be calculated in  the result.
Example:
SELECT
Document.Nomenclature AS Nomenclature,
Document.Count AS Count,
Document.Ref.Number,
Document.Ref.Contractor
FROM
Document.Invoice.Content AS Document
ORDER BY
Document.Nomenclature
TOTALS
SUM(Count)
BY
Nomenclature HIERARCHY

Result:

Fig. 200.  Query Result (Fragment)

If necessary, you can calculate value totals by hierarchy only, without calculating
totals in  the check points. To do so, use the ONLY keyword before the HIERARCHY
keyword.
Example:
SELECT
Document.Nomenclature AS Nomenclature,
Document.Count AS Count,
Document.Ref.Number,
1-470 1C:Enterprise 8.3. Developer Guide

Document.Ref.Contractor
FROM
Document.Invoice.Content AS Document
ORDER BY
Document.Nomenclature
TOTALS
SUM(Count)
BY
Nomenclature ONLY HIERARCHY

Result:

Fig. 201.  Query Result (Fragment)

8.2.15.3. Date Addition

If a  Date type field is  used to calculate totals, then you can supplement results
with dates in  a specified period. To do this, use the PERIODS keyword, followed
by the period type in parentheses (Second, Minute, Hour, Day, Week, Month,
Quarter, Year, TenDays, HalfYear) and the beginning and ending dates of the
corresponding period. If the beginning and ending dates are not specified, then the
first and the last dates in  the result will be used.
Example:
// Obtain a  number of purchases for individual customers by time of
// the selected day
SELECT
ReceiptOfGoods.Contractor,
BEGINOFPERIOD(ReceiptOfGoods.Date, HOUR) AS Period,
COUNT(ReceiptOfGoods.Ref) AS PurchaseCount
FROM
Document.ReceiptOfGoods AS ReceiptOfGoods
GROUP BY
ReceiptOfGoods.Contractor,
BEGINOFPERIOD(ReceiptOfGoods.Date, HOUR)
TOTALS
SUM(PurchaseCount)
BY
Period PERIODS(MINUTE, DATETIME(2006,6,28), DATETIME(2006,6,28))
Chapter 8. Work with Queries 1-471

Result:

Fig. 202.  Query Result

This kind of presentation is possible only if all period records are used as the
dimension source in  the course of result tabbing by the Period group.

8.2.15.4. Calculation of Overalls

To calculate totals for the entire table, use the OVERALL keyword in  the TOTALS
clause. In  this case aggregate function values are calculated for all table records.
Example:
SELECT
Document.Nomenclature,
Document.Count AS Count,
Document.Ref.Number,
Document.Ref.Contractor
FROM
Document.Invoice.Content AS Document
TOTALS
SUM(Count)
BY
OVERALL

Result:

Fig. 203.  Query Result (Fragment)

1-472 1C:Enterprise 8.3. Developer Guide

8.2.15.5. Using Totals and Groups Together

If totals are used with groups and a  list of aggregate functions is  not specified for
totals, then it  will be auto-generated from aggregate fields of the selection list. If
the query contains a  union, then aggregate functions from the first query are used.
Example:
SELECT
Document.Nomenclature AS Nomenclature,
Document.Ref.Contractor AS Contractor,
SUM(Document.Count) AS Count
FROM
Document.Invoice.Content AS Document
GROUP BY
Document.Nomenclature,
Document.Ref.Contractor
TOTALS BY
Nomenclature,
Contractor

Result:

Fig. 204.  Query Result (Fragment)

8.2.15.6. Totals Aliases

You can assign aliases to totals fields (check points), for which totals are read,
to access them later using the 1C:Enterprise script. To accomplish this, you must
specify the name of the alias after the check point expression, as it  is  done in  the
selection fields list.
Example:
SELECT
Document.Nomenclature AS Nomenclature,
Document.Count AS Count,
Document.Ref.Number,
Document.Ref.Contractor
FROM
Document.Invoice.Content AS Document
Chapter 8. Work with Queries 1-473

ORDER BY
Document.Nomenclature
TOTALS
SUM(Count)
BY
Nomenclature ONLY HIERARCHY AS Goods

If an alias is  not specified, the system will provide a  unique name for the total.
In  the above example, the total will have the Goods name.

8.2.16. Expressions in  the Query Language

Expressions can be used in various query language constructs. Query language
expressions are described as follows:
<Expression>
<Dereferencing field> |
<Aggregate function> |
<Built-in function> |
<Case operation> |
<Type cast>[.<Dereferencing field>] |
<Value> |
<Expression> <Binary operation> <Expression> |
<Unary operation> <Expression> |
( <Expression> )

<Binary operation>
+ | – | * | /

<Unary operation>
–|+

In the simplest case, an expression is  a reference to a  field of the query data source
table. The  reference can include specification of the table containing this field or
it  can be defined without specifying the table. For information about dereferencing
fields see page 1-474.
Expressions in  the selection field list and in  HAVING, TOTALS or ORDER BY clauses
can be represented by aggregate functions (see page 1-474).
An expression can be a  built-in function of the query language (see page 1-477).
You can also use case operations (see page 1-485) and value type cast operations
(see page 1-486).
Expressions can include values of logical, numeric, string and other constants; query
parameter values can also be used (see page 1-487). Binary and unary operations can
be applied to values of appropriate types within expressions. Checking the divider
for zero value is  recommended when the division operation is  used.
1-474 1C:Enterprise 8.3. Developer Guide

8.2.16.1. Dereferencing Fields

In the simplest case, query language expressions appear as references to fields of
infobase tables. References are generally described by the following rules:
<Dereferencing field>
[<Table>.]<Field name>[.<Field name>[…]]

<Table>
<Table name> | <Source alias>

Dereferencing of fields begins with the name of the table containing this field. If
the field name is  unique (it exists in  only one of the tables indicated in  the source
list), the table can be omitted.
If the field has a  reference type, the query language allows you to access fields
in  the referenced table, etc. Field names are period-separated.
If a source alias is assigned to the source table in the source list, you can use
it instead of the table name in dereferencing fields of this table. Otherwise the
table name is  specified (see query data source description).

8.2.16.2. Aggregate Functions of Query Language

The query language provides aggregate functions used when grouping query results
and calculating totals. You can use aggregate functions to summarize values of
a  given parameter. The  following aggregate functions are defined:
<Aggregate function>
SUM ( <Expression> ) |
AVG ( <Expression> ) |
MIN ( <Expression> ) |
MAX ( <Expression> ) |
COUNT ( [DISTINCT] <Expression> | * )

Example:
SELECT
Invoice.Nomenclature.Description,
SUM(Invoice.Sum) AS Sum
AVG (Invoice.Sum) AS Avg,
MAX(Invoice.Sum) AS Max,
MIN(Invoice.Sum) AS Min,
COUNT(Invoice.Sum) AS Count
FROM
Document.Invoice.Content AS Invoice
Chapter 8. Work with Queries 1-475

GROUP BY
Invoice.Nomenclature,
Invoice.Nomenclature.Description
TOTALS BY
OVERALL

Result:

Fig. 205.  Query Result (Fragment)

You can use aggregate functions in the selection fields list and in the HAVING,
TOTALS or ORDER BY clauses.

SUM
Description:
This function calculates the arithmetic sum of all entries in the field value
selection.
You can only indicate fields containing a  numerical value as a  function param-
eter.
If the field cannot contain a  numerical value, then using the SUM function will
produce an error. You can apply this function to the field, only if the field can
contain numerical values (has a  composite data type). But if there is  a non-nu-
merical value among the field values (besides NULL), then an error will occur.

AVG
Description:
This function calculates the average value of all entries in  the field value selec-
tion.
You can only use references to fields containing numerical values as a  function
parameter.
If the field cannot contain a  numerical value, then using the AVG function will
produce an error. You can apply this function to the field, only if the field can
contain numerical values (has a  composite data type). But if there is  a non-nu-
merical value among the field values (besides NULL), then an error will occur.
1-476 1C:Enterprise 8.3. Developer Guide

MIN

Description:
This function calculates the minimum value of all entries in the field value
selection.
You can use references to fields that contain values of every type as a  function
parameter.
In defining the minimum value, value comparison rules are applied, as described
in  the "Value Comparison Rules" section.

MAX
Description:
This function calculates the maximum value of all entries in the field value
selection.
You can use expressions that contain values of every type as a function
parameter. It  can not be used either with expressions of ValueStorage or with
MomentInTime type, or with strings of unlimited length.
In defining the maximum value, value comparison rules are applied, as
described in  the "Value Comparison Rules" section.

COUNT
Description:
This function calculates the count of parameter values in the selection. As
opposed to other aggregate functions, you can use COUNT in  three ways:
„„ This function allows you to calculate the count of values that are not equal
to NULL in  a given field.
„„ This function allows you to calculate the count of various values that are
not equal to NULL in  a given field; To do so, you must use the DISTINCT
keyword before the field specification.
„„ This function can calculate the count of rows in  the query result. To do so,
use an asterisk ("*") as a  function parameter.
You can use references to fields that contain values of every type as a  function
parameter.
Example:
SELECT
COUNT(*) AS Total,
COUNT(DISTINCT Invoice.Nomenclature) AS Different
FROM
Document.Invoice.Content AS Invoice
Chapter 8. Work with Queries 1-477

Result:

Fig. 206.  Query Result

8.2.16.3. Built-in Functions of Query Language

Built-in functions defined in  the query language can be used in  expressions of the
selection field list (see page 1-450) and in  the filter criteria of the WHERE clause
(see page 1-460).
The following built-in functions are defined:
<Built-in function>
SUBSTRING ( <Expression>, <Value>, <Value> ) |
YEAR ( <Expression> ) |
QUARTER ( <Expression> ) |
MONTH ( <Expression> ) |
DAYOFYEAR ( <Expression> ) |
DAY ( <Expression> ) |
WEEK ( <Expression> ) |
WEEKDAY ( <Expression> ) |
HOUR ( <Expression> ) |
MINUTE ( <Expression> ) |
SECOND ( <Expression> ) |
BEGINOFPERIOD(<Expression>, Minute | Hour | Day | Week |
Month | Quarter | Year | TenDays | HalfYear) |
ENDOFPERIOD(<Expression>, Minute | Hour | Day | Week |
Month | Quarter | Year | TenDays | HalfYear) |
DATEADD(<Expression>, Minute | Hour | Day | Week |
Month | Quarter | Year | TenDays | HalfYear, <Expression>) |
DATEDIFF(<Expression>, <Expression>, Second | Minute | Hour |
Day | Month | Quarter | Year) |
VALUETYPE(<Expression>) |
PRESENTATION(<Expression>) |
ISNULL(<Expression>, <Expression>)

SUBSTRING
Description:
This function is  used to extract a  substring from a  string. This  function has
three parameters.
„„ A string that requires obtaining a  substring. It's an expression of the String
type;
„„ The position of the character where the substring is  to begin. It's a  value of
the Number type;
„„ Length of the obtained substring. It  is  a value of Number type.
1-478 1C:Enterprise 8.3. Developer Guide

If the first parameter specifies a string, the result of the function is a string
(possibly of zero length). If the first parameter specifies a  NULL value, the result
of the function is  NULL. Other values are invalid and produce an error.
Example:
SELECT TOP 8
Contractors.Description,
SUBSTRING(Contractors.Description, 3, 5) AS Substring
FROM
Catalog.Contractors AS Contractors

Result:

Fig. 207.  Query Result

YEAR
Description:
This function calculates the year number from a  value of the Date type.
The function's parameter is  an expression of the Date type.
If the parameter contains a  value of the Date type, the result of the function
is a value of the Number type. If the parameter specifies a  NULL value, the
result of the function is  NULL. Other values are invalid and produce an error.
QUARTER
Description:
This function calculates the quarter number from a value of the Date type.
The  number of the quarter is  between 1 and 4.
The function's parameter is  an expression of the Date type.
If the parameter contains a  value of the Date type, the result of the function
is a value of the Number type. If the parameter specifies a  NULL value, the
result of the function is  NULL. Other values are invalid and produce an error.

MONTH
Description:
This function calculates the month number from a value of the Date type.
The  number of the month is  between 1 and 12.
Chapter 8. Work with Queries 1-479

The function's parameter is  an expression of the Date type.

If the parameter contains a  value of the Date type, the result of the function
is a value of the Number type. If the parameter specifies a  NULL value, the
result of the function is  NULL. Other values are invalid and produce an error.

DAYOFYEAR
Description:
This function calculates the day number within a  year from a  value of the Date
type. The  number of the day is  between 1 and 366.
The function's parameter is  an expression of the Date type.
If the parameter contains a  value of the Date type, the result of the function
is a value of the Number type. If the parameter specifies a  NULL value, the
result of the function is  NULL. Other values are invalid and produce an error.

DAY
Description:
This function calculates the day number within a  month from a  value of the
Date type. The  number of the day is  between 1 and 31.
The function's parameter is  an expression of the Date type.
If the parameter contains a  value of the Date type, the result of the function
is a value of the Number type. If the parameter specifies a  NULL value, the
result of the function is  NULL. Other values are invalid and produce an error.

WEEK
Description:
This function calculates the week number within a  year from a  value of the
Date type.
The function's parameter is  an expression of the Date type.
If the parameter contains a  value of the Date type, the result of the function
is a value of the Number type. If the parameter specifies a  NULL value, the
result of the function is  NULL. Other values are invalid and produce an error.

WEEKDAY
Description:
This function calculates the day number within a week from a value of the
Date type. The  number of the day is  between 1 (Monday) and 7 (Sunday).
The function's parameter is  an expression of the Date type.
1-480 1C:Enterprise 8.3. Developer Guide

If the parameter contains a  value of the Date type, the result of the function
is a value of the Number type. If the parameter specifies a  NULL value, the
result of the function is  NULL. Other values are invalid and produce an error.

HOUR
Description:
This function calculates the hour of a day from a value of the Date type.
An hour value is  between 0 and 23.
The function's parameter is  an expression of the Date type.
If the parameter contains a  value of the Date type, the result of the function
is a value of the Number type. If the parameter specifies a  NULL value, the
result of the function is  NULL. Other values are invalid and produce an error.

MINUTE
Description:
This function calculates the minute of an hour from a  value of the Date type.
A minute value is  between 0 and 59.
The function's parameter is  an expression of the Date type.
If the parameter contains a  value of the Date type, the result of the function
is a value of the Number type. If the parameter specifies a  NULL value, the
result of the function is  NULL. Other values are invalid and produce an error.

SECOND
Description:
This function calculates the second of a  minute from a  value of the Date type.
A second value is  between 0 and 59.
The function's parameter is  an expression of the Date type.
If the parameter contains a  value of the Date type, the result of the function
is a value of the Number type. If the parameter specifies a  NULL value, the
result of the function is  NULL. Other values are invalid and produce an error.

BEGINOFPERIOD
Description:
This function is  used to extract a  certain date from a  given date.
The function's parameter is  an expression of the Date type and the period type
is one of the following: Minute, Hour, Day, Week, Month, Quarter, Year,
TenDays, HalfYear.
Chapter 8. Work with Queries 1-481

Example:
SELECT BEGINOFPERIOD(DATETIME(2002, 10, 12, 10, 15, 34), MONTH)

Result:

Fig. 208.  Query Result

Example:
SELECT BEGINOFPERIOD(DATETIME(2002, 10, 12, 10, 15, 34), DAY)

Result:

Fig. 209.  Query Result

ENDOFPERIOD
Description:
This function is  used to extract a  certain date from a  given date.
The function's parameter is  an expression of the Date type and the period type
is one of the following: Minute, Hour, Day, Week, Month, Quarter, Year,
TenDays, HalfYear.

Example:
SELECT ENDOFPERIOD(DATETIME(2002, 10, 12, 10, 15, 34), MONTH)

Result:

Fig. 210.  Query Result

Example:
SELECT ENDOFPERIOD(DATETIME(2002, 10, 12, 10, 15, 34), YEAR)
1-482 1C:Enterprise 8.3. Developer Guide

Result:

Fig. 211.  Query Result

DATEADD

Description:
This function is  used to add values to a  date.
The first parameter is  a source date which is  to be supplemented by the value
defined by the second and third parameters; it is an expression of the Date
type.
The second parameter, the increment type, is  one of the following: Second,
Minute, Hour, Day, Week, Month, Quarter, Year, TenDays, HalfYear.
The third parameter is  the value which is  to be added to the date specified by
the first parameter. It  is  a value of the Number type (fractional part is  ignored).
Example:
SELECT DATEADD(DATETIME(2002, 10, 12, 10, 15, 34), MONTH, 1)

Result:

Fig. 212.  Query Result

Example:
SELECT DateAdd(DateTime(2002, 10, 12, 10, 15, 34), Day, 5)

Result:

Fig. 213.  Query Result

DATEDIFF

Description:
This function is  used to obtain differences between two dates.
Chapter 8. Work with Queries 1-483

The first parameter is  an expression of the Date type. The  second parameter
is an expression of the Date type. The third parameter, the difference type,
is  one of the following: Second, Minute, Hour, Day, Month, Quarter, Year.
Example:
SELECT DATEDIFF(DATETIME(2002, 10, 12, 10, 15, 34), DATETIME(2002, 10, 14, 9, 18, 06), DAY)

Result:

Fig. 214.  Query Result

Example:
SELECT DATEDIFF(DateTime(2002, 10, 12), DateTime(2002, 11, 03), MONTH)

Result:

Fig. 215.  Query Result

IMPORTANT!
This function calculates the calendar difference between two dates; therefore, you
cannot use it  in  places where you must calculate the count of bank or work days
between two dates.

VALUETYPE

Description:
The function that obtains the value type in  a query.
Parameters:
The function's parameter is  an expression of any type.
The return value is  a Type value.
Example:
SELECT
VALUETYPE(NomenclatureAccounting.Recorder) AS Document
FROM
AccumulationRegister.NomenclatureAccounting AS NomenclatureAccounting
1-484 1C:Enterprise 8.3. Developer Guide

PRESENTATION
Description:
This function returns the string presentation of a  value of arbitrary type.
The function's parameter is  an expression of any type.
The return value is  a String value.
The result of the function cannot be used within other functions, except for the
PRESENTATION function.
Example:
SELECT
PRESENTATION(Document.Contractor) AS Recipient,
PRESENTATION(Document.Date) AS Date
FROM
Document.Invoice AS Document

Result:

Fig. 216.  Query Result

ISNULL
Description:
This function replaces a  NULL value with another value.
Function parameters:
„„ The first parameter is  an expression of any type;
„„ The second parameter is  an expression of any type.
The return value is that of the first parameter if it is not NULL; otherwise
it  is  the value of the second parameter.
The second parameter is  cast to the type of the first parameter if the type of the
first parameter is  String or Number.
Example:
// Obtain sum based on Count field. If no record
// exists, display 0
SELECT
ISNULL(SUM(InvoiceContent.Count), 0)
FROM
Document.Invoice.Content AS InvoiceContent
Chapter 8. Work with Queries 1-485

8.2.16.4. Case Operations in  Query Language

Query language expressions can use case operations which allow you to obtain one
of the possible values meeting the specified conditions.
Case operations are described by the following set of rules:
<Case operation>
CASE
<Case alternatives>
[ELSE <Expression>]
END

<Case alternatives>
<Single case>
[<Case alternatives>]

<Single case>
WHEN <Logical expression>
THEN <Expression>

In case operations, you can specify an unlimited number of alternative single

cases WHEN … THEN. These are processed in the query in a sequence. If the
logical expression is True, then the case operation processing is completed.
The  operation result is  a value of the expression specified after the THEN keyword.
For a  description of logical expressions see page 1-489.
The value of the expression specified after the ELSE keyword is  used as the case
operation result if the predicate was False in  all the previously indicated alterna-
tive single cases.
Example:
SELECT
Nomenclature.Description,
CASE
WHEN Nomenclature.IsFolder = TRUE
THEN "This is  a folder"
WHEN Nomenclature.PurchasePrice > 1000
THEN "1000 -"
WHEN Nomenclature.PurchasePrice > 100
THEN "100 – 1000"
WHEN Nomenclature.PurchasePrice > 10
THEN "10 – 100"
WHEN Nomenclature.PurchasePrice > 0
THEN "0 – 10"
ELSE "Not specified"
END AS Price
FROM
Catalog.Nomenclature AS Nomenclature
1-486 1C:Enterprise 8.3. Developer Guide

Result:

Fig. 217.  Query Result (Fragment)

8.2.16.5. Type Cast in  Query Language

Fields of source tables can have a  composite type. These fields have to cast their
values to a particular type. The query language provides you with a type cast
feature. You can use it in the selection field list and the filter criterion of the
WHERE clause.

<Type cast>
CAST ( <Expression> AS <Value type> )

<Value type>
Boolean |
Number [(Length[, Precision])]|
String [(Length)]|
Date |
<Table name>

<Length>
Number

<Precision>
Number

The expression is  cast to one of the primitive types or a  data reference type. In  the
latter case the table name refers to the corresponding infobase table.
If the expression contains the required value type in  its composite type, then type
casting is  possible and the result for each value of the specified type will be the
value itself. For values of other types, the result of type cast will be NULL.
If the expression does not contain the required value type in  its composite type,
the query execution will be completed with an error because type casting cannot be
performed.
Chapter 8. Work with Queries 1-487

8.2.16.6. Constants and Parameters in  Query Language

Query language expressions can contain directly specified values of Boolean,
Number, String or Date type. Query parameter values can also be used:
<Value>
TRUE |
FALSE |
<NUMBER type literal> |
<STRING type literal> |
<DATE type literal> |
<TYPE type literal> |
<Parameter name> |
UNDEFINED |
NULL

<Number type literal>

<Integer>[.<Integer>]

<String type literal>

"<Character sequence>"

<Date type literal>

DATETIME ( <Integer>, <Integer>, <Integer>[,
<Integer>, <Integer>, <Integer>] )

Values of Boolean, Number and String types are specified in  the same way as
in  the 1C:Enterprise script.
Date type values are specified using the DATETIME keyword followed by the
sequence of year, month, day, hour, minute and second. The  last three components
are optional.
IMPORTANT!
The maximum date you can specify using the DATETIME literal is  12/31/3999
23:59:59.
You can pass multiple parameters to a query (see a description of the Query
object). Parameter values can be used in  the query language expressions. In  this
case you need to specify the "&" character followed by the parameter name.
<Type type literal>
TYPE(<Type name>)

<Type name> is a  name of a  primitive type or a  name of a  table, the type of

reference to which must be obtained. The  result of this expression will be a  Type
value for the specified type.
1-488 1C:Enterprise 8.3. Developer Guide

Example:
// Retrieval of the String type
TYPE(String)

// Retrieval of a  type referencing the Nomenclature catalog

TYPE(Catalog.Nomenclature)

Type values can be used in  comparison ordering and grouping operations of the
query language.
Example:
SELECT
VALUETYPE(Balance.Recorder)
FROM
AccumulationRegister.NomenclatureAccounting AS Balance
WHERE
VALUETYPE(Balance.Recorder) = TYPE(Document.Invoice)

A Type value can be passed as a  query parameter.

Example:
SELECT
VALUETYPE(Balance.Recorder)
FROM
AccumulationRegister.NomenclatureAccounting AS Balance
WHERE
VALUETYPE(Balance.Recorder) = &Type

When Type values are compared, they have the following order (the type listed first
is  the smallest):
„„ NULL
„„ Undefined
„„ Boolean
„„ Number
„„ Date
„„ String
„„ References to a  table
„„ Other types

8.2.17. Conditions in  Query Language

The query language uses filter criteria to filter data in  the WHERE, HAVING and JOIN
clauses. The  following rules describe these criteria:
<Filter criterion>
<Logical component> [OR <Logical component>]
Chapter 8. Work with Queries 1-489

<Logical component>
<Logical factor> [AND <Logical factor>]

<Logical factor>
NOT <Logical factor> |
( <Filter criterion> ) |
<Logical expression>

In the simplest case, a  condition is  an expression with a  result having a  logical
type value. Logical expression are described in  the next section.
Conditions can also be defined as more complex expressions, where simple logical
expressions are joined using the logical operators AND or, NOT.
Logical operators have the following priorities:
„„ NOT has the highest priority.
„„ AND is  next in  priority.
„„ OR has the lowest priority.
„„ Simple logical expressions are calculated first, then NOT, then AND and finally
OR. In  order to set another calculation order, you can use parentheses ().

8.2.17.1. Logical Expressions in  Query Language

You can use the following logical expressions in  case operations and filter criteria:
<Logical expression>
<Expression> |
<Expression> <Comparison operation> <Expression> |
<Expression> [NOT] IN [HIERARCHY] ( <Value list> ) |
<Expression> [NOT] IN [HIERARCHY] ( <Query description> ) |
<Expression> [NOT] BETWEEN <Expression> AND <Expression> |
<Expression> IS [NOT] NULL |
<Expression> REFS <Table name> |
<Expression> [NOT] LIKE <STRING type literal>
[ESCAPE <STRING type literal>]

<Comparison operation>
> | < | = | >= | <= | <>

<Value list>
<Expression>[, <Expression> [, …]]

A logical expression can be:

„„ A normal query language expression if its result has a  logical type;
1-490 1C:Enterprise 8.3. Developer Guide

„„ A comparison operation for two query language expressions carried out

according to the value comparison rules described in  the "Value Comparison
Rules" section;
„„ An operator for checking equality or inequality of the expression value with one
of the listed values or with values from the results of another query;
„„ An operator for checking whether the expression value falls into a certain
range;
„„ An operator for checking the expression value against NULL;
„„ An operator for checking reference expression values for references to a  certain
table;
„„ An operator for checking string values for matching a  template.
Value comparison rules used to compare values are described below.

8.2.17.2. Value Comparison Rules

Since you can compare values of different types in the query language, value
comparison rules have been defined.
These rules are used for:
„„ Comparing values in  comparison operators
„„ Defining the maximum and minimum values in the MIN and MAX aggregate
functions
„„ Ordering query result records according to the order specified in  the ORDER BY
clause
If value types differ from each other, then the relationship between values
is  defined based on type priority:
„„ NULL type (the lowest)
„„ Boolean type
„„ Number type
„„ Date type
„„ String type
„„ Reference types
The relationship between different reference types is defined based on internal
table reference numbers corresponding to one type or another.
If the data are of the same type, then their values are compared according to the
following rules:
„„ For Boolean type True value is  greater than False.
„„ For Number type common number comparison rules are applied.
„„ For Date type earlier dates are less than later dates.
„„ For String type comparison is performed according to established national
features of the database. The string comparison operation ignores ending
Chapter 8. Work with Queries 1-491

spaces, unlike string comparison in  1C:Enterprise script where ending spaces
are used in comparison operations. For example, comparing the strings "bb"
and "bb " in 1C:Enterprise script returns False (strings are not equal), but
it returns True in  the query language (strings are equal).
„„ Reference types are compared based on their values (entry number, etc.).
„„ Fields of the UniqueIdentifier type cannot be compared to other fields.
„„ You cannot compare open-ended fields (open-ended strings, ValueStorage,
ValueType field from charts of characteristic types tables).
IMPORTANT!
Any comparison operation with at least one NULL value results in  False.

8.2.17.3. Operator for Value Matching Check

IN operator form to check if a  value matches one of the listed
IN operator allows you to check if an expression value in  its right part matches
one of the values described in its left part. If at least one match is found, the
result of the operator is  True; else it  is  False. You can inverse operator action
by using NOT. Values are compared according to the rules described in  the "Value
Comparison Rules" section.
Example:
SELECT
Nomenclature.Description
FROM
Catalog.Nomenclature AS Nomenclature
WHERE
Nomenclature.Parent.Description IN("Home Appliances", "Office Equipment")

IN operator form to check membership in  hierarchy

You can check if a catalog belongs to a specific hierarchy. IN HIERARCHY
operator returns True if the left-hand expression value is  a reference to a  catalog
item and is  included in  a value array in  the right part or hierarchically belongs to
a  group included in  the array.
Example:
// A reference to any group of the Nomenclature catalog
// is  passed to the query as a  Group parameter.

SELECT
Nomenclature.Description
FROM
Catalog.Nomenclature AS Nomenclature
WHERE
Nomenclature.Ref IN HIERARCHY(&Group)
1-492 1C:Enterprise 8.3. Developer Guide

The query result can act as a  value array that is  checked for matching. In  this case
you need to specify a  query description to the right of IN operator.
Example:
SELECT
Nomenclature.Description
FROM
Catalog.Nomenclature AS Nomenclature
WHERE
Nomenclature.Ref IN HIERARCHY
(SELECT
Nomenclature.Ref
FROM
Catalog.Nomenclature AS Nomenclature
WHERE
Nomenclature.Description = "Clothes")

IN operator form to check for matching with one of the query results
Below is  an example of how you can use this operator:
Example:
// Select product names included
// in  the invoices
SELECT
Goods.Description
FROM
Catalog.Nomenclature AS Goods
WHERE
Goods.Ref IN
(SELECT
InvoiceContent.Nomenclature
FROM
Document.Invoice.Content AS InvoiceContent)

Result:

Fig. 218.  Query Result (Fragment)

Chapter 8. Work with Queries 1-493

To obtain an inverse result (i.e. if you need to determine that the value does not
match any of the query results) you should use the following query:
Example:
// Select product names included
// in  the invoices
SELECT
Goods.Description
FROM
Catalog.Nomenclature AS Goods
WHERE
(NOT Goods.Ref IN
(SELECT
InvoiceContent.Nomenclature
FROM
Document.Invoice.Content AS InvoiceContent))

Result:

Fig. 219.  Query Result (Fragment)

Please note that you can call table fields that encountered in the external query
before the operation from IN operation query.
Example:
// Select product names included
// in  the invoices
SELECT
Goods.Description
FROM
Catalog.Nomenclature AS Goods
WHERE
Goods.Ref IN
(SELECT
InvoiceContent.Nomenclature
FROM
Document.Invoice.Content AS InvoiceContent
WHERE
InvoiceContent.Nomenclature = Goods.Ref)
1-494 1C:Enterprise 8.3. Developer Guide

Result:

Fig. 220.  Query Result (Fragment)

Use of IN / NOT IN operation for multiple fields

Nested query syntax:

(expression1, expression2, …, expressionN) IN (SELECT expres-
sion1, expression2, …, expressionN …)

Value table syntax:

(expression1, expression2, …, expressionN) IN (&Parameter)
The parameter should be a value table where the first N columns will be used
in the IN operation.

8.2.17.4. Value-Within-Range Check Operator

The BETWEEN operator allows you to check whether or not an expression value
indicated to its left falls into a  range specified to its right. If the value is  within the
range, the operator returns True; otherwise it  returns False. You can inverse the
operator action by using NOT. For value comparison rules, see page 1-490.
Example:
SELECT
Nomenclature.Description,
Nomenclature.PurchasePrice
FROM
Catalog.Nomenclature AS Nomenclature
WHERE
Nomenclature.PurchasePrice BETWEEN 100 AND 1000

8.2.17.5. NULL Check Operator

The ISNULL operator allows you to check if an expression value to its left is  NULL.
If the value is  NULL, the operator returns True; else – False. You can inverse the
operator action by using NOT.
Chapter 8. Work with Queries 1-495

Example:
SELECT
Nomenclature.Description,
Nomenclature.PurchasePrice
FROM
Catalog.Nomenclature AS Nomenclature
WHERE
Nomenclature.PurchasePrice IS NULL

8.2.17.6. Reference Value Check Operator

REFS operator allows you to check if an expression value to its right references
the table specified to its left. If the above condition is  true, the operator returns
True; otherwise it  returns False. For information about dereferencing fields see
page 1-474.
Example:
SELECT
Invoice.Number,
Invoice.Date,
FROM
Document.Invoice AS Invoice
WHERE
Invoice.Contractor REFS Catalog.Contractors

8.2.17.7. String-Like-Template Check Operator

LIKE operator allows you to compare an expression value specified on its left side
with a  template string specified on its right side. The  expression value must be of
the String type. If the expression value matches the template, the operator returns
True; else – False.
The following characters in a template string are for system use only and have
non-string character meaning:
„„ % (percent): a  sequence of any number of arbitrary characters;
„„ _ (underscore): a  single arbitrary character;
„„ […] (one or more characters in square brackets): any character listed in the
square brackets. Enumerations can contain ranges, such as a-z, meaning
a  random character within the range, including ends of the range;
„„ [^…] (a negation character followed by one or more characters in square
brackets): any character besides those listed after the negation mark.
Any other character represents itself only and does not have any additional meaning.
If you must use one of these symbols as itself, it  must be preceded by an escape
character. The  escape character itself (any appropriate symbol) is  defined in  the
same operator after the ESCAPE keyword.
1-496 1C:Enterprise 8.3. Developer Guide

For example, the following template:

"%ABC[0-9][abcd]\_abc%" ESCAPE "\"

represents a  substring consisting of a  sequence of characters:

„„ The letter A
„„ The letter B
„„ The letter C
„„ A digit
„„ One of the letters a, b, c or d
„„ An underscore
„„ The letter a
„„ The letter b
„„ The letter c
Additionally this sequence can be preceded by a  custom set of characters.

8.3. EXECUTION AND USE OF QUERIES

IN  THE 1C:ENTERPRISE SCRIPT
A special set of objects provided in the 1C:Enterprise script permits to create
queries, select, and process query results. These objects are used to generate
queries, tab through query entries, etc.

8.3.1. Major Techniques and Practices

We will use several examples to illustrate work with queries in  the 1C:Enterprise
script. Here is  a typical example of using a  query.

// Generate a  query
Query = New Query("SELECT Product.Description Description,
|Product.Parent.Description ParentDescription
|FROM Catalog.Goods Product");

// Execute the query and write the result to the QueryResult variable.
QueryResult = Query.Execute();

// Obtain the query result selection.

Selection = QueryResult.Select();

// While the selection contains records ...

While Selection.Next() Do

// ... display the result fields in  the message window.

Product = Selection.Description;
Parent = Selection.ParentDescription;
Message("Product: " + Product + " Parent: " + Parent);
EndDo;
Chapter 8. Work with Queries 1-497

As you can see from this example, work with queries is based on three main
objects:
„„ Query – an object that executes the query. In  the example, this object is  repre-
sented by the Query variable.
„„ QueryResult – an object that contains the query result. In  the example, this
object is  represented by the QueryResult variable.
„„ QueryResultSelection – an object that can be used to select (i.e. tab through)
records in  the result. In  the example, this object is  represented by the Selec-
tion variable.
Review the QueryResultSelection object in  more detail.
Use the following query for this purpose:

SELECT
InvoiceContent.Nomenclature AS Nomenclature,
InvoiceContent.Count AS Count
FROM
Document.Invoice.Content AS InvoiceContent

ORDER BY
InvoiceContent.Nomenclature
TOTALS
SUM(Count)
BY
Nomenclature HIERARCHY

Result:

Fig. 221.  Working Selection

In this table we have added column No.1 which is  not present in  the query result.
We will use it  later to identify query result records. Totals records in  the table are
shown in  italic, while the totals records for hierarchical catalog levels are shown
in bold.
1-498 1C:Enterprise 8.3. Developer Guide

8.3.1.1. Query Result Iteration Methods

Linear Result Iteration
The linear method of result iteration is the simplest. In the linear method, the
selection yields records in the same sequence as in the query results. In the
example above, this will be records 1, 2, 3, 4, 5 and so on, up to 20.
To get a linear selection from the result, call the Select() method
of the QueryResult object without any parameters or with the QueryRe-
sultIteration.Linear parameter.
Example:
SelectionMode = QueryResultIteration.Linear;
Selection1 = QueryResult.Select(SelectionMode);
// which is  equivalent to the record
Selection1 = QueryResult.Select();

Hierarchical Result Iteration

The next method for result iteration is called hierarchical. This iteration
is used only for records on a single level. To get a hierarchical selection
from the result, call the Select() method for the QueryResult object with the
QueryResultIteration.ByGroupsWithHierarchy parameter.
Example:
SelectionMode = QueryResultIteration.ByGroupsWithHierarchy;
Selection2 = QueryResult.Select(SelectionMode);

In this example, selection from the results using hierarchical iteration will be
completed only for records 1 and 11, as these are the only two records that are
located at the highest level. To illustrate this, let us assume that the result is  a tree,
where totals records are nodes and detailed records are leaves. Here is  what we
will get (see fig. 222).
From this picture, you can see that only records 1 and 11 are located at the top
level of the tree and that only these records will be included in  the first pass of
hierarchical iteration.
The next question would be how to obtain other records of the query result.
To do this, you can get another selection from the QueryResultSelection object.
This  selection will be used for iteration over the subordinate records of the current
selection record. In this example, when the Selection2 object is to be placed
into record No 1, we will ask it  for a  hierarchical selection. This  way, we will
get a  selection that will return records 2 and 7. When Selection2 is  to be placed
in record No 11, the final hierarchical selection will return records 12 and 16.
This  is  how the hierarchical iteration for query results works.
Chapter 8. Work with Queries 1-499

Fig. 222.  Hierarchical Query Result Iteration

Please note that you can obtain nested selections of any type from the parent selec-
tion. Thus, if you request a linear Selection2, placed into record 1, it would
return records 2 to 10. Review an example of this technique.
Example:
Procedure ExecuteQuery()
// Generate a  query.
Query = New Query;

// Set the query text

Query.Text = "SELECT
|InvoiceContent.Nomenclature AS Nomenclature,
|InvoiceContent.Count AS Count
|FROM
|Document.Invoice.Content AS InvoiceContent
|ORDER BY
|InvoiceContent.Nomenclature
|TOTALS
|SUM(Count)
|BY
|Nomenclature HIERARCHY";
1-500 1C:Enterprise 8.3. Developer Guide

// Execute the query and write the result to the variable

// QueryResult.
QueryResult = Query.Execute();

// Obtain the query result selection.

SelectionMode = QueryResultIteration.ByGroupsWithHierarchy;
Selection = QueryResult.Select(SelectionMode);

OutputRecursively(Selection);

EndProcedure

Procedure OutputRecursively(Selection)
// While the selection contains records ...
While Selection.Next() Do
// ... display result fields in  the message window
Product = Selection.Description;
Count = Selection.Count;
Message("Product: " + Product + " Count: " + Count);

// Continue subordinate records selection

SelectionMode = QueryResultIteration.ByGroupsWithHierarchy;
OutputRecursively(Selection.Select(SelectionMode, Selection.Group()));
EndDo;
EndProcedure

Result Iteration by Groups

The third and the final method of result iteration is by groups. It is similar to
hierarchical iteration, but with one difference: records with hierarchical results are
treated as detailed records rather than totals records. To get a  result for a  group
selection query you have to call the Select() method for the QueryResult object
with the QueryResultIteration.ByGroups parameter.
Example:
SelectionMode = QueryResultIteration.ByGroups;
Selection2 = QueryResult.Select(SelectionMode);
// After interation of all the records is  complete, we get the following:
// 1, 2, 7, 11, 12, 16.

Example:
Procedure ExecuteQuery()
// Generate a  query.
Query = New Query;

// Set the query text

Query.Text = "SELECT
|InvoiceContent.Nomenclature AS Nomenclature,
|InvoiceContent.Count AS Count
|FROM
Chapter 8. Work with Queries 1-501

|Document.Invoice.Content AS InvoiceContent
|ORDER BY
|InvoiceContent.Nomenclature
|TOTALS
|SUM(Count)
|BY
|Nomenclature HIERARCHY";

// Execute the query and write the result to the variable

// QueryResult.
QueryResult = Query.Execute();

// Obtain the query result selection

SelectionMode = QueryResultIteration.ByGroups;
Selection = QueryResult.Select(SelectionMode);

// While the selection contains records ...

While Selection.Next() Do
// ... display result fields in  the message window
Product = Selection.Description;
Count = Selection.Count;
Message("Product: "+Product+" Totals for product: "+Count);

OutputChildRecords(Selection.Select());
EndDo;
EndProcedure

Procedure OutputChildRecords(Selection)
// While the selection contains records ...
While Selection.Next() Do
// ... display result fields in  the message window
Product = Selection.Description;
Count = Selection.Count;
Message("Product: "+Product+" Count: "+Count);
EndDo;
EndProcedure

8.3.1.2. Working with Selection

The QueryResultSelection object is  used to cycle through query result records.
A selection can be represented as an object that contains a  reference to the current
result record and grants the program access to all fields of the current record. Three
methods are used for query record navigation:
„„ Next() – go to the next result record according to the selection iteration order.
At the first call, the selection will be positioned to the first record. When all
records are selected, this method will indicate this by returning a  False value.
„„ NextByFieldValue() – get the next record with a  value in  the given field that
is  different from the value in  the same field of the current record.
„„ FindNext() – find a  record with the specified values of certain fields.
1-502 1C:Enterprise 8.3. Developer Guide

Use of NextByFieldValue() Method

You can use this method to group results by field values.
Example:
SELECT
Doc.Nomenclature,
Doc.Ref.Contractor AS Contractor,
Doc.Count
FROM
Document.Invoice.Content AS Doc

ORDER BY
Doc.Nomenclature.Description,
Contractor

Result:

Fig. 223.  Query Result

You get a  linear selection from the query result and can use the NextByField-
Value() method for iteration.
Example:
Selection = QueryResult.Select();
While Selection.NextByFieldValue("Product") Do
// there we'll get records with numbers 1, 5, 9, 12
While Selection.NextByFieldValue("Contractor") Do
// there we'll get records with numbers 1, 2, 3, 4 at first
// then we'll get records with numbers 5, 6, 7
// then we'll get records with numbers 9, 10, 11
// then we'll get records with numbers 12, 13, 14, 15
EndDo;
EndDo;

Please note that record 8 is  not selected in  the internal cycle, since it  has the same
Recipient field value as the previous record.
Chapter 8. Work with Queries 1-503

If you use the Next() method to get records by field value, all records with the
same field value specified during the previous call of the NextByFieldValue()
method will be selected.
Example:
Selection = QueryResult.Select();
While Selection.NextByFieldValue("Product") Do
// there we'll get records with numbers 1, 5, 9, 12
While Selection.Next() Do
// there we'll get records with numbers 1, 2, 3, 4 at first
// then we'll get records with numbers 5, 6, 7, 8
// then we'll get records with numbers 9, 10, 11
// then we'll get records with numbers 12, 13, 14, 15
EndDo;
EndDo;

Methods for Defining the Current Record Type

When a  selection is  placed into a  record, you can use this selection to determine
the characteristics of the record. You can use the following methods to get record
characteristics:
„„ Level() – determines the record level in  the query result.
„„ RecordType() – determines whether the record belongs to one of the following
types:
○○ Group total
○○ Total by hierarchy
○○ Detailed record
○○ Overall
„„ Group() – determines the name of the field that was used for calculating totals.
To illustrate how this method works, review what it  returns for a  query used as an
example at the beginning of this chapter:
SELECT
InvoiceContent.Nomenclature AS Nomenclature,
InvoiceContent.Count AS Count
FROM
Document.Invoice.Content AS InvoiceContent

ORDER BY
InvoiceContent.Nomenclature
TOTALS
SUM(Count)
BY
Nomenclature HIERARCHY
1-504 1C:Enterprise 8.3. Developer Guide

Result:

Fig. 224.  Record Hierarchy

8.3.2. Work with Temporary Tables

The 1C:Enterprise query language permits using temporary tables in  queries. Use
of temporary tables helps to increase query performance and makes the text of
complex queries easier to understand.
Work with temporary tables is  supported by two components:
„„ 1C:Enterprise script TempTablesManager object that stores temporary table
data;
„„ query language syntax that allows creation of new and use of existing temporary
tables.

8.3.2.1. Temporary Tables Manager

The temporary tables manager is  used to manage the lifetime of temporary tables
created during the application operation.
Any number of the temporary tables manager instances can be created in one
application, each storing its own set of temporary tables. Each temporary table
is  uniquely identified with a  name and all the temporary tables within one tempo-
rary table manager must have unique names.
NOTE
Temporary table names have to meet the requirements imposed upon variable
names in  the 1C:Enterprise script (see page 1-120).
The temporary tables manager instance can be created using the New wizard.
Chapter 8. Work with Queries 1-505

Example:
TempTablesManager = New TempTablesManager;

All the temporary tables created in  the given manager instance exist only while the
temporary tables manager instance exists. If the manager instance is  destroyed, all
of its temporary tables are also deleted.
The temporary tables manager can be forced to close by using the Close() method.
This will delete all tables created in it. Further work with this manager will
become impossible.

8.3.2.2. Creation of Temporary Tables

Temporary tables are created using the Query object of the 1C:Enterprise script.
The query is linked to the temporary tables manager through the TempTab-
lesManager query property. It  specifies the manager instance where the tempo-
rary tables must be created.
Example:
TempTablesManager = New TempTablesManager;
Query = New Query;
Query.TempTablesManager = TempTablesManager;

A temporary table can be created based on database data or external source data
(for example, a  value table).
In order to create a temporary table based on database data, set the temporary
tables manager for the Query object, then run a  database query using the INTO
keyword followed by the name of the created temporary table. The  INTO keyword
is  located after the query selection list.
Example:
SELECT
Nomenclature.Code,
Nomenclature.Description
INTO TemporaryTable
FROM
Catalog.Nomenclature AS Nomenclature

The query result will contain a  single row with a  Count column that will include
the records placed in  the created table.
If the temporary tables manager is  not set or is  closed or the specified temporary
tables manager already has a  table with the specified name, an error message will
appear.
If you do not want to use an external source as a  basis for temporary tables, you
can use the FOR UPDATE clause; this is  required when you need to place data into
1-506 1C:Enterprise 8.3. Developer Guide

a  temporary table and at the same time prevent other transactions from reading the
data by locking it.
Example:
SELECT
Invoice.Ref,
Invoice.Number,
Invoice.Date,
INTO TemporaryTable
FROM
Document.Invoice AS Invoice
WHERE
Invoice.Ref IN(&Documents)

FOR UPDATE

If you need to create an index for a temporary table, specify the INDEX BY
keyword in  the query followed by the fields used to build an index.
Example:
SELECT
Nomenclature.Code AS Code,
Nomenclature.Description
INTO TemporaryTable
FROM
Catalog.Nomenclature AS Nomenclature

INDEX BY
Code

Fields for indexing must be included in  the selection list.

If a  value table is  used as a  source, it  should have explicitly defined types of the
values included in  columns.
The FOR UPDATE clause must be used to create a  temporary table and lock data
in  tables used as a  basis for the temporary table.
Example:
SELECT
Invoice.Ref,
Invoice.Number,
Invoice.Date,
INTO TemporaryTable
FROM
Document.Invoice AS Invoice
WHERE
Invoice.Ref IN(&Documents)

FOR UPDATE
Chapter 8. Work with Queries 1-507

In order to create temporary tables based on an external source, specify the name
of the parameter in  which the external source will be placed, in  the list of sources
in the query text. The remaining syntax is identical to the usual creation of
a  temporary table.
The following entities can be external sources:
„„ Value table
„„ Tabular section
„„ Query result
An example of the temporary table created on basis of external source is  shown
below:

SELECT
Source.Code,
Source.Description
INTO TemporaryTable
FROM
&ExternalSource AS Source

In this example, the contents of the Code and Description columns are placed to
TemporaryTable from an external source, for example, a  value table passed as the
ExternalSource parameter.
IMPORTANT!
You can't create a  temporary table if it  is  created based on value tables with
a  UUID-type value in  the columns.
IMPORTANT!
If a  temporary table is  on basis of external source, do not use unions and joins
in  the query or the fields that are field attributes of the tables used as a  basis for
the temporary table.

8.3.2.3. Use of Temporary Tables

To use existing temporary tables, set a  temporary tables manager for the Query
object; after this you can call the temporary tables included in  this temporary tables
manager by name, like standard query tables.

8.3.2.4. Deletion of Temporary Table

In order to delete a  temporary table from the temporary tables manager, use the
DROP keyword of the query language followed by the name of the deleted table.
Example:
DROP TemporaryTable

If the table to be dropped does not exist, an error message will be displayed.
1-508 1C:Enterprise 8.3. Developer Guide

8.3.3. Working with Batch Queries

The 1C:Enterprise platform supports operations with query batches. Query texts
are separated by semicolons (";") within a batch query. Queries are executed
sequentially; temporary tables created during query execution exist until the end
of the entire query batch or until a  query that drops a  particular temporary table
is  executed in  the batch.
Example:
Query = New Query;
Query.Text=
"SELECT
|NomenclatureAccountingBalancesAndTurnovers.Nomenclature,
|NomenclatureAccountingBalancesAndTurnovers.QuantityReceipt,
|NomenclatureAccountingBalancesAndTurnovers.QuantityExpense,
|NomenclatureAccountingBalancesAndTurnovers.QuantityEndingBalance
|INTO NomenclatureAccounting
|FROM
|AccumulationRegister.NomenclatureAccounting.BalanceAndTurnovers
(, , Auto, , ) AS NomenclatureAccountingBalancesAndTurnovers
|;
|
|SELECT
|NomenclatureAccounting.Nomenclature,
|NomenclatureAccounting.QuantityExpense,
|NomenclatureAccounting.QuantityEndingBalance
|FROM
|NomenclatureAccounting AS NomenclatureAccounting
|;

Result = Query.Execute();

The first query creates a  temporary table; its data are used in  the second query.
If the temporary tables manager is  set for the Query object that executes the batch
query, temporary tables that were not terminated within the batch query will be
saved in  this manager. Within the text of a  batch query, you may use and destroy
temporary tables that existed in  the assigned temporary tables manager at the batch
execution start.
In addition to the Execute() method that executes all batch queries sequentially
and returns the result of the last batch query, the 1C:Enterprise platform provides
another method, i.e. ExecuteBatch(). This  method executes all queries sequen-
tially and returns a result array for each query in the batch according to the
succession of queries within the batch text. A query to terminate a  temporary table
results in  the Undefined value which will also be included in  the result array.
Chapter  9

WORK WITH DATA

9.1. OBJECT LOCKS

As it  works with object data (catalogs, documents, account, etc.), the 1C:Enterprise
system provides two types of object locks: pessimistic and optimistic. These allow
you to modify entire objects with multiple simultaneous users.

9.1.1. Pessimistic Lock

A pessimistic lock of database objects prevents other sessions or this session from
modifying the object data until the lock is released (automatically or using the
1C:Enterprise script methods).
Generally, pessimistic locks are used by 1C:Enterprise to lock objects edited in  a form.
At the same time the developer can enable this feature using the 1C:Enterprise script.
In 1C:Enterprise, pessimistic locks are applied with the help of application object
form extensions. As soon as the user starts modifying an object in  a form, the form
extension enables a  pessimistic lock. If another user attempts to edit this object
while the lock is  active, a  message appears explaining that the object could not
be locked. When the user who edited the object closes the object form, the form
extension releases the pessimistic lock.
If you want to apply the standard form behavior to the non-standard object form,
you can use the form's LockFormDataForEdit() method to enable a  pessimistic
lock and the UnlockFormDataForEdit() method to release the lock.
The developer can enable a pessimistic lock using the global context
LockDataForEdit() method. Two options of pessimistic lock are available:
„„ Form ID is specified. In this case a lock is active while the form exists;
the lock is automatically released when the form is closed or the session
is  terminated. You can also release the lock using the global context UnlockDa-
taForEdit() method with the form ID specified when setting the lock;
1-510 1C:Enterprise 8.3. Developer Guide

„„ No form ID is  specified. In  this case the applied lock is  not associated with
any form. It  is  automatically released when a  session is  terminated or control
return from the server or transaction is  complete (if the lock was placed on the
transaction). You can also release the lock using the global context UnlockDa-
taForEdit() method without specifying the form ID.
Please note, however, that locking an object does not guarantee it cannot be
updated or removed from the database. Therefore, to ensure the locked object
cannot be modified, another session must attempt to lock it, too, before the modifi-
cation operation. An attempt to lock a  previously locked database object raises an
exception that can be processed using Try … Except … EndTry.
&AtServer
Function SampleModification()

ProductRef = Catalogs.Goods.FindByCode("000000001");

Try

LockDataForEdit(ProductRef);

// Object data can be modified
// ...
ProductObject = ProductRef.GetObject();
ProductObject.Description = "New description";
ProductObject.Write();

Return True;

Except

// Object data cannot be modified

Message = New UserMessage;
Message.Text = "Object data already locked";
Message.Message();

Return False;
EndTry;
EndFunction

Please remember that concurrent attempts to lock an object with form ID and
without it  are incompatible.
ProductRef = Catalogs.Nomenclature.FindByCode(1);

LockDataForEdit(ProductRef);

Try

LockDataForEdit(ProductRef, , FormID);

Except

// exception due to lock incompatibility

EndTry;
Chapter 9. Work with Data 1-511

The developer can release a  pessimistic lock using the global context UnlockDa-
taForEdit() method.

9.1.2. Pessimistic Lock and Transactions

Object lock operations affect other object lock operations only and have no effect
on data operations or transactions.
An attempt to lock a  previously locked database object raises an exception that can
be processed and does not result in  an automatic transaction rollback. If execution
of the LockDataForEdit() method within the transaction raises an exception,
it  can be processed using Try … Except … EndTry and does not require a  trans-
action rollback.
Object locks enabled in  the course of a  transaction are released when the transac-
tion is  complete if no form ID is  specified for the lock.

9.1.3. Optimistic Lock

An optimistic lock prevents an object from being written to the database if the
object was modified in  the database after it  had been read.
Technically, an optimistic lock is  a check performed before the object is  written to
the database.
When an object of the 1C:Enterprise script reads data from the database, it  also
reads the version of the object stored in  the database.
If the object data in  the database has been modified (e.g., by another user) before
the current user updates the data (sets a  pessimistic lock), it  changes the object
version number stored in  the database. When the user attempts to write the object,
the object version in  memory is  checked against the version in  the database. Since
the versions do not match, a  warning appears explaining that the object version has
changed or the object has been removed, i.e. an optimistic lock is  enabled.
The optimistic lock guarantees that the user's changes do not overwrite the changes
made by other sessions or other application objects of the same session.

9.2. TRANSACTIONS
Regardless of the selected 1C:Enterprise version (file mode version or client/server
mode), the system works with information stored in  the database through transac-
tions.
A transaction is a sequence of data manipulation operations that is atomic
in  terms of its impact on the database. Transactions are "all-or-nothing" in  nature;
they transition the database from one status to another in  its entirety. If one of the
transaction actions cannot be completed for some reason or the system has encoun-
tered an error, the database returns to its pre-transaction status (the transaction
is  rolled back).
1-512 1C:Enterprise 8.3. Developer Guide

Transactions can be used either by the 1C:Enterprise or by the developer as he/she

creates modules.
1C:Enterprise invokes transactions implicitly every time database information
is  modified. Thus, all event handlers located in  object and record set modules and
related to database data modification are called within a  transaction. The  following
types of objects are also read in transactions: ExchangePlanObject, Docu-
mentObject, CatalogObject, ChartOfCharacteristicTypesObject,
ChartOfAccountTypesObject, ChartOfAccountsObject, BusinessPro-
cessObject, TaskObject, SequenceRecordSet, InformationRe-
gisterRecordSet, AccumulationRegisterRecordSet, AccountingRegis-
terRecordSet, CalculationRegisterRecordSet, RecalculationRecordSet.
In  the managed transaction lock mode (see page 1-515), a  shared lock is  applied
based on the recordset recorder value and filter values for the independent informa-
tion register recordset.
Additionally the developer can work with transactions explicitly. In this case
global context procedures BeginTransaction(), CommitTransaction() and
RollbackTransaction() are used.

9.2.1. Explicit Calls to Transactions

The BeginTransaction() procedure can be used to open a transaction. All
subsequent changes to database information made by other operators can be either
committed in  their entirety or rolled back.
All changes can be committed using the CommitTransaction() procedure.
To cancel all changes made to an open transaction, use the RollbackTransac-
tion() procedure. The CommitTransaction() method is used to accept all
applied changes. To cancel all changes applied in  an opened transaction you can
use the RollbackTransaction() method. If the number of BeginTransac-
tion() method calls exceeds the number of CommitTransaction() method
or RollbackTransaction() method calls, the system implicitly calls the
RollbackTransaction() method in  the following cases:
„„ When 1C:Enterprise script execution is finished (event handler, external
connection, automation server).
„„ When control is  transferred from the server to the client.
If the number of CommitTransaction() method or RollbackTransaction()
method calls exceeds the number of BeginTransaction() method calls, an
exception will be generated for every excessive call of CommitTransaction() or
RollbackTransaction().
Chapter 9. Work with Data 1-513

Therefore, a  general layout of use of transactions can look like the following:
BeginTransaction();

// A sequence of operators
…

Try

// A sequence of executed operators

…

Except
RollbackTransaction();
EndTry;

// A sequence of executed operators

…

CommitTransaction();

As you apply this procedure, please remember that errors you encounter when you
work with the database can be processed by the system in  different ways.
Generally, all database errors fall into one of two categories:
„„ Non-recoverable errors
„„ Recoverable errors
Non-recoverable errors can disturb normal operation of 1C:Enterprise system,
e.g. by corrupting data. A non-recoverable error always results in  1C:Enterprise
termination.
If a  non-recoverable error occurs in  the course of a  transaction, all changes made
within this transaction are rolled back by the system.
Recoverable errors do not cause major breakdowns in  1C:Enterprise operation.
In case of a recoverable error the system can continue functioning. The opera-
tion that caused the error is  aborted and an exception is  raised; the latter can be
captured and processed using Try … Except … EndTry.
If a  recoverable error occurs in  the course of a  transaction, the system does not
automatically abort the transaction, allowing the developer to resolve the issue.
The nature of the error defines the issue resolution scenario.
If the error is  not related to the database, the transaction can be continued and the
module operation does not have to be terminated. If necessary, the developer can
cancel the transaction or, on the contrary, carry it  on if the error does not interfere
with the transaction's atomic nature.
If, however, the exception is  due to a  database error, the system registers the error
state of the transaction and continuing or committing the transaction becomes
impossible. The only database operation available to the developer in this case
is  a transaction rollback. The  developer can re-try the transaction later.
1-514 1C:Enterprise 8.3. Developer Guide

A sample code that uses this approach to writing data to the database can look like
the following.
// Abort write attempts flag
Written = False;

// Write attempts in  a loop

While Not Written Do

Try
BeginTransaction();
Data.Write();
CommitTransaction();

// If the transaction is  successfully committed, abort write attempts

Written = True;

Except
// In  case of failure abort the current transaction and
// start the next attempt in  a new transaction
RollbackTransaction();
EndTry;

EndDo;

9.2.2. Nested Transaction Call

You can invoke BeginTransaction(), CommitTransaction() and
RollbackTransaction() procedures within a  running transaction. For example,
you can use the following call procedure:

BeginTransaction();
…

// Nested transaction call

BeginTransaction();
…
CommitTransaction();
…

// Nested transaction call

BeginTransaction();
…
CommitTransaction();
…
CommitTransaction();

However, calls of this type do not start a  new transaction within the current trans-
action.
IMPORTANT!
1C:Enterprise does not support nested transactions.
Chapter 9. Work with Data 1-515

It means the only active transaction is  always the top-level transaction. All trans-
actions invoked within the open transaction belong to this transaction rather than
become nested transactions. Therefore, a rollback of a nested transaction ulti-
mately rolls back the entire top-level transaction rather than the nested transaction
only. At the same time commitment of a  nested transaction is  ignored.

9.2.3. Impact of Transactions on Program Objects

In the most general case, program objects used in 1C:Enterprise are completely
transparent to database transactions. In other words, you can invoke database
transactions when various program object methods are executed; however, actions
involved in  a database transaction rollback generally have no impact on the corre-
sponding program objects.
It means that when database transactions are rolled back the developer is  respon-
sible for making changes to the corresponding program objects (if required).
This  can be achieved by re-reading all object data or changing certain attributes of
the program object (e.g., if required for interface display purposes).
This rule has exceptions. Due to a  very special application nature of 1C:Enterprise
program objects, a  rollback of database changes can, in  some cases, affect property
values of the corresponding program objects. It  happens in  the following cases:
„„ When a  transaction is  rolled back, the document posted flag recovers the pre-
transaction value;
„„ If an object is created and written in a transaction, the transaction rollback
clears the reference value;
„„ If an object is created outside the transaction and is written using its auto-
generated code/number, the transaction rollback clears the code/number.

9.3. MANAGED LOCKS

9.3.1. General Information on Locks
Ideally, in  any DBMS transactions should isolate changes made to the database.
In other words, multiple transactions that modify data concurrently should be
independent.
The simplest solution to this issue is execution of transactions in a sequence.
It  means every subsequent transaction is  executed after the previous transaction
has completed.
However, in practice, using this approach in multi-user systems significantly
reduces the system performance. Therefore, mechanisms that support concurrent
execution of multiple transactions are used.
To make concurrent transactions possible, transactions are isolated at several levels.
At the lowest level transactions can affect each other a  lot. At the top level they are
entirely isolated.
1-516 1C:Enterprise 8.3. Developer Guide

Thus, greater isolation of transactions means more overhead and slow system
performance.
Transactions can be isolated using locks placed on the data used in  transactions.
The  level of isolation defines the lock types applied to various database objects
and the lock duration.
In 1C:Enterprise, you can work with data in  one of two modes:
„„ In a  transaction
„„ Outside a  transaction
When you work with data outside the transaction, you are only allowed to
read the data. This approach ensures maximum speed and concurrency of
data read operations. Therefore, any data read operation outside the transaction
is  unreliable. It  means a  read operation of this type can return obsolete data or
uncommitted changes made by another transaction, i.e. it  does not account for data
locks set by other transactions.
When you work with data within a  transaction, you can perform any data read and
modification operations.
You should follow the following rules:
„„ Data read operations must be reproducible, i.e. any subsequent data read opera-
tion with the same selection criterion must return the same result;
„„ The read operation result must contain the most recent data. It  means no other
transaction can change the data read by the current transaction until the latter
is completed;
„„ The read operation result must not include uncommitted changes of database
data.

9.3.2. Managed Locks

1C:Enterprise allows interacting with the database in  two modes within a  transac-
tion: automatic lock mode and managed lock mode.
The basic difference between these two modes is  described below. The  auto-lock
mode does not require the developer to manage locks within transactions in  any
way in order to ensure the aforementioned rules of working with data in  trans-
actions are followed. These rules are followed by the 1C:Enterprise platform by
applying certain levels of transaction isolation in  a particular DBMS. This  mode
is  the easiest for the developer; however, in  certain cases (e.g., when many users
work with the system concurrently and actively) the transaction isolation level
applied by the DBMS cannot ensure sufficient concurrency of work which leads to
multiple lock collisions.
If you select the managed lock mode, 1C:Enterprise uses a  much lower level of
DBMS transaction isolation, thus improving concurrency of application user oper-
ations. However, unlike the auto-lock mode, this transaction isolation mode cannot
ensure rules for working with data in  transactions are met (e.g., reproducibility of
Chapter 9. Work with Data 1-517

data read operations in  a transaction is  not guaranteed). Therefore, in  the managed
lock mode, the developer has to manage locks applied within transactions.
A summary of differences between the auto-lock and managed lock modes
is  provided in  the table below:
Lock Type Transaction Isolation Level
Auto-locks
File Database Tables Serializable
MS SQL Server Records Repeatable Read or Serializable
IBM DB2 Records Repeatable Read or Serializable
PostgreSQL Tables Serializable
Oracle Database Tables Serializable
Managed Locks
File Database Tables Serializable
MS SQL Server 2000 Records Read Committed
MS SQL Server 2005 and later Records Read Committed Snapshot
IBM DB2 Records Read Committed
PostgreSQL Records Read Committed
Oracle Database Records Read Committed

NOTE
It is  recommended to develop applications in  the managed lock mode to get the
most of your DBMS. Application automatic mode is  used for compatibility with
previous application versions and it  is  not recommended for production opera-
tion.
The system behavior during irresponsive reading (e.g. when dynamic lists are used
or reports are made) also varies depending on the given lock mode. The table
below provides a  summary of the differences of irresponsive reading in  different
(automatic or managed) lock modes.
Reading outside the transaction
Automatic Lock
File database "Dirty" reading
MS SQL Server "Dirty" reading
IBM DB2 "Dirty" reading
PostgreSQL Consistent reading
Oracle Database Consistent reading
Managed Lock
File database "Dirty" reading
MS SQL Server 2000 "Dirty" reading
MS SQL Server 2005 and later Consistent reading
IBM DB2 "Dirty" reading
PostgreSQL Consistent reading
Oracle Database Consistent reading
1-518 1C:Enterprise 8.3. Developer Guide

9.3.3. Setting Lock Mode in  Configuration

Configuration has the Data lock control mode property. Each configuration object
also has the Data lock control mode property.
The data lock control mode for the entire configuration can be set to Automatic,
Managed (used by default for new configurations) and Automatic and managed.
Automatic and Managed enable the respective lock control mode for all the
configuration objects, regardless of their values. Automatic and managed means
that a  particular configuration object will use the mode selected in  its Data lock
control mode property: Automatic or Managed.
It is  important to note that the data lock control mode specified for a  metadata
object is  set for the transactions initiated by 1C:Enterprise when it  works with the
object data (e.g., when it  modifies the object data).
If, however, an object write operation is performed within a developer-initiated
transaction (BeginTransaction() method), the data lock control mode is  defined
by the LockMode parameter of the BeginTransaction() method rather than by
the metadata object's Data lock control mode property.
By default, the LockMode parameter is set to DataLockControlMode.Auto-
matic; therefore, if you want to use the managed lock mode in an explicit
transaction, select the DataLockControlMode.Managed value.

9.3.4. Work with Managed Locks Through

1C:Enterprise Script
To manage locks within transactions, you can use the 1C:Enterprise script Data-
Lock object. You can create an instance of this object in  the wizard and use it  to
describe the required lock namespaces and modes. You can set all the locks you
have created using the Lock() method of the DataLock object. If this method
is  executed in  a transaction (explicit or implicit), locks are set and auto-released
when the transaction is completed. If the Lock() method is executed outside
a transaction or inside a transaction in automatic lock management mode, an
exception will be thrown.
The DataLock object is a collection of data lock items, each describing locks
of a single lock namespace. Lock namespaces are defined in the 1C:Enterprise
platform and match the structure of configuration application objects. Each lock
namespace has fields defined in  the platform and available for analysis when locks
are set.
The following lock namespace names and field names are valid.
Chapter 9. Work with Data 1-519

Lock Namespace Name Lock Namespace Field Name

Catalog.<Name> Ref;
<field name>
Document.<Name> Ref;
<field name>
ExchangePlan.<Name> Ref;
<field name>
ChartOfAccounts.<Name> Ref;
<field name>
BusinessProcess.<Name> Ref;
<field name>
Task.<Name> Ref;
<field name>
ChartOfCalculationTypes.<Name> Ref;
<field name>
ChartOfCharacteristicTypes.<Name> Ref;
<field name>
InformationRegister.<Name>.RecordSet  – Recorder
only for an information register that is  subordinate to
a  recorder
InformationRegister.<Name> Period, if any;
<Dimension name>
AccumulationRegister.<Name>.RecordSet Recorder
AccumulationRegister.<Name> Period;
<Dimension name>
AccountingRegister.<Name>.RecordSet Recorder
AccountingRegister.<Name> Period;
<Dimension name>
<RecordType> – Accountin-
gRecordType system enumeration value;
Account;
ExtDimensions<N>;
<Extra dimension types>
CalculationRegister.<Name>.RecordSet Recorder
CalculationRegister.<Name> RegistrationPeriod;
ActionPeriod;
<Dimension name>
Recalculation.<Name>.RecordSet RecalculationObject
Sequence.<Name>.RecordSet Recorder
Sequence.<Name> <Dimension name>
Constant.<Name>

Where <field name> – is  a name of the field that can be used to set a  managed
lock. A list of valid fields (that can be used to set a  managed lock) shall be set
in the Data lock fields property for the following objects:
„„ catalogs
„„ documents
1-520 1C:Enterprise 8.3. Developer Guide

„„ charts of characteristic types

„„ charts of accounts
„„ charts of calculation types
„„ exchange plans
„„ business processes
„„ tasks
We recommend that you do not set locks by attributes (and common attributes)
of the following types: an unlimited length string, value storage, type description.
This  concerns the following objects: catalogs, documents, charts of characteristic
types, charts of calculation types, charts of accounts, business processes, tasks, and
exchange plans. Locks by Predefined and PredefinedDataName fields cannot
be set in  catalogs, charts of characteristic types, charts of calculation types, and
charts of accounts.
If a  managed transaction lock is  set to the AccountingRegister.<Name> space
and an external dimension value is set by a reference to a characteristics, the
characteristics should be one of the external dimensions of this account in  the chart
of accounts. If no external dimension for the account is  set, an error will be thrown.
In each lock namespace, you can set any number of criteria for the fields used to
select records to be locked. The  criteria can specify that the field value must match
the selected value or must fall within the selected range.
You can use two methods to set the criteria:
„„ Specify the field name and value explicitly (use the SetValue() method of the
DataLockItem object);
„„ Specify the data source that contains the required values (use the DataSource
property of the DataLockItem object).
When you specify the field value explicitly, the SetValue() method receives the
field name and value as its parameters:
Lock = New DataLock;
LockItem = Lock.Add( "Catalog.Shop");
LockItem.SetValue("Code", 100);
LockItem.Mode = DataLockMode.Exclusive;
Lock.Lock();

Lock = New DataLock;

LockItem = Lock.Add("AccumulationRegister.ProductsInStock");
LockItem.SetValue("Quality", Catalogs.Quality.FindByCode("1"));

Please keep in  mind that a  single register record can be locked twice: first, you can
lock the record and then you can lock the set that owns this record.
Chapter 9. Work with Data 1-521

When an object for which the field lock is  available is  deleted or changed, locking
is  performed by the Reference field and by all fields specified in  the Data lock
fields property. If an object is  changed, it  is  locked by "old" field values (which
existed before writing) and by "new" values (which are included in  the object to be
written).
You can also pass the 1C:Enterprise script Range object as a  value; this object
is  created in  the wizard and defines the upper and lower limits of the range (the
limit values are also included in  the range).
If you use a  data source, specify a  value for the DataSource property and then
use the UseFromDataSource() method to map the lock namespace fields with the
data source fields:
Lock = New DataLock;
LockItem = Lock.Add("AccumulationRegister.GoodsInStock");
LockItem.DataSource = DocumentObject.Returnables;
LockItem.UseFromDataSource("Nomenclature", "Nomenclature");
LockItem.UseFromDataSource("Warehouse", "Warehouse");

You can use the following as a  data source:

„„ query result
„„ tabular section
„„ record set
„„ value table
Therefore, when you map fields, the following items are used as source field names:
„„ Query result column names
„„ Tabular section attribute names
„„ Dimension names
„„ Value table column names
The Range object can also serve as a  data source field value.
You can set one of two lock modes for each lock item:
„„ Shared mode
„„ Exclusive mode
To set the lock mode, use the Mode property of the DataLockItem object.
Below is  a table of managed lock compatibility:
Shared lock Exclusive lock
Shared lock + -
Exclusive lock - -

In the shared lock mode, the locked data cannot be modified by another transaction
until the current transaction is  completed.
1-522 1C:Enterprise 8.3. Developer Guide

In the exclusive lock mode, the locked data cannot be modified by another trans-
action until the current transaction is completed and cannot be read by another
transaction placing a  shared lock on the same data.
Considering compatibility of actions within a transaction, you should remember
that in  addition to explicit managed locks set by the user, 1C:Enterprise can also
set implicit managed exclusive locks as it writes data within the transaction.
When you read object data from the database (retrieve the object or follow a  link),
transactional object lock is  not applied. If you need the lock, you should use the
1C:Enterprise script to set it  before calling the object.
Below is  a table of compatibility for actions performed within a  transaction when
the managed lock mode is  used.
Lock Mode NL SL EL
R W R W R W
NL R + + + + + +
W + - - - - -
SL R + - + - - -
W + - - - - -
EL R + - - - - -
W + - - - - -

Where:
„„ R – read
„„ W – write
„„ NL – no lock
„„ SL – shared lock
„„ EL – exclusive lock

9.3.5. Automatic and Managed Mode: Features

The Automatic and managed lock control mode is  used to resolve issues related to
concurrent use of some configuration objects.
Assume you have a  large configuration that is  hard to transition to the managed
lock mode all at once. However, a couple of documents always stick out when
multiple users work with them simultaneously. In  this case you can set the Auto-
matic and managed mode for the entire configuration and then select the Managed
mode for the documents and the configuration objects that are affected when the
documents are written. Thus, you can set up the managed lock mode for the docu-
ments, while the rest of the configuration will still function in  the automatic lock
control mode.
When you work in  the Automatic and managed lock control mode, you should be
aware of two peculiarities:
„„ Regardless of the mode specified for the current transaction, the system applies
managed locks;
Chapter 9. Work with Data 1-523

„„ The lock control mode is  defined by the top-level transaction. In  other words,
if by the time you initiate a  transaction another transaction has been started, the
new transaction can only run in  the mode specified for the running transaction.
Review the above peculiarities in  more detail.
The first peculiarity is that the system places additional managed locks on the
data written in a transaction, even if the transaction already uses the automatic
lock control mode. It  means transactions that run in  the managed lock mode can
conflict with transactions executed in  the automatic lock control mode.
The second peculiarity is that the lock control mode specified for a meta-
data object in the configuration or explicitly set at the transaction start
(in the BeginTransaction() method parameter) is  only a  recommended mode.
The  actual lock control mode for a  transaction depends on whether this transac-
tion call is  the first or another transaction has already been initiated in  the current
1C:Enterprise session.
For example, if you want to manage locks as you write register record sets and post
a  document, the managed lock mode has to be placed on both the register and the
document, since register record sets will be written in  a transaction opened when
you write the document.
Four combinations of lock control modes are valid in a transaction, as demon-
strated in  the table below:
Existing Transaction Mode New Transaction Mode Result
Automatic Automatic The new transaction runs in  the automatic
mode
Automatic Managed The new transaction runs in  the automatic
mode
Managed Automatic An exception is  raised
Managed Managed The new transaction runs in  the managed
mode

9.3.6. Working with multiple managed locks

It should be remembered that if over 100,000 locks are applied to one scope, lock
escalation may occur. Lock escalation means that the whole space is locked.
Should independent separators be used, then escalation is applied to one set of
separator values:
„„ The whole space is  only blocked within the separator values.
„„ Escalation does not impact sessions with other separator values.
1-524 1C:Enterprise 8.3. Developer Guide

9.3.7. Configuration Modification When Switching

to Managed Lock Mode
When you switch to the managed lock mode partially or completely, you have to
refine the application. It  means you have to find code blocks that require managed
locks and set the managed data lock mode in  these blocks. You can use one of two
methods:
„„ Use the DataLock object;
„„ Use the LockForUpdate property for accumulation and accounting register
record sets. The required managed lock is auto-set by the platform if the
register record set to be written has this property set to True.

9.3.7.1. Identification of Code Blocks to Be Refined

Managed locks are required for code blocks that meet one of the following condi-
tions:
„„ Data that are being read needs to be modified later;
„„ A consistent collection of data (included in  multiple objects) is  being read and
data consistency has to be preserved. In  this case the collection data have to be
locked once or in  a sequence as its individual items are being read. If a  data
item is  read once, is  not logically associated with other data items and will not
be modified in  the same transaction, you do not have to lock it;
„„ It is important to ensure the data are not modified until the transaction
is  completed. For example, some data read within the transaction can be read
again and it  is  important to preserve it  intact.
A typical example of such an operation is a request to obtain product balances
in  the document posting module.

9.3.7.2. Managed Lock Mode Selection

The lock mode for the operations described above should be selected based on the
following prerequisites:
„„ Exclusive lock mode should be placed on the data that are to be modified within
the same transaction. It  prevents lock collisions;
„„ Shared lock mode should be placed on the data that are read-only and are not
modified, but require a  lock.

9.3.7.3. Sample Configuration Refinement

Below is an example of setting managed locks in the record set module of the
GoodsInStock accumulation register.
First, create a  managed lock:
Lock = New DataLock;
Chapter 9. Work with Data 1-525

Then analyze the query text generated in  the module and create the required locks.
Exclusive Lock for GoodsInStock Register
When you run the record set module, a query is generated; it contains the
following fragment:

// …
LEFT JOIN
AccumulationRegister.GoodsInStock.Balance(,
Nomenclature IN (SELECT DISTINCT
Nomenclature
FROM
Document.GoodserviceSales.Goods
WHERE
Ref = &DocumentRef))
// …

In this case the following locks are required:

LockGoodsInStock1 = Lock.Add("AccumulationRegister.GoodsInStock");

LockGoodsInStock1.Mode =
DataLockMode.Exclusive;

LockGoodsInStock1.DataSource = DocumentObject.Goods;

LockGoodsInStock1.UseFromDataSource("Nomenclature", "Nomenclature");
LockGoodsInStock1.UseFromDataSource("NomenclatureCharacteristic","NomenclatureCharacteristic");
LockGoodsInStock1.UseFromDataSource("Warehouse", "Warehouse");

Shared Lock for GoodsInReserveInStock Register

When you run the module, a query is generated; it contains the following
fragment:

// …
LEFT JOIN
AccumulationRegister.GoodsInReserveInStock.Balance(,
Nomenclature IN (SELECT DISTINCT
Nomenclature
FROM
Document.GoodserviceSales.Goods
WHERE
Ref = &DocumentRef))
// …
1-526 1C:Enterprise 8.3. Developer Guide

In this case the following locks are required:

LockGoodsInReserveInStock1 = Lock.Add("AccumulationRegister.GoodsInReserveInStock");

LockGoodsInReserveInStock1.Mode = DataLockMode.Shared;

LockGoodsInReserveInStock1.DataSource = DocumentObject.Goods;

LockGoodsInReserveInStock1.UseFromDataSource("Nomenclature", Nomenclature");
LockGoodsInReserveInStock1.UseFromDataSource("NomenclatureCharacteristic","NomenclatureCharacteristic");
LockGoodsInReserveInStock1.UseFromDataSource("Warehouse", "Warehouse");

Shared Lock for GoodsToBeTransferredFromWarehouse Register

When you run the module, a query is generated; it contains the following
fragment:
// …
LEFT JOIN
AccumulationRegister.GoodsToBeTransferredFromWarehouse.Balance(,
Nomenclature IN (SELECT DISTINCT
Nomenclature
FROM
Document.GoodserviceSales.Goods
WHERE
Ref = &DocumentRef))
// …

In this case the following locks are required:

LockGoodsToBeTransferredFromWarehouse1 = Lock.Add("AccumulationRegister.GoodsToBeTransferredFromWarehouse");

LockGoodsToBeTransferredFromWarehouse1.Mode = DataLockMode.Shared;

LockGoodsToBeTransferredFromWarehouse1.DataSource = DocumentObject.Goods;

LockGoodsToBeTransferredFromWarehouse1.UseFromDataSource("Nomenclature", "Nomenclature");
LockGoodsToBeTransferredFromWarehouse1.UseFromDataSource(
"NomenclatureCharacteristic","NomenclatureCharacteristic");
LockGoodsToBeTransferredFromWarehouse1.UseFromDataSource("Warehouse", "Warehouse");

Locks for Returnables Tabular Section Exclusive Lock

for GoodsInStock Register
When you run the module, a query is generated; it contains the following
fragment:
// …
LEFT JOIN
AccumulationRegister.GoodsInStock.Balance(,
Nomenclature IN (SELECT DISTINCT
Chapter 9. Work with Data 1-527

Document.GoodserviceSales.Returnables.Nomenclature
FROM
Document.GoodserviceSales.Returnables
WHERE
Document.GoodserviceSales.Returnables.Ref = &DocumentRef)
AND Quality = &New)
// …

In this case the following locks are required:

LockGoodsInStock2 = Lock.Add("AccumulationRegister.GoodsInStock");

LockGoodsInStock2.Mode = DataLockMode.Exclusive;

LockGoodsInStock2.DataSource = DocumentObject.Returnables;

LockGoodsInStock2.UseFromDataSource("Nomenclature", "Nomenclature");
LockGoodsInStock2.UseFromDataSource("Warehouse", "Warehouse");
LockGoodsInStock2.SetValue("Quality", Catalogs.Quality.FindByCode("1"));

Locks for Returnables Tabular Section Shared Lock

for GoodsInReserveInStock Register
When you run the module, a query is generated; it contains the following
fragment:

// …
LEFT JOIN
AccumulationRegister.GoodsInReserveInStock.Balance(,
Nomenclature IN (SELECT DISTINCT
Document.GoodserviceSales.Returnables.Nomenclature
FROM
Document.GoodserviceSales.Returnables
WHERE
Document.GoodserviceSales.Returnables.Ref = &DocumentRef)) AS Reserves
// …

In this case the following locks are required:

LockGoodsInReserveInStock2 = Lock.Add("AccumulationRegister.GoodsInReserveInStock");

LockGoodsInReserveInStock2.Mode = DataLockMode.Shared;

LockGoodsInReserveInStock2.DataSource = DocumentObject.Returnables;
LockGoodsInReserveInStock2.UseFromDataSource("Nomenclature", "Nomenclature");
LockGoodsInReserveInStock2.UseFromDataSource("Warehouse", "Warehouse");
1-528 1C:Enterprise 8.3. Developer Guide

Locks for Returnables Tabular Section Shared Lock

for GoodsToBeTransferredFromWarehouse Register
When you run the module, a query is generated; it contains the following
fragment:
// …
LEFT JOIN
AccumulationRegister.GoodsToBeTransferredFromWarehouse.Balance(,
Nomenclature IN (SELECT DISTINCT
Document.GoodserviceSales.Returnables.Nomenclature
FROM
Document.GoodserviceSales.Returnables
WHERE
Document.GoodserviceSales.Returnables.Ref = &DocumentRef)) AS GoodsToBeTransferred
// …

In this case the following locks are required:

LockGoodsToBeTransferredFromWarehouse2 = Lock.
Add("AccumulationRegister.GoodsToBeTransferredFromWarehouse");

LockGoodsToBeTransferredFromWarehouse2.Mode = DataLockMode.Shared;

LockGoodsToBeTransferredFromWarehouse2.DataSource = DocumentObject.Returnables;

LockGoodsToBeTransferredFromWarehouse2.UseFromDataSource("Nomenclature", "Nomenclature");
LockGoodsToBeTransferredFromWarehouse2.UseFromDataSource("Warehouse", "Warehouse");

After all the required locks are created, you must lock the data listed above:
Lock.Lock();

// … followed by the previous module text

9.4. EXCLUSIVE MODE

Exclusive mode is a  special database access mode when only one session can be
used for working with a  database. The  exclusive mode can be used when major
changes agreed to need to be implemented in  an infobase that cannot be executed
at the transaction level. The impact of other sessions on the results of changes
should be limited. Some script methods (the DeleteObjects() method) and using
Designer need to be performed in  exclusive mode.
To set or release the exclusive mode, use the SetExclusiveMode() global context
method. To check whether the exclusive mode is  set, use the ExclusiveMode()
method. It is not possible to change the exclusive mode status if a transaction
(explicit or implicit) is  active.
Chapter 9. Work with Data 1-529

If the exclusive mode is  set, no new sessions can be created with this infobase.
Moreover, the exclusive mode cannot be set if multiple sessions work with an
infobase. The exclusive mode does not support setting managed locks (and any
attempts to set them are ignored).
When working in the exclusive mode, you should always bear the following
in  mind: if a  background task is  launched from the session that set the exclusive
mode, the background task launched "takes away" the exclusive mode from the
parent session. During a  background task, the parent session cannot change any
data in  an infobase. The  exclusive mode will return to the parent session when the
launched background task is  completed.
1-530 1C:Enterprise 8.3. Developer Guide
Chapter  10

DATA COMPOSITION SYSTEM

The data composition system is  intended for generation of 1C:Enterprise reports
based upon their declarative description. Using declarative descriptions for the
reports allows to do the following:
„„ Create reports without any coding;
„„ Create various report variants;
„„ Specify user settings in  various variants;
„„ Use automatically generated view and settings forms for the reports;
„„ Break down report's execution into stages;
„„ Execute different stages of report generation on different machines;
„„ Use components of the data composition system independently;
„„ Modify the report's execution process programmatically;
„„ Configure the report's structure;
„„ Combine several tables in  the report;
„„ Create nested reports, etc.
Features of the data composition system are used in  the following cases:
„„ In dynamic lists (see page 1-369),
„„ In preparing data for further processing (e.g., in  data processors).

10.1. GENERAL INFORMATION ON DATA COMPOSITION

The data composition system is  a set of items, each representing a  report execu-
tion stage. Therefore, the entire report execution process in  the data composition
system is  perceived as a  sequence of transitions from one item to another, eventu-
ally reaching the completed report stage.
Each item of the data composition system has its own declarative description,
program access and serialization to/from XML. This approach allows flexible
management of different report execution stages.
1-532 1C:Enterprise 8.3. Developer Guide

The main items of the data composition system are demonstrated on fig. 225.

Fig. 225.  Main Items of Data Composition System

The data composition schema describes the essence of data provided for reporting
(where to receive data from and how to manage data composition). It  represents
a  basis for report generation. It  can contain:
„„ Query text with the data composition system instructions
„„ Description of several data sets
„„ Description of available fields
„„ Description of links between several data sets
„„ Description of data receiving parameters
„„ Description of field and group templates, etc.
The data composition settings describe everything a  developer or a  user can set
up in  the specified data composition schema. They can include:
„„ Filter
„„ Ordering
„„ Conditional appearance
„„ Report structure (parts of the future report)
„„ Data receiving parameters
„„ Data output parameters, etc.
The data composition template represents a predefined description as to how
to create a report. It combines composition schemas and settings. It actually
results from applying specific settings to the composition schema and represents
a  finished task for the composition processor to generate a  report with the required
structure and specified settings.
Chapter 10. Data Composition System 1-533

The data composition result item is  a set of items of the data composition result.
The  data composition result does not exist as an independent logical entity, only
its items do. Items of the data composition result can be output to a  spreadsheet
document for presentation to the end user or to other types of documents.
The data composition process consists of several stages, as shown on fig. 226.

Fig. 226.  Stages of Data Composition Process

The data composition schema can be created in  the following ways:
„„ Visually, using the data composition schema wizard
„„ Visually, using any editor that allows editing XML text
„„ Using a  program with 1C:Enterprise script objects
Editing the data composition settings can use a number of dedicated
1C:Enterprise script objects and table box extensions.
Preparing to execute is a process of generating a data composition template.
This  process generates queries required to obtain the data specified in  the settings
and it  also creates report area templates.
Data composition execution is  a process of obtaining, aggregating and formatting
the data.
Output of data composition result: the obtained composition result can be output
to a  document to be shown to the user. A report can be output in  various formats.
The schema on fig. 227 below demonstrates the data composition system objects
used at different report generation stages in  generalized view.
The data composition schema wizard can be used for creating the data composi-
tion schema.
The data composition settings composer can be used for editing settings of the
data composition system.
1-534 1C:Enterprise 8.3. Developer Guide

Fig. 227.  Data Composition System Objects

The data composition template composer is used at the execution preparation

stage.
The data composition processor executes data composition.
Processor of outputting the data composition result to a spreadsheet docu-
ment outputs items of the data composition result to a  spreadsheet document.
Reports obtained using the data composition system are distinguished by
a  complex structure that includes various combinations of the following items:
„„ Groups
„„ Tables
„„ Plans
„„ Nested reports
Thus, a  report obtained using the data composition system is  not simply a  table,
but a  complex hierarchical structure of the listed items (see fig. 228).
This figure shows a  sample report containing a  chart and product groups at the
first hierarchical level. A particular product group contains a  table with turnovers
for a  product belonging to the group.
Chapter 10. Data Composition System 1-535

Fig. 228.  Report Structure

10.2. COMMON OBJECTS OF DATA COMPOSITION SYSTEM

10.2.1. Use Property
Multiple objects, in particular subsystems of data composition settings, own
a Boolean-type Use property. This  property is  used to partially disable function-
alities without physical removal. This  property is  set to True by default, although
there are some exceptions.

10.2.2. Data Composition System Field

This object represents a  path to field data. The  field is  implemented as a  separate
type that disambiguates properties of some objects that can take on both string
and field values. It has a constructor with the String parameter, which stores
a  path to data, and does not have properties or methods. If the path to data contains
identifiers with spaces or special characters, these identifiers must be enclosed
in brackets.
1-536 1C:Enterprise 8.3. Developer Guide

10.2.3. Data Composition System Parameters

Parameters have been implemented to ensure consistent use and change of value
collections where value lists and item types are predefined and cannot be changed.
This  mechanism includes two parts:
„„ Available parameters that define the collection content and valid item types.
A parameter is  similar to a  data composition system field.
„„ Parameter values.

10.3. DATA COMPOSITION SCHEMA

The data composition schema is represented by the 1C:Enterprise script
DataCompositionSchema object and consists of multiple nested objects.
The  data composition schema is  presented as XML so that it  can be created by
any tools that allow generating XML and used by any tools that can read XML.
The data composition schema is  used to provide information on available settings,
format the data composition template (see page 1-617), i.e. to execute data compo-
sition.
The data composition schema wizard is  used for visual editing of the data compo-
sition schema (see page 1-589).
Data composition schema can be loaded from XML using the standard
1C:Enterprise script tools.

XMLReader = New XMLReader;

XMLReader.SetString(
FormElements.DataCompositionSchemaText.
GetText());
DCS = XDTOSerializer.ReadXML(
XMLReader,
Type("DataCompositionSchema"));

All expressions, described in  the data composition schema, are written in  the data
composition system expression language (see page 1-547).
Chapter 10. Data Composition System 1-537

10.3.1. Data Composition Schema Components

Each data composition schema contains a variety of objects that describe its
components. Let us review these sections:

Fig. 229.  Data Composition Schema Components

10.3.1.1. Data Sources

A data composition schema may contain several data sources.
A data source means a source from where data are retrieved. 1C:Enterprise
infobase is  used as a  data source.
Data sources are described in  the schema's DataSources property that contains
a  value collection consisting of DataCompositionSchemaDataSource items.

10.3.1.2. Data Sets

Data sets in  data composition schemas contain information on what fields can be
retrieved from this set, what data set fields can be used for filtering, etc.
The data composition schema allows the presence of several data sets (see page
1-542).
Data sets are described in  the schema's DataSets property. This  property contains
a  value collection that can include the following items:
„„ Query (DataCompositionSchemaDataSetQuery) – data retrieval
is  described using the query language;
„„ Object (DataCompositionSchemaDataSetObject) – describes the name of
an external data set to be used to retrieve data;
1-538 1C:Enterprise 8.3. Developer Guide

„„ Union (DataCompositionSchemaDataSetUnion) – describes the data sets

included in  the union.
All the three data sets have common properties:
„„ Name – the data set name to be used to address this data set from other objects
of the data composition schema. Within a  single data composition schema data
set names must be unique;
„„ Fields – a  description of the fields available for the data set.
Additionally data sets (queries and objects) contain the DataSource property that
represents the name of a  data source from where data are retrieved. It  must contain
the name of a  data source from the data composition schema (see page 1-537).
Query data sets contain the Query property, i.e. the query text to be used to retrieve
data from the data source. The  query text is  written in  data source terms. Thus,
for a  Local data source type, the query text will be written in  1C:Enterprise query
language terms using a  special extension – a  query language extension for the data
composition system (see page 1-544).
A union data set contains the Items property that lists the data sets included in  the
union (see page 1-538).
Query Data Set
It contains a  standard query to the data in  the 1C:Enterprise infobase.
A query data set can contain a  batch query. The  resulting query is  a batch query.
The  set of fields to be placed in  a temporary table is  automatically defined based
on the fields used in  other queries. If no temporary table fields are required, the
temporary table is not added to the resulting query. The filter used in the data
composition settings is  applied to all queries of the batch.
The data set content is  the result of the last query in  the batch.
Only one data source can be accessed within a  single dataset (including external
data sources).
Object Data Set
An object data set is  used to output information from a  1C:Enterprise object in  a
report; the object can be a  value table, a  query result, a  current document, etc.
This data source is described in the data composition schema, filled program-
matically, e.g., using a  button and passed to the data composition processor as an
external data source.
Union Data Set
A union data set contains the Items property that describes the data sets to be
merged.
Please note that field values of a  union data set are retrieved from the fields of
nested data sets using their data paths. Thus, in  the above example, the external
Chapter 10. Data Composition System 1-539

data set includes the ExpAmount field; and the field data are retrieved from the
nested data sets with the ExpenseAmount data path.
Data Composition Schema Data Set Field
A data set can contain descriptions of fields available for this data set.
The data set fields are described in the DataSetFields property that contains
a  value collection consisting of DataCompositionSchemaDataSetField items.

10.3.1.3. Data Set Links

The data sets included in  the data composition schema can be linked to each other.
The data set links are described in the DataSetLinks property of the data
composition schema; this property contains a value collection consisting of the
DataCompositionSchemaDataSetLink items.

10.3.1.4. Calculated Fields

The data composition schema has a capability to describe fields that will be
calculated by certain expressions using data set fields. These fields can be used
in  settings similarly to data set fields.
Calculated fields are described in the DataCompositionSchemaCalcula-
tedFields property of the data composition schema; this property contains a  value
collection consisting of DataCompositionSchemaCalculatedField items.

10.3.1.5. Resource Fields

The data composition schema can contain a  description of resource fields whose
values are to be calculated for group records. This  is  done using total field descrip-
tion.
Total fields are described in the TotalFields property of the data composition
schema; this property contains a value collection consisting of DataComposi-
tionSchemaTotalField items. Every record from the data set for which the
resource gets calculated, is  used in  this calculation only once.

10.3.1.6. Parameters
The data composition schema contains a  description of the data parameters.
The data parameters are described in the data composition schema parameters
property that contains a  value collection consisting of DataCompositionSche-
maParameter items.
You can specify the parameter mandatory attribute and make the parameter obliga-
tory to fill. For example, using a  combination of these attributes you can implement
a  parameter which, if it  is  not entered, prevents generation of a  report.
1-540 1C:Enterprise 8.3. Developer Guide

10.3.1.7. Nested Schemas

The data composition schema can contain descriptions of nested data composition
schemas.
Nested data composition schemas are described in the NestedDataComposi-
tionSchemas property of the data composition schema; this property contains
a  value collection consisting of NestedDataCompositionSchema items.

10.3.1.8. Templates
Templates to be used for outputting a  field or a  group can be described in  the data
composition schema. When specifying a  template for a  field or a  group, indicate
the name of the template described in  this property.
Templates are described in the data composition schema templates property.
This  property contains a  value collection consisting of DataCompositionSche-
maTemplateDescription items.

10.3.1.9. Field Templates

Each data composition schema field can be assigned a  name of a  template used to
output the field in  the composition result.

Fig. 230.  Field Templates

A link between a field and a template is described using the DataComposi-

tionSchemaFieldTemplate object. A collection of these objects is included
in the FieldTemplates property of the DataCompositionSchema object.
Chapter 10. Data Composition System 1-541

10.3.1.10. Group Templates

Each data composition schema group can be assigned a  name of a  template used
to output the group in  the composition result.
A link between a group and a template is described using the DataComposi-
tionSchemaGroupTemplate object. A collection of these objects is included
in the GroupTemplates property of the DataCompositionSchema object.

10.3.1.11. Group Header Templates

Group header templates can also be described for each group.
A link between a group header and a template is described using the
DataCompositionSchemaGroupTemplate object (see the previous section).
A collection of these objects is  included in  the GroupHeaderTemplates property
of DataCompositionSchema object.

10.3.1.12. Default Settings

Each report variant set up in  the data composition schema contains the default data
composition settings that can be specified by the developer. The  variant listed first
in  the variant list for the data composition system settings is  assigned as default
(the Chart by periods variant on fig. 231). The  default variant settings are applied
when the report is  first opened, the More – Set standard settings (All actions – Set
standard settings) command is  selected or the default settings need to be program-
matically set up.

Fig. 231.  Default Variant

For details on data composition settings see page 1-599.

1-542 1C:Enterprise 8.3. Developer Guide

10.3.2. Working with Multiple Data Sets

The data composition system allows using several data sets in  a single composition.
In order to use multiple data sets in  a single composition, add the data set descrip-
tions to be used to the schema and specify links between the data sets.
Review the following example.
Write three data sets: PriceList, Balance and Sales.

Fig. 232.  Example with Multiple Data Sets

Define links between the data sets. Create a  link between PriceList and Balance
data sets and another link between PriceList and Sales data sets (see fig. 233).

Fig. 233.  Data Set Links

Add resource descriptions (see fig. 234).

Fig. 234.  Data Composition Schema Resources

Chapter 10. Data Composition System 1-543

If the data composition system describes a  link between two data sets, the destina-
tion data set is  considered dependent. The  source data set is  considered a  parent
in  relation to the dependent data set.

Fig. 235.  Dependent Data Sets

In the examples above, the Balance and Sales data sets are dependent.
The  PriceList data set, on the other hand, is  their parent.
There is no indication about the link type in the data composition schema.
All links are considered left external joins. I.e., a  parent data set record is  used
in  the composition even if there are no records in  the dependent set.
You can indicate the link type in  the data composition template (see page 1-617).
The link type is generated by the template composer depending on the applied
global filters. If a global filter is applied to a dependent data set field, links
between this data set and its parents generated in  the data composition template
(up to the top of the data set hierarchy) are Inner. It  means that parent data set
records are included in  the composition only if records are found in  the dependent
data sets.
For example, if the user applies a global filter to the Warehouse field, the
PriceList and Balance data sets are bound by an inner link.

Fig. 236.  Inner Link

If a  data set is  dependent on a  certain data set and the link allows using a  param-
eter list, data from the dependent data set are obtained in  portions of 1000 records.
If using the parameter list is  not allowed in  the link, records are obtained one by
one.
If dependent and parent data sets contain a  field with the same name, this field
is  obtained from the parent data set. In  the examples provided, the Nomenclature
field is  always obtained from the PriceList data set.
1-544 1C:Enterprise 8.3. Developer Guide

Fig. 237.  Common Field

The unlinked data sets cannot contain fields with the same name if they do not have
the same parent with the given field. Thus, the Balance and Turnovers data sets
can contain the Nomenclature field, but they cannot both contain the Contractor
fields.
In the link description, fields from the source data set (the parent set) are used
in  the source expression; fields from the destination data set (the dependent data
set) are used in  the destination link expression. Thus, to describe a  link between
the PriceList and Balance data sets, the Nomenclature expression in the
SourceExpression property uses the PriceList data set field, while the Nomen-
clature expression in  the DestinationExpression property uses Balance data
set field.
Fields from unlinked data sets cannot be used in  a single group and data sets with
the same parent are not considered linked. The  only exception is  total fields that
can be used in  any group. In  the example above, you cannot use the Warehouse
and Contractor fields in  the same group. However, you can use CountBalance
and SumTurnover, because they are resource fields.
The data from a  dependent data set cannot be obtained without obtaining the parent
set data. It  means obtaining data from a  dependent set automatically retrieves data
from the parent set (and all of its parents). In  the above example, when you obtain
the Balance data set, data from the PriceList set is  also retrieved.
If a group uses data sets from multiple data sets, iteration is performed in the
last dependent data set during composition. Thus, if a group uses fields of the
PriceList and Balance sets, iteration is  performed in  the Balance set.
If no field from the linked data set is used in the settings, the data set is not
included in  the data composition template.

10.3.3. Query Language Extension

for Data Composition System
A query language extension for the data composition system is  performed using
special syntax instructions enclosed in  braces and placed directly in  the query text.
Chapter 10. Data Composition System 1-545

10.3.3.1. Syntax Elements of Query Language Extension

for Data Composition System
SELECT

Description:
This clause describes the fields that can be selected by the user for output.
This keyword is followed by comma-separated field aliases from the main
query selection list that are available for setup.
A field alias can be followed by a  combination of ".*" characters that imply
child fields of this field can be used.
Thus, Nomenclature.* means Nomenclature child fields (e.g., Nomencla-
ture.Code) can be used. The  SELECT element can only be included in  the first
query of a  union.
Example:
{SELECT Nomenclature, Warehouse}

WHERE
Description:
It describes the fields where the user can apply filtering. This  clause uses table
fields. Selection list field aliases are not allowed. Each union part can contain its
own WHERE element.
If no parameter values are specified, the WHERE clause is  no included in  the
resulting query.
Example:
{WHERE Nomenclature.*, Warehouse }
{WHERE Document.Date >= &BeginDate, Document.Date <= &EndDate}

CHARACTERISTICS

Description:
In order to support work with characteristics in  the query language extension
for the data composition system, characteristics description syntax has been
introduced.
The above example describes the characteristics of Ref fields in  the Nomen-
clature catalog.
Characteristics describe the following properties:
„„ TYPE – the name of the type for which characteristics are described;
1-546 1C:Enterprise 8.3. Developer Guide

„„ CHARACTERISTICTYPES – a  name of the table or a  query to obtain a  list

of characteristics. ALLOWED keyword is  allowed in  the query. In  this case,
a  list of characteristics will only contain the characteristics that are avail-
able to the user, in  line with the applicable data access limitations.
If a  list of characteristics is  specified by a  table name instead of a  query,
the ALLOWED keyword is  also used in  the system generated query to obtain
a  list of characteristics.
„„ ID – the name of the field that contains the characteristic ID;
„„ NAME – the name of the field that contains the characteristic name;
„„ VALUETYPE – the name of the field that contains the characteristic value
type. If no value type is specified, the characteristic is assigned the
Boolean type;
„„ VALUES – a  table name or a  query to obtain values of characteristics;
„„ OBJECT – the name of the field that contains the object ID (e.g., a  product
reference);
„„ CHARACTERISTIC – the name of the field that contains the characteristic ID;
„„ VALUE – the name of the field that contains the characteristic value; If
it  is  not specified, the value is  True (if an object has this characteristic);
otherwise the value is  False.
Example:
{CHARACTERISTICS TYPE(Catalog.Nomenclature)
LIST (SELECT
OptionTypes.Ref,
OptionTypes.Description,
OptionTypes.ValueType
FROM
ChartOfCharacteristicTypes.OptionTypes AS OptionTypes)
ID Ref
NAME Description
VALUETYPE ValueType
VALUES InformationRegister.Options
OBJECT Nomenclature
CHARACTERISTIC PropertyType
VALUE Property
}

Parameters
Description:
Besides the main elements, the data composition system can receive elements
written in  virtual table parameters. In  this case the field type depends on the
type of the parameter that contains the elements.
Chapter 10. Data Composition System 1-547

BeginDate, EndDate, Nomenclature and Warehouse fields (see the example

below) become available for filtering, i.e. the user can apply filters to them.
Example:
SELECT
NomenclatureAccountingTurnovers.Nomenclature AS Nomenclature,
NomenclatureAccountingTurnovers.Warehouse AS Warehouse,
NomenclatureAccountingTurnovers.QuantityReceipt AS QuantityReceipt,
NomenclatureAccountingTurnovers.QuantityExpense AS QuantityExpense,
FROM
AccumulationRegister.NomenclatureAccounting.Turnovers({&BeginDate},
{&EndDate},
,
{Nomenclature.*,
Warehouse.*}) AS NomenclatureAccountingTurnovers

10.3.3.2. Auto Fill of Available Fields

The following is  performed when available query fields are auto-filled:
„„ All selection list fields and their child fields become available for filtering
ordering, grouping, selecting, etc.
„„ Virtual table parameters become available for filtering.

10.3.4. Data composition system expression language

The data composition system expression language is  intended to create expressions
used throughout the system.
Expressions are used in  the following subsystems:
„„ Data composition schema – to describe calculated fields, total fields, link
expressions, etc.
„„ Data composition settings – to describe custom field expressions.
„„ Data composition template – to describe data set link expressions, template
parameter descriptions, etc.
NOTE
Data composition expression language does not support getting a  field from the
expression using dot operator.

10.3.4.1. Literal constants

An expression may contain literals of the following types.

Line
Description:
A string literal is  enclosed in  double quotation marks (").
1-548 1C:Enterprise 8.3. Developer Guide

If you need to use double quotation marks (""") within a  string literal, use two
double quotation marks.
Example:
"Literal""in quotation marks"""

Number
Description:
A number is written without spaces, in decimal format. Its fractional part
is  separated by a  period (".").
Example:
10.5
200

Date
Description:
A date literal is written using the DATETIME keyword. This keyword
is  followed by a  year, month, day, hours, minutes, and seconds separated by
commas. It  is  not necessary to specify the time.
Example:
January sixth, 1975
DATETIME(1975, 1, 06)

// The  second of December, 2006, 23 hours, 56 minutes, 57 seconds

DATETIME(2006, 12, 2, 23, 56, 57)

Boolean
Description:
Boolean values may be written with True and False literals.

Value
Description:
To specify literals of other types (system enumerations, preset data), use the
Value keyword followed by the literal name in  brackets.
Example:
VALUE(AccountType.Active)
Chapter 10. Data Composition System 1-549

Fields
Description:
Expressions may contain dataset fields. A field is identified by a data path.
Parts of a  data path are separated by ".". Field names are not case sensitive. If
a  data path contains an identifier with spaces or special characters, such identi-
fiers should be enclosed in  brackets.
Example:
Nomenclature.Articul
Sales.AmountTurnover
Sales.[Amount turnover]

Parameters
Description:
Expressions may use parameters. To use a  parameter in  an expression, write
its name preceded by &.
Example:
&Contractor
&StartDate

Type

Description:
Creates a  value of type Type. A type is  set with the help of the Type keyword.
Example:
Type("String")

10.3.4.2. Operations with numbers

Unary "-"

Description:
This operation changes the sign of a  number to its opposite.
Example:
-Sales.Count
1-550 1C:Enterprise 8.3. Developer Guide

Unary "+"
Description:
This operation does not perform any actions with the number.
Example:
+Sales.Count

Binary "-"
Description:
This operation calculates the difference between two numbers.
Example:
BalanceAndTurnovers.OpeningBalance - BalanceAndTurnovers.ClosingBalance
BalanceAndTurnovers.OpeningBalance - 100
400 - 357

Binary "+"
Description:
This operation calculates a  total of two numbers.
Example:
BalanceAndTurnovers.OpeningBalance + BalanceAndTurnovers.Turnover
BalanceAndTurnovers.OpeningBalance + 100
400 + 357

Multiplication "*"
Description:
This operation multiplies two numbers.
Example:
Nomenclature.Price * 1.2
2 * 3.14

Division "/"
Description:
This operation divides one operand by another.
Example:
Nomenclature.Price / 1.2
2 / 3.14
Chapter 10. Data Composition System 1-551

Remainder from division "%"

Description:
This operation retrieves a  remainder from dividing one operand by another.
Example:
Nomenclature.Price % 1.2
2 % 3.14

10.3.4.3. String operations

Concatenation (Binary "+")
Description:
This operation is  intended for concatenation of two rows.
Example:
Nomenclature.Articul + ": " + Nomenclature.Description

LIKE
Description:
This operation checks if a  string matches the transferred template.
The value of the LIKE operator is  True if the Expressions value matches the
template or False otherwise.
The following characters in  a template line have a  meaning that is  different
from their meaning in  a simple sequence of characters:
„„ "%" (per cent): a  sequence containing zero and more random characters.
„„ "_" (underscore): one random character;
„„ "[…]" (one or multiple characters in  square brackets): one character of those
in  the square brackets. Ranges can be listed as well, such as a-z. This  means
a  random character within the range, both ends of the range included;
„„ "[^…]" (square brackets containing a  negation character followed by one or
multiple characters): any character but those that follow the negation character;
Any other character represents itself only and does not have any additional use.
If you need to use one of the above characters as a  simple character, it  should
be preceded by ESCAPE.
For instance, the template below means a  substring that consists of a  sequence
of characters:
„„ letter A
„„ letter B
1-552 1C:Enterprise 8.3. Developer Guide

„„ letter C
„„ one number
„„ one of the letters: a, b, c or d
„„ an underscore
„„ letter a
„„ letter b
„„ letter c
The sequence may start anywhere within a  string.
Example:
"%ABC[0-9][abcd]\_abc%" ESCAPE "\"

10.3.4.4. Comparison operations

Equal (=)

Description:
This operation is  intended to compare two operands for equality.
Example:
Sales.Contractor = Sales.NomenclatureMainSupplier

Not Equal (<>)

Description:
This operation is  intended to compare two operands for inequality.
Example:
Sales.Contractor <> Sales.NomenclatureMainSupplier

Less (<)
Description:
This operation is  intended to check that the first operand is  less than the second
one.
Example:
CurrentSales.Total < PreviousSales.Total
Chapter 10. Data Composition System 1-553

Greater (>)
Description:
This operation is  intended to check that the first operand is  greater than the
second one.
Example:
CurrentSales.Total > PreviousSales.Total

Less or Equal (<=)

Description:
This operation is  intended to check that the first operand is  less than or equal
to the second one.
Example:
CurrentSales.Total <= PreviousSales.Total

Greater or Equal (>=)

Description:
This operation is intended to check that the first operand is greater than or
equal to the second one.
Example:
CurrentSales.Total >= PreviousSales.Total

Operation (IN)
Description:
This operation is  intended to check the presence of a  value in  the list of passed
values. The  operation returns True if the value is  found or False otherwise.
Example:
Nomenclature IN (&Product1, &Product2)

Operation to check value presence in  data set (IN)

Description:
This operation is  intended to check value presence in  the specified data set.
The  data set for checking must contain one field.
Example:
Sales.Contractor IN Contractors
1-554 1C:Enterprise 8.3. Developer Guide

Operation to check NULL value (IS NULL)

Description:
This operation returns True, if it  is  NULL.
Example:
Sales.Contractor IS NULL

Operation to check non-NULL value (IS NOT NULL)

Description:
This operation returns True, if it  is  not NULL.
Example:
Sales.Contractor IS NOT NULL

10.3.4.5. Boolean operations

Boolean operations use Boolean expressions as their operands.

NOT operation

Description:
NOT operation returns True, if its operand is equal to False, and it returns
False, if its operand is  equal to True.
Example:
NOT Document.Consignee = Document.Shipper

AND operation
Description:
AND operation returns True, if both operands are TRUE, and False, if one of the
operands is  False, for instance:
Example:
Document.Consignee = Document.Shipper AND Document.Consignee = &Contractor

OR operation
Description:
OR operation returns True, if one of the operands is  True, and False, if both
operands are False.
Chapter 10. Data Composition System 1-555

Example:
Document.Consignee = Document.Shipper OR Document.Consignee = &Contractor

10.3.4.6. Aggregate functions

Aggregate functions perform certain actions on a  set of data.

SUM
Syntax:
Total (Expression)
Description:
The Total aggregate function calculates a total of expression values passed
as an argument for all detailed records. You can pass Array as a  parameter.
In  this case the function will be applied to the array content.
Example:
TOTAL(Sales.SumTurnover)

COUNT

Syntax:
Count(Expression)
Description:
The Count function calculates the number of non-NULL values. You can pass
Array as a parameter. In this case the function will be applied to the array
content.
Example:
COUNT(Sales.Contractor)

COUNT (DISTINCT)
Syntax:
Count(Distinct expression)
Description:
This function calculates the number of different values. To obtain different
values, specify Distinct before the Count method parameter. You can pass
Array as a parameter. In this case the function will be applied to the array
content.
1-556 1C:Enterprise 8.3. Developer Guide

Example:
COUNT(Distinct Sales.Contractor)

MAX
Syntax:
Max(Expression)
Description:
This function obtains the maximum value. You can pass Array as a  parameter.
In  this case the function will be applied to the array content.
Example:
MAXIMUM(Balance.Count)

MIN
Syntax:
Minimum(Expression)
Description:
This function gets the minimum value. You can pass Array as a  parameter.
In  this case the function will be applied to the array content.
Example:
MINIMUM(Balance.Count)

AVG
Syntax:
Avg(Expression)
Description:
This function gets the mean value for non-NULL values. You can pass Array as
a  parameter. In  this case the function will be applied to the array content.
Example:
AVERAGE(Balance.Count)

ARRAY
Syntax:
Array([Distinct] Expression)
Description:
This function creates an array that includes an expression value for each detailed
record.
Chapter 10. Data Composition System 1-557

You can use a  value table as a  parameter. Note that in  this case the function
results in  an array containing the values of the first column of the value table
passed as a  parameter.
If an expression includes the Array function, this expression is  considered to
be an aggregate expression.
If the Distinct keyword is specified, the retrieved array will not include
duplicate values.
Example:
ReportFunctions.StandardDeviation(Array(Sum))

VALUETABLE
Syntax:
ValueTable([Distinct] Expression1 [AS ColumnName1][, Expres-
sion2 [AS ColumnName2]], ...])

Description:
The function generates a  table of values with the number of columns equal to
the number of function parameters. Detailed records are retrieved from data sets
that are required to compute all the expressions specified as function parameters.
If residual fields are used as function parameters, the resulting value table
will include values for the entries by unique sets of measurements from other
periods. Note that values are only obtained for residual fields, measurements,
accounts, period fields and their attributes. The values of other fields in the
entries from other periods are considered NULL.
If an expression includes the ValueTable function, this expression is  consid-
ered to be an aggregate expression.
If the Distinct keyword is  specified, the retrieved value table will not include
rows with duplicate data.
Use the AS keyword that follows an expression used in order to create
a  column value to specify a  name for each column.
Example:
ReportFunctions.ValueTableToString(ValueTable(Inventory AS Inventory, QuantityBalance AS Balance))

GROUPBY
Syntax:
GroupBy(<Expression>, <ColumnNumbers>)
Description:
This function removes duplicates from an array.
1-558 1C:Enterprise 8.3. Developer Guide

Parameters:
<Expression>
Type: Array or ValueTable. Duplicates are deleted for the value located in  this
formal parameter.
<ColumnNumbers>
String type. Is used if the Expression parameter is  of the ValueTable type.
Numbers or names (comma-separated) of the value table columns where dupli-
cates should be searched for. By default, this includes all columns.
Example:
GroupBy(ValueTable(PhoneNumber, Address) ,"PhoneNumber").

GETPART
Syntax:
GetPart(<Expression>, <ColumnNumbers>)
Description:
The function obtains a value table that contains specific columns from the
original value table.
Parameters:
<Expression>
Type: ValueTable. The  table of values that the columns should be retrieved
from.
<ColumnNumbers>
String type. Numbers or names (comma-separated) of the value table columns
that should be retrieved.
Returned value:
A table of values that contains only the columns specified in  ColumnNumbers
parameter.
Example:
GetPart(GroupBy(ValueTable(PhoneNumber, Address) ,"PhoneNumber"),"PhoneNumber").

ORDER
Syntax:
GroupBy(<Expression>, <ColumnNumbers>)
Description:
Intended to order the items of an array and value table.
Chapter 10. Data Composition System 1-559

Parameters:
<Expression>
Type: Array or ValueTable. An object to be ordered.
<ColumnNumbers>
Is used if the Expression parameter is  of the ValueTable type. Numbers or
names (comma-separated) of the value table columns that should be ordered.
By default, this includes all columns.
Order direction or an automatic ordering attribute may be placed after each
column.
Returned value:
An array or a  table of values ordered in  accordance with the transferred param-
eters.
Example:
Order(ValueTable(PhoneNumber, Address, CallDate),"CallDate Desc").

JOINSTRINGS
Syntax:
JoinStrings(<Values>, <ItemSeparator>, <ColumnSeparator>)
Description:
Intended to join multiple strings into a  single string.
Parameters:
<Values>
Values, the string presentations of which should be joined into a  single string.
If it is an Array, array items will be joined into a  string. If it  is  a ValueTable,
all the table columns and rows will be joined into a  string.
<ItemSeparator>
String type. Contains a  text to be used as a  separator between array items and
the rows of a  value table. By default, it  is  a line feed character.
<ColumnSeparator>
String type. Contains a  text to be used as a  separator between the columns
of a  value table. By default it  is  ";".
Returned value:
Joined string.
Example:
JoinStrings(ValueTable(PhoneNumber, Address)).
1-560 1C:Enterprise 8.3. Developer Guide

GROUPPROCESSING
Syntax:
GroupProcessing(<Expressions>, <HierarchyExpressions>,
<GroupName>)
Description:
A table of values is created that contains the parameter values (in columns)
for each group entry (in rows). If hierarchical grouping is  used, each hierarchy
level is processed separately. The values of hierarchical records are also
included in  a data table. In  a returned object, this table of values will be located
in the Data property.
The CurrentItem property will hold the row (of the value table being trans-
ferred) for which the function is  currently calculated.
When implementing a  function that can take group processing data as param-
eter, please note that NULL value can be transferred to the function as a  value.
This  may happen, for instance, if the GroupProcessing() function is  calcu-
lated and the name of the group that is  currently unavailable is  specified.
Parameters:
<Expressions>
The string listing the comma-separated expressions to be calculated. Each
expression may be followed by the optional AS keyword and a  column name of
the resulting value table. Each expression describes a  column of the value table
being created.
<HierarchyExpressions>
The expressions to be calculated for hierarchical records. This is similar to
the Expressions parameter with the only difference being that Expressions
parameter is  used for non-hierarchical records, and HierarchyExpressions
is used for hierarchical records. If the parameter is omitted, the expressions
specified in the Expression parameter are used to calculate the values for
hierarchical records.
<GroupName>
Name of the group to calculate processing grouping in. If this is  omitted, calcu-
lations are carried out in  the current grouping. If a  calculation is  performed
on a table and the parameter includes a null string or is blank, the value
is calculated for the row grouping. When the data composition template
is  generated, the template composer replaces this name with the grouping name
in  the resulting template. If the grouping is  not available, the function will be
replaced with NULL.
Chapter 10. Data Composition System 1-561

Returned value:
DataCompositionGroupProcessingData object.
Example:
An example of how the ABCClassification() function can be implemented.
This function returns 1 if the value reaches 75% of the total amount; 2,
if it  reaches between 75% and 95%; and 3 in  other cases.
// Calculate ABC classification.
Function ABCClassification(Data) Export
Var ValueTable;

If Data = Null Then

Null is  returned;
EndIf;

If ValType (Data) <> Type ("DataCompositionGroupProcessingData") Then

Message(ValType(Data));
ThrowException "Only an object of type DataCompositionGroupProcessingData can be transferred
to function ABCClassification()";
EndIf;

If not data.ProcessingTempData.Property("ABCClassificationValueTable", ValueTable) Then

// calculate the classification once during the first call
// and then remember the calculation made and use this
// calculation afterwards
ValueTable = Data.Data.Copy();
ValueTable.Columns.Add("Number", New TypeDescription("Number"));
Number = 0;
CommonAmount = 0;
For Each ValueTableString From ValueTable Cycle
ValueTableString.Number = Number;
Number = Number + 1;

If ValueTableString[0] <> NULL Then

CommonAmount = CommonAmount + ValueTableString[0];

EndIf;

EndLoop;

ValueTable.Sort(ValueTable.Columns[0].Name + " Desc");

ValueTable.Indexes.Add("Number");
CumulativeAmount = 0;
IndexOfClassA = Undefined;
IndexOfClassB = Undefined;
For Each ValueTableString From ValueTable Cycle

If ValueTableString[0] <> NULL Then

CumulativeAmount = CumulativeAmount + ValueTableString[0];

EndIf;

If CommonAmount = 0 Then

Percent = 1;
1-562 1C:Enterprise 8.3. Developer Guide

Else

Percent = CumulativeAmount / CommonAmount

EndIf;

If percent > 0.75 Then

If IndexOfClassA = Undefined Then
IndexOfClassA = ValueTable.Index(ValueTableString);
ElseIf Percent > 0.90 Then
If IndexOfClassB = Undefined Then
IndexOfClassВ = ValueTable.Index(ValueTableString);
EndIf;
Abort;
EndIf;
EndIf;
EndLoop;

Data.ProcessingTempData.Insert("ABCClassificationValueTable", ValueTable);
Data.ProcessingTempData.Insert("ABCClassificationIndexOfClassA", IndexOfClassA);
Data.ProcessingTempData.Insert("ABCClassificationIndexOfClassB", IndexOfClassB);
EndIf;

If Data.CurrentItem = Undefined Then

// GroupTotal.
Null is  returned;

Else

String = ValueTable.Find(Data.Data.Index(Data.CurrentItem), "Number");

If String = Undefined Then

Null is 
returned;

Else

Index = ValueTable.Index(String);

If Index <= Data.ProcessingTempData.ABCClassificationIndexOfClassA Then

1 is  returned;

ElseIf Index <= Data.ProcessingTempData.ABCClassificationIndexOfClassB Then

2 is  returned;

Else

3 is  returned;

EndIf;

EndIf;

EndIf;
EndFunction
Chapter 10. Data Composition System 1-563

The following expression can be used in  a composition expression to obtain

a  class (in a  resource or a  user field, for instance):
ABCClassification(GroupProcessing("Sum(SumTurnover)"))

EVERY
Syntax:
Every(<X>)
Description:
The Every aggregate function determines whether a  set transferred contains at
least one False value.
Returned value:
True – if the set transferred contains no False value.
False – if the set transferred contains at least one False value.
ANY
Syntax:
Any(<X>)
Description:
The Any aggregate function determines whether a set transferred contains at
least one True value.
Returned value:
True – if the set transferred contains at least one True value.
False – if the set transferred contains no True value.

STDDEV_POP
Syntax:
STDDEV_POP(<X>)
Description:
Calculates a  standard deviation of the general aggregate of the set transferred.
Calculation is  based on the following formula: SQRT(VAR_POP(X)).
Returned value:
Result.

STDDEV_SAMP
Syntax:
STDDEV_SAMP(<X>)
1-564 1C:Enterprise 8.3. Developer Guide

Description:
Calculates a  standard deviation of a  selection of the set transferred.
The calculation is  based on the following formula: SQRT(VAR_SAMP(X)).
Returned value:
Result.

VAR_SAMP

Syntax:
VAR_SAMP(<X>)

Description:
Calculates the selected dispersion for the set transferred.
Calculation is based on the following formula: (SUM(X^2)-SUM(X)^2/
COUNT(X))/(COUNT(X)-1). If the number of entries in a set is equal to 1
(COUNT(X)=1), the returned value is  NULL.
Returned value:
Result.
VAR_POP
Syntax:
VAR_POP(<X>)

Description:
Calculates a  general aggregate dispersion for the set transferred. NULL values
are ignored.
The calculation is based on the following formula: (SUM(X^2)-SUM(X)^2/
COUNT(X))/(COUNT(X)).

Returned value:
Result.

COVAR_POP
Syntax:
COVAR_POP(<Y>, <X>)

Description:
Calculates the covariation of aggregated multiple pairs of the sets transferred.
Chapter 10. Data Composition System 1-565

The calculation is based on the following formula: (SUM(Y*X)-SUM(X)*-

SUM(Y)/N)/N. N is the number of X and Y value pairs from the sets transferred,
where neither X nor Y is  equal to NULL. Pairs that have at least one NULL value
are ignored.
Returned value:
Result.
COVAR_SAMP
Syntax:
COVAR_SAMP(<Y>, <X>)
Description:
Calculates a  sample covariation of multiple pairs of the sets transferred.
The calculation is based on the following formula: (SUM(Y*X)-SUM(Y)*-
SUM(X)/N)/(N-1). N is the number of X and Y value pairs from the sets
transferred, where neither X nor Y is  equal to NULL. Pairs that have at least one
NULL value are ignored.
Returned value:
The result of calculation or NULL if the function is  applied to empty sets.

CORRELATION
Syntax:
Correlation(<Y>, <X>)

Description:
Calculates the covariation coefficient of multiple pairs of the sets transferred.
Calculation is based on the following formula: COVAR_POP(Y,X)/(STDDEV_
POP(Y)*STDDEV_POP(X)). Pairs that have at least one NULL value are ignored.
Returned value:
The result of calculation or NULL if the function is  applied to empty sets.

REGR_SLOPE
Syntax:
RegressionSlope(<Y>, <X>)

Description:
Calculates the line slope.
Calculation is  based on the following formula: Covar_Pop(Y,X)/Var_Pop(X).
Pairs that have at least one NULL value are ignored.
1-566 1C:Enterprise 8.3. Developer Guide

Returned value:
Result.
REGR_INTERCEPT
Syntax:
REGR_INTERCEPT(<Y>, <X>)
Description:
Calculates the Y intercept of the regression line.
Calculation is based on the following formula: Average(Y)- Regr_Slope
(Y, X) * Average(X). Pairs that have at least one NULL value are ignored.
Returned value:
Result.
REGR_COUNT
Syntax:
REGR_COUNT(<Y>, <X>)
Description:
Calculates the number of pairs without NULL.
Returned value:
Result. 9
REGR_R2
Syntax:
REGR_R2(<Y>, <X>)
Description:
Calculates a determination coefficient for the regression. The function
is  calculated without taking into account value pairs that contain NULL value.
Returned value:
„„ NULL, if Var_Pop(X) is  equal to 0.
„„ 1, if Var_Pop Y) is  0 and Var_Pop(X) is  not equal to 0.
„„ Pow(Corr(Y,X),2), if Var_Pop(Y) is  more than 0 and Var_Pop(X) is  not
equal to 0.
REGR_AVGX
Syntax:
REGR_AVGX(<Y>, <X>)
Chapter 10. Data Composition System 1-567

Description:
Calculates an average of independent variables <X> for a  regression line after
the pairs where at least one value is  NULL are excluded.
The calculation is  based on the following formula: Average(X).
Returned value:
Result.
REGR_AVGY
Syntax:
REGR_AVGY(<Y>, <X>)

Description:
Calculates an average of dependent variables <Y> for a  regression line after the
pairs where at least one value is  NULL are excluded.
The calculation is  based on the following formula: Average(X).
Returned value:
Result.
REGR_SXX
Syntax:
REGR_SXX(<Y>, <X>)
Description:
Performs a calculation using the following formula: Regr_Count(Y, X) *
Var_Pop(X). Pairs that have at least one NULL value are ignored.

Returned value:
Result.

REGR_SYY
Syntax:
REGR_SYY(<Y>, <X>)

Description:
Performs a calculation using the following formula: Regr_Count(Y, X) *
Var_Pop(Y). Pairs that have at least one NULL value are ignored.

Returned value:
Result.
1-568 1C:Enterprise 8.3. Developer Guide

REGR_SXY
Syntax:
REGR_SXY(<Y>, <X>)

Description:
Performs a calculation using the following formula: Regr_Count(Y, X) *
Covar_Pop(Y, X). Pairs that have at least one NULL value are ignored.

Returned value:
Result.
RANK
Syntax:
Rank(<Order>, <HierarchyOrder>, <GroupName>)

Description:
The function defines which place the current record should take among the
current group records if sorted in  the order specified in  the function’s parame-
ters. Numbering starts at 1.
Parameters:
<Order>
String type. Contains statements that should have their comma-separated
group records ordered in  their sequence. The  ordering direction is  managed by
Asc, Desc words. The  field may also be followed by AutoOrder string which
means that ordering fields specified for the referenced object should be used
for reference ordering. If the sequence is  not specified, the value is  calculated
in  the grouping sequence.
<HierarchyOrder>
String type. A string that contains ordering expressions for hierarchical
records.
<GroupName>
String type. Name of the group in which to calculate the function.
If omitted, calculations are carried out in  the current grouping. If the calculation
is  performed in  a table, and the parameter contains an empty string or is  not
specified, the value is  calculated for a  group string. When the data composi-
tion template is  generated, the template composer replaces this name with the
grouping name in  the resulting template. If the grouping is  not available, the
function will be replaced with NULL.
Chapter 10. Data Composition System 1-569

Returned value:
Ordered number. If a  sequence includes multiple records with identical values
of ordering fields, the function will return identical values for all such records.

CLASSIFICATIONABC

Syntax:
ClassificationABC(<Value>, <GroupCount>, <PercentageFor-
Groups>, <GroupName>)

Description:
Performs an ABC classification of each record in  the group.
Parameters:
<Value>
String type. Specifies a value for which the classification should be calcu-
lated.
<GroupCount>
Type: Number. The  number of groups into which to separate a  value set.
<PercentsForGroups>
String type. The volume (%) of each split group, except for the last one.
Listed in  a row and separated by comma.
<GroupName>
String type. Name of the group in which to calculate the function.
If omitted, calculations are carried out in  the current grouping. If a  calculation
is  performed on a  table and the parameter includes a  null string or is  blank,
the value is calculated for the rows grouping. When the data composition
template is generated, the template composer replaces this name with
the grouping name in  the resulting template. If the grouping is  not available,
the function will be replaced with NULL.
Returned value:
Class number 1 corresponds to class A, 2 – class B, 3 – class C, etc.
Example:
ClassificationABC(SumTurnover, 3, "15, 25")
1-570 1C:Enterprise 8.3. Developer Guide

10.3.4.7. Other operations

CHOICE operation
Description:
The CHOICE operation is  used to select one of the multiple values under certain
conditions.
Example:
CHOICE When Sum > 1000 Then Sum Else 0 End

10.3.4.8. Rules for comparing two values

If compared values are of different types, the relationship between them is  defined
by priority type:
„„ NULL (the lowest)
„„ Boolean
„„ Number
„„ Date
„„ String
„„ reference types
Relationships between different reference types are defined based on the table
reference numbers corresponding to a  specific type.
If the data types are the same, their values are compared based on the following
rules:
„„ For the Boolean type, True is  more than False.
„„ For the Number type, standard rules of number comparison apply.
„„ For the Date type, earlier dates are less than later dates.
„„ For the String type, strings are compared according to the national database
parameters.
„„ Reference types are compared based on their values (record number, etc.).

10.3.4.9. Working with NULL value

Any operation where one of the operands is  NULL will result in  a NULL value.
The exceptions are:
„„ AND will return NULL only if none of the operands is  False.
„„ OR will return NULL only if none of the operands is  True.
Chapter 10. Data Composition System 1-571

10.3.4.10. Operation priorities

Operations have the following priorities (from the lowest to the highest priority):
„„ OR
„„ AND
„„ NOT
„„ IN, IS NULL, IS NOT NULL
„„ =, <>, <=, <, >=, >
„„ Binary +, Binary -
„„ *, /, %
„„ Unary +, Unary -

10.3.4.11. Functions
EVAL
Syntax:
Eval(<Expression>,<Grouping>,<CalculationType>)

Description:
The Eval function is  used to evaluate expressions within a  certain grouping.
Parameters:
<Expression>
A string that contains the expression to be calculated.
<Grouping>
A string that contains the name of a  grouping within which the expression is  to
be evaluated. If an empty string is used as a grouping name, the evaluation
will be performed within the context of the current grouping. If the Overall
string is  used as a  grouping name, the evaluation will be performed within the
context of the grand total. Otherwise, the evaluation will be performed in  the
context of the parent grouping with this name.
<CalculationType>
A string that contains a type of calculation. If this parameter is Overall,
the expression will be evaluated for all the records of the grouping. When the
parameter value is  Grouping, the values will be calculated for the current
group record of the grouping.
1-572 1C:Enterprise 8.3. Developer Guide

Example:
Total(Sales.SumTurnover) / EVAL("Total(Sales.SumTurnover)", "Overall")

In this example, the result will be the ratio of the total by the Sales.SumTurn-
over field of the grouping record to the total of the same field in  the entire
composition.

EVALEXPRESSION
Syntax:
EvalExpression(<Expression>, <Grouping>, <Calculation-
Area>, <Begin>, <End>, <Sorting>, <HierarchicalSorting>,
<ProcessingSimilarOrderValues>)
Description:
The function is  used to evaluate expressions within a  certain grouping.
The function takes filters of the groups into account but ignores hierarchical
filters.
The function cannot be applied to a  group in  a group filter for this group. For
example, in  a filter of the Nomenclature group you should not use the expres-
sion EvalExpression("Total(SumTurnover)", , "Overall") > 1000.
However, this expression can be used in  a hierarchical filter.
If the end record is  located before the beginning one, there are considered to be
no records to calculate the detailed data and aggregate functions.
When you calculate the interval expressions for overalls (the Grouping param-
eter is  Overall), there are considered to be no records to calculate the detailed
data and aggregate functions.
When the template composer generates an expression for the EvalExpression
and the sorting expression contains fields that can be used in  a grouping, the
EvalExpression function is  replaced with NULL.

Parameters:
<Expression>
String type. An expression to be calculated.
<Grouping>
String type. Contains a  name of a  grouping within which the expression is  to
be evaluated. If an empty string is used as a grouping name, the evaluation
will be performed within the context of the current grouping. If the Overall
string is  used as a  grouping name, the evaluation will be performed within the
context of the grand total. Otherwise, the evaluation will be performed in  the
context of the parent grouping with this name.
Chapter 10. Data Composition System 1-573

Example:
Total(Sales.SumTurnover) / Eval("Total(Sales.SumTurnover)", "Overall")

In this example, the result will be the total of the Sales.SumTurnover field of
the grouping record divided by the total of the same field in  the entire compo-
sition.
<CalculationArea>
String type. The  parameter may take the following values:
„„ Overall – the expression is  calculated for all group entries.
„„ Hierarchy – the expression should be calculated for the parent hierarchical
record, if any, or for the entire group if there is no parent hierarchical
record.
„„ Grouping – the expression is  calculated for the current group record of the
grouping.
„„ GroupingNotResource – when the function is calculated for a group
record by resources, the expression will be calculated for the first group
record of the original grouping.
When the EvalExpression() function is calculated with the Grou-
pingNotResource value for group records that are not grouped by
resources, the function is  calculated in  the same manner as it  is  calculated
with Grouping for the parameter value.
When a data composition template is created to output fields of the
resource to group by to the template, data composition template composer
puts an expression calculated via EvalExpression() function to the
template and specifies NotResourceGroup parameter. For the remaining
resources, standard resource expressions are added to the group by resource.
<Start>
String type. Specifies which record should be used to begin the portion where
the aggregate expression functions should be calculated and what record should
be used to retrieve field values outside of aggregate functions. It  can take the
following values:
„„ First. The  first record of the group should be retrieved. The  word may
be followed by an expression in brackets with the result used as a shift
from the group beginning. The  resulting value should be a  positive integer.
Example: First(3) means that the third value from the group beginning
is retrieved.
If the first record is outside of the group, there are considered to be no
records. For example, when there are 3 records and you need to retrieve
First(4), it  is  assumed that there are no records.
1-574 1C:Enterprise 8.3. Developer Guide

„„ Last. The last record of the group should be retrieved. The word may

be followed by an expression in brackets with the result used as a shift
from the group end. The resulting value should be a positive integer.
For example: Last(3) means that the third value from the group end
is retrieved.
If the last record is outside of the group, there are considered to be no
records. For example, when there are 3 records and you need to retrieve
Last(4), it  is  assumed that there are no records.
„„ Previous. The  previous record of the group should be retrieved. The  word
may be followed by an expression in  brackets with the result used as a  shift
back from the current record of the group. For example: Previous(2)
retrieves the record that is  located prior to the previous one.
If the previous record is  outside of the group (e.g., for the second group
record you need to get Previous(3)), the first group record is  retrieved.
When the previous record for a group total is retrieved, the first record
is retrieved.
„„ Next. The next record of the group should be retrieved. The word may
be followed by an expression in brackets with the result used as a shift
forward from the current record of the group. For example: Next(2)
retrieves the record that follows the next one.
If the next record is outside of the group, there are considered to be no
records. For example, when there are 3 records and you need to retrieve
Next() for the third record, it  is  assumed that there are no records.
When the next record for a  group total is  retrieved, there are considered to
be no records.
„„ Current. The  current record should be retrieved.
When you are retrieving for a  group total, the first record is  retrieved.
„„ BoundaryValue. A record should be retrieved based on a specified
value. The  BoundaryValue keyword may be followed by an expression
in  brackets with its value used to start the portion of the first sorting field.
The first record that has its sorting field equal to or greater than the speci-
fied value will be retrieved as a  record. For example, if Period is  used as
a  sorting field, its values are 01/01/2010, 02/01/2010, 03/01/2010, and you
need to retrieve BoundaryValue(DateTime(2010, 1, 15)), the record
with the date 02/02/2010 will be retrieved.
<End>
String type. Specifies the record that should be the last one in the portion
to be used to calculate aggregate functions of the expression. It  can take the
following values:
„„ First. The  first record of the group should be retrieved. The  word may
be followed by an expression in brackets with the result used as a shift
Chapter 10. Data Composition System 1-575

from the group beginning. The  resulting value should be a  positive integer.
For example: First(3) means that the third value from the group’s start
is retrieved.
If the first record is outside of the group, there are considered to be no
records. For example, when there are 3 records and you need to retrieve
First(4), it  is  assumed that there are no records.
„„ Last. The last record of the group should be retrieved. The word may
be followed by an expression in brackets with the result used as a shift
from the group end. The resulting value should be a positive integer.
For example: Last(3) means that the third value from the group end
is retrieved.
If the last record is outside of the group, there are considered to be no
records. For example, when there are 3 records and you need to retrieve
Last(4), it  is  assumed that there are no records.
„„ Previous. The  previous record of the group should be retrieved. The  word
may be followed by an expression in  brackets with the result used as a  shift
back from the current record of the group. For example: Previous(2)
retrieves the record that is  located prior to the previous one.
If the previous record is  outside of the group (e.g., for the second group
record you need to get Previous(3)), the first group record is  retrieved.
When the previous record for a group total is retrieved, the first record
is retrieved.
„„ Next. The next record of the group should be retrieved. The word may
be followed by an expression in brackets with the result used as a shift
forward from the current record of the group. For example: Next(2)
retrieves the record that follows the next one.
If the next record is outside of the group, there are considered to be no
records. For example, when there are 3 records and you need to retrieve
Next() for the third record, it  is  assumed that there are no records.
When the next record for a  group total is  retrieved, there are considered to
be no records.
„„ Current. The  current record should be retrieved.
When you are retrieving for a  group total, the first record is  retrieved.
„„ BoundaryValue. A record should be retrieved based on a specified
value. The  BoundaryValue keyword may be followed by an expression
in  brackets with its value used to end the portion of the first sorting field.
The first record that has its sorting field equal to or greater than the speci-
fied value will be retrieved as a  record. For example, if Period is  used as
a  sorting field, its values are 01/01/2010, 02/01/2010, 03/01/2010, and you
need to retrieve BoundaryValue(DateTime(2010, 1, 15)), the record
with the date 02/01/2010 will be retrieved.
1-576 1C:Enterprise 8.3. Developer Guide

<Sorting>
String type. Lists comma-separated expressions that describe ordering rules.
If not specified, ordering is performed in the same way as in the group for
which the expression is evaluated. The Asc (to sort by ascending order) or
Desc (to sort by descending order) and AutoOrder (to order reference fields by
the fields to be used to sort a  referenced object) keywords can be used after
each expression. AutoOrder can be used both with the Asc and Desc keywords.
<HierarchicalSorting>
String type. Similar to Sorting parameter. Used to sort hierarchical records.
If missing, the template composer generates a  sorting based on the value in  the
Sorting parameter.
<ProcessingSimilarOrderValues>
String type. Sets the rule to define a  previous or a  next record if there are
several records with the same ordering value:
„„ Separately – means that a  sequence of sorted records is  used to deter-
mine the previous and next records. This  is  the default value.
„„ Together – means that the previous and next records are defined based on
the sorting expression values.
For example, if a  retrieved sequence is  sorted by date:
№ Date Full name Value
1 January 01, 2001 M. Ivanov 10
2 January 02, 2001 S. Petrov 20
3 January 02, 2001 R. Sidorov 30
4 January 03, 2001 S. Petrov 40

If the parameter is  set to Separately, then:

○○ Record 2 will serve as the previous one for record 3.
○○ If a calculation fragment is defined as Current, Current (with
parameters Begin and End respectively), this fragment will only
contain one record (which is record 2) for record 2. Expression
EvalExpression("Total(Value)", , , Current, Current) will
be equal to 20.
If the parameter is  set to Together, then:
○○ Record 1 will serve as the previous one for record 3.
○○ If a  calculation fragment is  defined as Current, Current (with param-
eters Begin and End respectively, this fragment will contain records 2
and 3 for record 2. Expression EvalExpression("Total(Value)", ,
, Current, Current) will be equal to 50.
Chapter 10. Data Composition System 1-577

If a  parameter value equal to Together is  specified, do not specify offsets

for positions First, Last, Previous, Next in  Begin and End parameters.
Example:
If an amount with accumulation needs to be calculated, use the following
expression:
EvalExpression("Total(SumTurnover)", , , "First", "Current")

If you need to obtain a  grouping value in  the previous line, use the following
expression:
EvalExpression ("Rate", , , "Previous")

EVALEXPRESSIONWITHGROUPARRAY
Syntax:
EvalExpressionWithGroupArray (<Expression>, <GroupFieldsEx-
pressions>, <RecordsFilter>, <GroupFilter>)

Description:
The function retrieves an array with every item containing the result of calcu-
lating the expression for the group by the specified field.
When the template composer generates a  template, it  converts function param-
eters into data composition template field terms. For example, the Contractor
field will be converted into DataSet.Contractor.
When the template composer generates expressions to output a custom field
with an expression containing only EvalArrayWithGroupArray(), it will
generate the required expression so that the data display presentations are
sorted. For example, for a  custom field with the expression:
EvalExpressionWithGroupArray("Total(SumTurnover)", "Contractor")

the template composer will generate the following expression to be output:

JoinStrings(Array(Sort(EvalExpressionWithGroupValueTable ("Presentation(Total(DataSet.SumTurnover)),
Total(DataSet.SumTurnover)", "DataSet.Contractor"), "2")))

Parameters:
<Expression>
String type. An expression to be calculated. A string, for instance
Total(SumTurnover).
1-578 1C:Enterprise 8.3. Developer Guide

<GroupFieldsExpression>
String type. Group field expressions are comma-separated expressions of the
group fields. For example: Contractor, Batch.
<RecordsFilter>
String type. An expression that describes a  filter applied to detailed records.
For example, DeletionMark = False.
<GroupFilter>
String type. An expression that describes a filter applied to group records.
For example: Total(SumTurnover) > &Parameter1.
Example:
Maximum(EvalExpressionWithGroupArray ("Total(SumTurnover)", "Contractor")).

EVALEXPRESSIONWITHGROUPVALUETABLE
Syntax:
EvalExpressionWithGroupValueTable (<Expressions>, <GroupFi-
eldsExpressions>, <RecordsFilter>, <GroupFilter>)

Description:
The function retrieves a  table of values with every row containing the result of
calculating the expressions for the group by the specified field.
When the template composer generates a  template, it  converts function param-
eters into data composition template field terms. For example, the Contractor
field will be converted into DataSet.Contractor.
When the template composer generates expressions to output a custom field
with an expression containing only EvalArrayWithGroupValueTable(),
it  will generate the required expression so that the data display presentations
are sorted. For example, for a  custom field with the expression:
EvalExpressionWithGroupValueTable ("Contractor, Total(SumTurnover)", "Contractor")

the template composer will generate the following expression to be output:

JoinStrings(GetPart(Sort(EvalExpressionWithGroupValueTable ("DataSet.Contractor, dataSet

.ContractorPresentation, Total(DataSet.SumTurnover), Presentation(DataSet.SumTurnover),
DataSet.SortingField", "DataSet.Contractor"), "5, 1, 3"), "2, 4"))
Chapter 10. Data Composition System 1-579

Parameters:
<Expressions>
String type. The expressions to be calculated. The string may list multiple
comma-separated expressions. Each expression may be followed by an optional
AS keyword and the name of a  value table column. For example: Contractor,
Total(SumTurnover) AS SalesVolume.
<GroupFieldsExpression>
String type. Group field expressions are comma-separated expressions of the
group fields. For example: Contractor, Batch.
<RecordsFilter>
String type. An expression that describes a  filter applied to detailed records.
For example, DeletionMark = False.
<GroupFilter>
String type. An expression that describes a  filter applied to group records. For
example: Total(SumTurnover) > &Parameter1.
Example:
EvalExpressionWithGroupValueTable ("Contractor AS Contractor, Total(SumTurnover) AS SalesVolume", "Contractor")

The result of this function is a table of values that has columns named
Contractor and SalesVolume that will contain contractors with their respec-
tive volumes of sales.

LEVEL
Description:
This function is  intended to retrieve the current record level.
Example:
LEVEL()

LEVELINGROUP
Description:
The function is  used to retrieve the level of an entry in  relation to the group
root.
Example:
LEVELINGROUP()
1-580 1C:Enterprise 8.3. Developer Guide

VALUEISFILLED
Description:
Returns True, if the value differs from the value of another default type,
differs from NULL, from an empty link, and the Undefined value. NULL value
is checked for logical values. Strings are checked to verify whether they
contain any non-spacing characters.

SERIALNUMBER
Description:
This function retrieves the next sequence number.
Example:
SERIALNUMBER()

GROUPSERIALNUMBER
Description:
This function returns the next sequence number in  the current grouping.
Example:
GROUPSERIALNUMBER()

FORMAT
Description:
This function retrieves a  formatted string of the transferred value. The  format
string defined in  compliance with the 1C:Enterprise format string.
Parameters:
„„ Value
„„ Format string

Example:
FORMAT(Invoices.SumDoc, "NFD=2")

BEGINOFPERIOD
Description:
This function is  intended to extract a  specific date from a  given date.
Chapter 10. Data Composition System 1-581

Parameters:
„„ Expression of type Date.
„„ Type of period – a  string that contains one of the following values: Minute,
Hour, Day, Week, Month, Quarter, Year, Decade, HalfYear.
Example:
BEGINOFPERIOD(DateTime(2002, 10, 12, 10, 15, 34), "Month")

Result:
01.10.2002 0:00:00

ENDOFPERIOD
Description:
This function is  intended to extract a  specific date from a  given date.
Parameters:
„„ Expression of type Date.
„„ Type of period – a  string that contains one of the following values: Minute,
Hour, Day, Week, Month, Quarter, Year, Decade, HalfYear.
Example:
ENDOFPERIOD(DateTime(2002, 10, 12, 10, 15, 34), "Week")

Result:
13.10.2002 23:59:59

DATEADD

Description:
This function is  used to add a  value to a  date.
Parameters:
„„ Expression of type Date.
„„ Type of increment – a string that contains one of the following values:
Second, Minute, Hour, Day, Week, Month, Quarter, Year, Decade,
HalfYear.
„„ Size – specifies the value of date increment. Number type. Fractions are
ignored.
Example:
DATEADD(DateTime(2002, 10, 12, 10, 15, 34), "Month", 1)
1-582 1C:Enterprise 8.3. Developer Guide

Result:
12.11.2002 10:15:34

DATEDIFF
Description:
This function is  intended to obtain the difference between two dates.
Parameters:
„„ Expression of type Date.
„„ Expression of type Date.
„„ Type of difference – one of the values: Second, Minute, Hour, Day, Month,
Quarter, Year.
Example:
DATEDIFFERENCE(DATETIME(2002, 10, 12, 10, 15, 34),
DATETIME(2002, 10, 14, 9, 18, 06),
"DAY")

Result:
2

CURRENTDATE

Description:
Returns system data. When a composition template is composed in all
the expressions present in the composition, the CurrentDate() function
is  replaced with the current date value.
Example:
CURRENTDATE()

SUBSTRING
Description:
This function extracts a  substring from a  string.
Parameters:
„„ An expression of string type.
„„ The position of the character where the substring starts.
„„ The length of the extracted substring.
Chapter 10. Data Composition System 1-583

Example:
SUBSTRING(Contractors.Address, 1, 4)

STRINGLENGTH
Description:
This function defines the string length. The  parameter is  a string type expres-
sion.
Example:
STRINGLENGTH (Contractors.Address)

YEAR
Description:
This function extracts a year from a  Date value. The only parameter is an
expression of type Date.
Example:
YEAR(Invoice.Date)

QUARTER
Description:
This function extracts a quarter number from a Date value. As a rule,
a  quarter number is  between 1 and 4. The  only parameter of the function is  an
expression of type Date.
Example:
QUARTER(Invoice.Date)

MONTH
Description:
This function is  intended to obtain a  month number from a  Date value. As
a  rule, a  month number is  between 1 and 12. The  only parameter of the func-
tion is  an expression of type Date.
Example:
MONTH(Invoice.Date)
1-584 1C:Enterprise 8.3. Developer Guide

DAYOFYEAR
Description:
This function retrieves the day of the year from a  Date value. The  day of the
year is  normally in  the range from 1 to 365 (366). The  only parameter of the
function is  an expression of type Date.
Example:
DAYOFYEAR(Invoice.Date)

DAY
Description:
This function retrieves the day of the month from a  Date value. As a rule,
a  day number is  between 1 and 31. The  only parameter of the function is  an
expression of type Date.
Example:
DAY(Invoice.Date)

WEEK
Description:
This function retrieves the week number in  a year from a  Date value. Weeks
of the year are numbered starting with 1. The  only parameter of the function
is  an expression of type Date.
Example:
WEEK(Invoice.Date)

WEEKDAY
Description:
This function retrieves the day of the week from a  Date value. The day of
the week is  normally in  the range from 1 (Monday) to 7 (Sunday). The  only
parameter of the function is  an expression of type Date.
Example:
WEEKDAY(Invoice.Date)

HOUR
Description:
This function retrieves the hour (in 24-hour format) from a Date value.
As a  rule, the hour of the day is  between 0 and 23. The  only parameter of the
function is  an expression of type Date.
Chapter 10. Data Composition System 1-585

Example:
HOUR(Invoice.Date)

MINUTE
Description:
This function retrieves the minute number from a  Date value. As a  rule, the
minute of the hour is  between 0 and 59. The  only parameter of the function
is  an expression of type Date.
Example:
MINUTE(Invoice.Date)

SECOND
Description:
This function retrieves the second in  a minute from a  Date value. The  number
of second is between 0 and 59. The only parameter of the function is an
expression of type Date.
Example:
SECOND(Invoice.Date)

CAST
Description:
This function extracts a  type from an expression that can contain a  compound
type. If the expression contains a  type other than the required one, the NULL
is returned.
Parameters:
„„ Expression transformed
„„ Type – a  string that contains a  type string. For example, Number, String,
etc. In  addition to primitive types, the string can also contain a  table name.
In  this case the function attempts to cast to the table reference.
Example:
CAST(Data.Attribute1, "Number(10,3)")

ISNULL
Description:
This function returns the second parameter value if the first parameter is  NULL.
Otherwise, the first parameter value is  returned.
1-586 1C:Enterprise 8.3. Developer Guide

Example:
ISNULL(Total(Sales.SumTurnover), 0)

PRESENTATION
Syntax:
Presentation(<Expression>)
Description:
This function retrieves the string presentation of the non-primitive type value
delivered. The  value itself is  returned for primitive values.
If an array is transferred as a parameter, the function returns a string
containing string presentations of all the array items separated by ";". If a  value
table is  transferred as a  parameter, the function returns a  string that contains
string presentations of all value table strings, and cell presentations of each row
are separated by ";", while the rows are separated with a  line feed character.
If an item has an empty string presentation, a string reading <Empty value>
is  displayed instead of its presentation.
Example:
Presentation(Contractor)

STRING
Syntax:
String(<Expression>)
Description:
If an array is transferred as a parameter, the function returns a string
containing string presentations of all the array items separated by ";". If a  value
table is  transferred as a  parameter, the function returns a  string that contains
string presentations of all value table strings, and cell presentations of each row
are separated by "; ", while the rows are separated with a  line feed character.
If an item has an empty string presentation, a string reading <Empty value>
is  displayed instead of its presentation.
Example:
String(SaleDate)

ACOS
Syntax:
ACos(<X>)
Description:
Calculates the arccosine value.
Chapter 10. Data Composition System 1-587

ASIN
Syntax:
ASin(<X>)
Description:
Calculates the arcsine value.
ATAN
Syntax:
ATan(<X>)
Description:
Calculates the arctangent value.
COS
Syntax:
Cos(<X>)
Description:
Calculates the cosine value.
SIN
Syntax:
Sin(<X>)
Description:
Calculates the sine value.
TAN
Syntax:
Tan(<X>)
Description:
Calculates the tangent value.
EXP
Syntax:
Exp(<X>)
Description:
Calculates e raised to the power of X.
LOG
Syntax:
Log(<X>)
1-588 1C:Enterprise 8.3. Developer Guide

Description:
Calculates a  natural log value.
LOG10
Syntax:
Log10(<X>)
Description:
Calculates a  common log value.
POW
Syntax:
Pow(<X>, <Y>)
Description:
Calculates X raised to the power of Y.
SQRT
Syntax:
Sqrt(<X>)
Description:
Calculates a  square root value.
ROUND
Syntax:
Round(<Expression>, <CharacterCount>)
Description:
Rounds off the Expression value to CharacterCount after the comma.
INT
Syntax:
Int(<Expression>)
Description:
Calculates the cosine value.
VALUETYPE
Syntax:
ValueType(<Expression>)
Description:
Calculates a  type of expression transferred as a  parameter.
Returned value:
A value of type Type.
Chapter 10. Data Composition System 1-589

10.3.4.12. Common module functions

A data composition mechanism expression may contain function calls of global
common modules of the configuration and nonglobal common modules with
the Client (ordinary application) (if a standard application is used) or Server
(if a  managed application is  used) property set. You do not need to use additional
syntax to call these functions.
BriefDescription(Doc.Ref, Doc.Date, Doc.Number)

This example will call the BriefDescription() function from a common

module of the configuration.
Note that you can only use shared module functions if you specify the corre-
sponding data composition processor parameter.
Moreover, shared module functions cannot be used in  custom field expressions.

10.3.5. Data Composition Schema Wizard

The data composition schema wizard is a 1C:Enterprise script DataComposi-
tionSchemaWizard object intended for visual design of the data composition
schema. Moreover, the data composition schema wizard is  used in  the Designer to
edit the data composition schema.
For query data sets, the wizard automatically obtains nested data sets from the
query text and represents them as data set fields (nested data set).
For object data sets, the wizard supports addition of nested data set fields.

Fig. 238.  Addition of a  New Data Set

An example of how the data composition schema wizard window opens and the
obtained composition schema is  serialized in  XML is  shown below:

Procedure ReportEditorCommandBar (Button)

Wizard = New DataCompositionSchemaWizard;

Wizard.SetSchema(GetDataCompositionSchema());
1-590 1C:Enterprise 8.3. Developer Guide

Wizard.Edit(ThisObject);

EndProcedure

Procedure ChoiceProcessing(SelectionValue, Source)

If TypeOf(Source) = Type("DataCompositionSchemaWizard") Then

DataCompositionSchema = Source.GetSchema();
XMLWriter = New XMLWriter;
XMLWriter.SetString();
XDTOSerializer.WriteXML(
XMLWriter, DataCompositionSchema,
"dataCompositionScheme",
"http://v8.1c.ru/8/data-composition-system/scheme");
FormElements.DataCompositionSchemaText.SetText(XMLWriter.Close());
EndIf;

EndProcedure

Work with the data composition schema is  divided into the following stages:
„„ Editing data sets
„„ Editing data set fields
„„ Editing data set links
„„ Editing calculated fields
„„ Editing resources
„„ Editing parameters
„„ Editing templates
„„ Editing nested settings
„„ Editing data composition system settings

10.3.5.1. Editing Data Sets

The data composition system supports editing for the following objects:
„„ Query data set
„„ Object data set
„„ Union data set
„„ Query fields
When a  data set is  added, a  name and data source are automatically generated for
it  (if a  data source does not exist).
A data composition schema data set field that represents a  nested data set can be
described in  a query and an object data set.
The {SELECT} and {WHERE} clauses in  an object data set query can include nested
tables.
Chapter 10. Data Composition System 1-591

SELECT
GoodsReceipt.Date,
GoodsReceipt.Number,
GoodsReceipt.Vendor,
GoodsReceipt.Warehouse,
GoodsReceipt.Goods.(
LineNumber,
Product,
Price,
Count,
Sum
)
{SELECT
Date,
Number,
Vendor.*,
Warehouse.*,
Goods.(
LineNumber,
Product.*,
Price,
Count,
Sum
)}

FROM
Document.GoodsReceipt AS GoodsReceipt
{WHERE
GoodsReceipt.Date,
GoodsReceipt.Number,
GoodsReceipt.Vendor.*,
GoodsReceipt.Warehouse.*,
GoodsReceipt.Goods.(
LineNumber,
Product.*,
Price,
Count,
Sum
)}

Code fragments in  bold in  the above example describe nested table fields that are
available for setup.

Editing Query Data Set

Editing a  query data set comprises generating a  data query. You can use the query
wizard or edit query text directly in  the data composition schema wizard window
(see fig. 239).
If the Autofill flag is  set, the data composition system automatically fills the data
composition system fields based on the created query.
1-592 1C:Enterprise 8.3. Developer Guide

Fig. 239.  Query Data Set

Editing Object Data Set

Editing an object data set comprises adding/editing the name of the object that
contains the data and adding/editing fields and groups.

Fig. 240.  Object Data Set

Chapter 10. Data Composition System 1-593

Editing Union Data Set

Editing a union data set comprises editing merged fields that are in the list of
fields subordinate to the data set. The  created query and object data sets can be
dragged and dropped in  a union data set.

Fig. 241.  Union Data Set

10.3.5.2. Editing Data Set Fields

When editing fields, the following can be specified:
„„ Field header
„„ Field accessibility restriction
„„ Attribute field accessibility restriction
„„ Role for the field
„„ Field presentation
„„ Order expressions
„„ Hierarchy check methods (data set and parameter)
„„ Field value type
„„ Field appearance
Please note that the field's role, presentation order expression, parameter, value
type and appearance can only be edited at the top level of the data set hierarchy.
If a  data set field has no header, the data composition system attempts to generate
the header on the basis of the query field synonym. If no synonym can be obtained
for the field, the field data path is used as the header; however, it is first
supplemented by white spaces using the name-to-synonym conversion algorithm.
1-594 1C:Enterprise 8.3. Developer Guide

Synonyms are only retrieved for the query fields that either have no alias or have an
alias that is  different from the default alias.
The following method is  used to obtain synonyms for a  query field:
„„ If the query has no unions:
○○ If the query field expression includes a single field, the synonym
is  retrieved from this field;
○○ If the field expression is  an aggregate function of a  single field, the field
synonym is retrieved from this field. For other expressions, obtaining
a  synonym is  considered impossible.
„„ If the query has unions:
○○ All unions are searched for the field that allows obtaining a synonym
which is then used as the field synonym. If no field is found, obtaining
a  synonym is  considered impossible.
The data composition schema wizard includes an additional column with a  check
box that indicates that the field header is  manually set. The  check box is  cleared
by default if the field has no header.
When filling fields based on a  query, the wizard auto-fills headers for the fields
that either cannot obtain a synonym or have an alias that is different from the
default alias. Thus, the check box is  auto-selected for these fields.
If this check box is  deselected, the Title column displays the header to be displayed
to the user. However, the field header is  not actually filled in  this case. The  Title
column for the fields with the deselected check box is  not editable and highlighted
as unavailable.
If the developer wants to change the header, he/she can enable the check box; the
field header is  filled based on the text previously displayed in  the Title column.
When the check box is  cleared, the wizard clears the query text and displays auto-
generated text in  the header.
The field role is  initially defined in  the query, but can be changed in  a separate
dialog box (see fig. 242).
The account field requires am explicit reference to the account type in  the Type
parameter.
The dimension field can have a  path to the parent dimension data indicated in  the
Dimension parameter.
If the Ignore NULL values flag is  set, it  means the result will not include group
records for the field if its value is  NULL.
The resulting data set always includes fields with the Required flag set if at least
one field of the data set is  used in  the settings. For example, if you want to obtain
split balance for extra dimensions, but the ExtDimensions field is  not used in  the
query, the balance is  not split.
Chapter 10. Data Composition System 1-595

Fig. 242.  Field Role

The field's order expression, value type and appearance can also be edited
in  a separate dialog box.

10.3.5.3. Editing Data Set Links

If multiple top-level data sets exist, it  is  possible to set up links between them by
one or several fields.

Fig. 243.  Data Set Links

Data sets act as link sources and destinations. The  source and destination expres-
sions are data set fields.

10.3.5.4. Editing Calculated Fields

The Calculated fields tab allows creating and editing the following properties/char-
acteristics of calculated fields:
„„ Data path
„„ Expression
„„ Header
1-596 1C:Enterprise 8.3. Developer Guide

„„ Accessibility restriction
„„ Presentation expression
„„ Order expressions
„„ Value type
„„ Appearance
„„ Available values
Order expressions are edited in  a separate dialog box.

10.3.5.5. Editing Resources

Resource calculation is  available for all fields of all data sets and for calculated
fields. The  left table box displays a  list of available and unused fields. The  right
table box displays the fields used for generating totals and calculation expressions.

Fig. 244.  Editing Resources

By default the Sum function is set for numeric fields and the Count function –
for non-numeric fields. Use the >> button to add all fields of the Number type to
the resources. You can also enter multiple rows for a  single resource. When the
template composer obtains an expression for a  resource, it  uses information about
the target group and displays the corresponding expression.
In the Calculate by… column edit dialog, for fields for which hierarchical grouping
is possible, strings with a field name and Hierarchy keyword are added.
The  expression will be used for hierarchical grouping records for the field specified
before the keyword. When a  group is  selected in  the context of which a  resource
can be calculated, you can simultaneously select both a  usual and a  hierarchical field.
If a resource can only be calculated for a certain group (i.e. its Calculate by…
column contains at least one group), then this resource is  output to the result for
this group and its nested groups only.
Chapter 10. Data Composition System 1-597

Fig. 245.  Calculating resources by the group fields

10.3.5.6. Editing Parameters

Editing parameters includes:
„„ editing parameter name
„„ editing header
„„ editing available parameter types and values
„„ defining a  value and parameter value list accessibility
„„ defining an expression
„„ defining a  parameter as an available data composition setting field
„„ accessibility restriction
„„ determine whether the parameter is  required
„„ the parameter usage attribute
„„ setting edit parameters

Fig. 246.  Editing Parameters

If a  parameter value is  undefined, it  is  seen as a  zero reference to the set type.
Parameters can include predefined data and enumerations (the Designer mode).
The Available values column is  used to edit values that can be selected by the user
as data composition schema parameters. If the List of values is  available check box
is  selected, it  means multiple parameter values can be used.
NOTE
If the StandardPeriod parameter type is  used, please note that the start and
end dates of a  standard period also contain time values. The  start date contains
00:00:00 as its time value, while the end date contains 23:59:59. Thus, the
BEGINOFPERIOD and ENDOFPERIOD functions are no longer required in  a query.
1-598 1C:Enterprise 8.3. Developer Guide

Let's consider an example of using a required data composition schema param-

eter: assume that the Organization parameter is  required for a  report. In  the data
composition schema, for the Organization parameter the Usage property is  set to
Always, and Disallow incomplete values is  set to True.
When working with a  report, the Usage field is  not available for a  user, and any
unfilled value is  shown as usual (wavy red line). If a  user does not enter a  param-
eter value and runs the report, he will get the message saying that he must enter the
parameter value.

10.3.5.7. Editing Templates

Add templates by pressing the Add Template button on the command bar.

Fig. 247.  Template Editor

You can choose one of three template types:

„„ Field template
„„ Group template
„„ Group header template
„„ Table resources template
Group name and fields and template types can be set for a  group or group header
template.
For a table resource template, you can specify templates for two groups that
include this template.
The table box Area column specifies template area coordinates in  a spreadsheet
document.
Spreadsheet document areas can be edited using the properties panel, called
by pressing Alt  +  Enter. Both the appearance and the cell content and drill down
parameter are editable.
Chapter 10. Data Composition System 1-599

A template can be edited in  any language supported in  the system. If a  parameter
or a  template is  assigned to a  spreadsheet document cell, parameters are added to
the template and displayed in  the Parameter name column of the Template Param-
eters table box. Template parameter expressions can be edited. When a  template
is  loaded, its areas are separated by empty rows.

10.3.5.8. Nested Schemas

The Nested schemas tab allows creating and editing nested data composition
schemas. Nested schemas edited by the data composition schema wizard can act as
a schema.

Fig. 248.  Nested Schemas

10.3.5.9. Settings
A data composition schema contains default data composition settings that can be
specified by the developer.

Fig. 249.  Data Composition Schema Settings Editor

1-600 1C:Enterprise 8.3. Developer Guide

The Auto position of resources report settings control how resource fields are
displayed:
„„ Do not use – in  this case resources are shown in  the order in  which fields are
listed in  the Selected fields tab.
„„ After all fields – in  this case resources are displayed after all fields.
A group (or a  table group) has the Grouping use case parameter that controls how
additional information is  displayed after resource fields. If this parameter is  not set
or is  set to Auto, the group is  responsible for showing detailed records.
If this parameter is  set to Additional information for a  column group, the result table
in  this column will show one column with the fields listed in  the Selected fields
tab of this group that are available for display in  a row group. If group fields are
set for the column group, an error will occur when the data composition template
is generated. The same applies for a row group, except that one row is shown
instead of a  column.
For example, Nomenclature is  shown in  table rows. And warehouses are shown
in  table columns. A report on inventory at warehouses is  generated. It  is  neces-
sary to show the nomenclature article after columns with the inventory. To do this,
add a  table group to the columns without group fields and set the Grouping use
case parameter to Additional information in  group settings. In  the Selected fields
tab, specify the Nomenclature.Article field.
When such a  group is  shown outside the table, all fields available in  the group are
displayed.
Thus, if a report contains a group with multiple nested groups, you can use
a group with the Grouping use case parameter set to Additional information to
display parent group data between the groups.
The following parameters are ignored for groups with the Additional information
usage option:
„„ Group Fields Location – field titles shown in  a group are always displayed at
the beginning of a  row/column.
„„ Records number.
„„ Records percent.
„„ Totals placement.
„„ Grouping field placement.
„„ Grouping placement.
„„ Grand totals placement.
When the data template is  composed, if a  group with the Additional information
usage option uses a  field that is  not available in  the group or a  table and it  is  not
available for any group, an exception is  called.
Chapter 10. Data Composition System 1-601

Nested Fields
The system automatically generates nested fields for numeric resources. These
fields are calculated by the system and simplify generation of different indicators,
for example, a resource percentage of a resource values sum in all report data.
These fields include:
% in hierarchical group

Identifier:
PercentInHierarchy
Description:
This field shows the resource percentage in the current hierarchical group.
When the field is  shown outside the table, the value is  100%.
% in a column or a point hierarchical group

Identifier:
PercentInColumnOrPointHierarchy
Description:
This field shows the current cell resource value percentage of the resource total
value in  the current hierarchy level of the current column/point group. When
the field is  shown outside the table, the value is  % in  hierarchy group.
% in a row or a series hierarchical group

Identifier:
PercentInRowOrSeriesHierarchy
Description:
This field shows the current cell resource value percentage of the resource total
value in  the current hierarchy level of the current row/series group. When the
field is  shown outside the table, the value is  100%.
% in a group

Identifier:
GroupPercent
Description:
This field shows the current cell resource value percentage of the resource total
value in  the current group. When the field is  shown outside the table, the value
is  100%.
1-602 1C:Enterprise 8.3. Developer Guide

% in a column or a point group

Identifier:
ColumnOrPointGroupPercent
Description:
This field shows the current cell resource value percentage of the resource total
value in  the current column/point group. When the field is  shown outside the
table, the value is  100%.
% in a row or a series group
Identifier:
RowOrSeriesGroupPercent
Description:
This field shows the current cell resource value percentage of the resource total
value in the current row/series group. When the field is shown outside the
table, the value is  % in  group.
% in a column or a point
Identifier:
ColumnOrPointPercent
Description:
This field shows the current cell resource value percentage of the resource total
value per column/point. When the field is  shown outside the table, the value
is  % total.
% in a row or a series
Identifier:
RowOrSeriesPercent
Description:
This field shows the current cell resource value percentage of the resource
total value per row/series. When the field is  shown outside the table, the value
is  100%.
% total
Identifier:
OverallPercent
Description:
This field shows the current cell resource value percentage of the resource
total value in  the table. When the field is  shown outside the table, the value
is  100%.
Chapter 10. Data Composition System 1-603

System Fields
The system generates a special system field group in the list of selected fields.
These are used to determine the record sequence number both for the whole report
and a  separate group. Note that system fields are not included in  the list of fields
with auto fields when expanding, so they have to be added manually.
Ser. #

Identifier:
SystemFields.SerialNumber
Description:
Shows the row sequence number in  the given report. Numeration always starts
from 1.
# in group

Identifier:
SystemFields.GroupSerialNumber
Description:
Shows the row sequence number in the current group. Numeration always
starts from 1.
Level

Identifier:
SystemFields.Level
Description:
Shows the current record's level. Numeration always starts from 1.
Level in group

Identifier:
SystemFields.LevelInGroup
Description:
Shows the current record's level relative to the group. Numeration always starts
from 1.

Parameter Fields
There is  a special group in  selected fields, Parameters, that can be used to add
data composition schema parameters with Include in  available fields checked to
a report.
1-604 1C:Enterprise 8.3. Developer Guide

10.3.6. Data Composition Variant Settings

In a  data composition schema, multiple settings variants can be defined. A settings
variant is  a set of report settings picked out by the developer for some purpose.
These settings variants are stored in  the data composition schema.
For example, for a  Sales Trends report, one report variant may be a  chart showing
product sales by periods and another variant may be a  spreadsheet report repre-
senting product sales by customers. Each report variant has its own set of custom
settings (see page 1-610).
When a  data composition schema is  used for the report, settings variants described
in  the schema are presented to the user as standard report variants.
The system enables the user to create a new report variant directly in the
1C:Enterprise mode. This  option is  recommended to advanced users only. In  this
case the new report variant is  saved in  the reports variants storage that is  used by
other users to load the required variant. For a  description of the reports variants
storage see page 1-223.
The configuration comparison and merge mechanism (see page 2-1071) can be
used to partially compare and merge settings.
The data composition schema can be loaded from XML using the standard
1C:Enterprise script tools.

10.3.6.1. Structure of Data Composition Settings Variant

Structure is a settings framework. It defines the mutual position of their main
items.
The settings structure is accessible through the Structure property of the
DataCompositionSettings object. The  settings structure items can be:
„„ Groups
„„ Tables (DataCompositionTable)
„„ Charts (DataCompositionChart)
„„ Nested settings objects (DataCompositionNestedObjectSettings)

Group
To implement a  group, three different data types are used in  the settings structure:
„„ Groups (DataCompositionGroup)
„„ Table groups (DataCompositionTableGroup)
„„ Chart groups (DataCompositionChartGroup)
Use of three types is explained by the requirement to implement limitations on
the mutual position of items in  the structure tree: tables and plans cannot contain
anything except groups. Correspondingly, all group objects have a  similar object
Chapter 10. Data Composition System 1-605

model; they are distinguished by types of nested value collection and contents of
output parameters.

Group Fields
A set of fields used for grouping is described in the DataCompositionGro-
upFields object. The  Items property of this object contains a  group field collec-
tion consisting of DataCompositionGroupField objects.
NOTE
When grouping by the period field, a  parent period field which is  not an addi-
tional period is  automatically added to the group if grouping by this parent period
field was not performed in  the parent groups.
For example, if grouping is  performed by the Recorder field, then the SecondPe-
riod field is  automatically added to the group.
Creation of groups by period field attributes is  not allowed.
Autogroup Field
An auto-field is  converted to a  set of group fields before use.
The procedure used to generate the set is described below. The selected used
fields meeting the following criteria are chosen:
„„ The fields are available to be used in  the group fields.
„„ They are not resources.
„„ They are not dependent on other selected fields.
„„ They are not dependent on the existing group fields.
If a  field is  already included in  the group field data, it  is  not added again.
Table
A table description in  the settings structure is  performed using the DataComposi-
tionTable object.
Chart
A chart description in  the settings structure is  performed using the DataComposi-
tionChart object.
Nested Object
A nested object description in the settings structure is performed using
the DataCompositionNestedObjectSettings object.
The Name property is  implemented for the object. This  property is  used to iden-
tify a  nested report within the generated data composition template.
1-606 1C:Enterprise 8.3. Developer Guide

10.3.6.2. Properties of Data Composition Settings

Selection
A set of fields output as a result of composition. It is described using
the DataCompositionSelectedFields object. The Items property of this
object contains a  collection of selected fields consisting of DataCompositionSe-
lectedField objects.
Selected Field Group
It is used to group fields. It is described using the DataCompositionSelec-
tedFieldGroup object.
Auto-Selected Field
An auto-field is  converted to a  set of selected fields before use. The  list of fields
in  the set depends on what structure item owns the expanded auto-field and what
part of the structure this item is  located at. The  system tabs through all the report
structure parent items for each item and selects resource and fields using the
following rules:
„„ For a  group or table group the following replaces an auto-field:
○○ All the used fields of the group that are available for used in  the selected
fields;
○○ Fields that represent attributes of the group fields;
○○ Resources of parent items.
IMPORTANT!
The system only tabs through groups with the Elements or Hierarchy type.
„„ For chart groups, resources are not selected; instead, all settings structure parent
items are tabbed through and group fields are selected from the selected item
fields if they have a  Hierarchy only group.
„„ For Detailed records groups (groups, table groups, plan groups), all used fields
are selected from the main selected fields of the settings that own a  particular
group, with the exception of the fields included in  upper-level groups and their
attributes. If this group is  Hierarchy only, its fields and attributes are used by the
system to generate a  set of combo boxes. For chart groups, resources are not
selected, too.
„„ For Additional information-type fields, fields are added to the selected fields (not
resources) that are available in  a group or a  parent group, a  table and in  any
group from the opposite axis.
„„ For a diagram, the autoselection field is replaced with all resources stated
above.
Chapter 10. Data Composition System 1-607

„„ For charts, an auto-selection field is replaced by a resource that is first

encountered in  the tabbing procedure described above.
„„ For tables, an auto-selection field is  converted to a  set of resources used by
parent items.
NOTE
If a  field is  already included in  the selected fields, it  is  not added again.
Fields are added to the set in  the following order: first, fields of the group's own
fields (for groups), then fields from the global settings (for Detailed records groups)
and, finally, resources and fields from the parent items.
Filter
It is  used to filter records included in  the composition result. It  can also be used
to filter records with applied appearance (conditional appearance) and to create user
combo boxes.
It is  described using the DataCompositionFilter object. The  Items property
of this object contains a collection of filter items consisting of DataComposi-
tionFilterItem objects.
Filter Item Group
It is  used to group filter items and order the result data. It  is  described using the
DataCompositionFilterItemGroup object.
Order
It describes how to order records output in  the result. It  represents a  DataCompo-
sitionOrder object. The  Items property of this object contains a  collection of
order items consisting of DataCompositionOrderItem objects.
Auto-Order Item
An auto-order item is  converted to a  set of order items before use.
The following rules are used to generate the set: resources are added uncondition-
ally, while non-resource fields are only selected if they are group field attributes or
the group field itself (all fields are added to the set for detail records). Group fields
that are not specified in  the global order are added to the end of the order. If a  field
is  already included in  the selected order, it  is  not added again.
Conditional Appearance
It describes how to format different result fields. It represents the DataCompo-
sitionConditionalAppearance object. The Items property of this object
contains a collection of order elements consisting of DataCompositionCondi-
tionalAppearanceItem objects.
1-608 1C:Enterprise 8.3. Developer Guide

The Format and Text parameters are edited as multilingual in  the data composi-
tion appearance of the data composition wizard.
For an element of conditional appearance, you can specify to which areas such
conditional appearance should be applied.
„„ To a  field output in  the grouping
„„ To a  field output in  a hierarchical grouping
„„ To a  field output in  total
„„ To field headers
„„ To a  report header area
„„ To the area where report parameters are output
„„ To the area where filter values are output

Appearance Fields
These are fields with applied appearance. They are described using the DataCom-
positionAppearanceFields object. The  Items property of this object contains
a collection of appearance fields consisting of DataCompositionAppearan-
ceField objects. If no fields are indicated, appearance is  applied to the entire area.
Output Parameters
Output parameter values define object appearance. Inheritance is supported for
some parameters. It  means the output parameter collection for an item can contain
parameters that do not belong to the item, but are used in  items that can be inserted
in  a subordinate settings structure.
Data Parameters
Data parameter values are usually used in  queries for selection filtering.
User Fields
User fields allow the user to extend a  set of the used available fields by defining
custom expressions or variant sets with the condition of using a  specified variant.
User fields are described using the DataCompositionUserFields object.
The  Items property of this object contains a  collection of user fields consisting of
two object types:
„„ Expression field (DataCompositionUserFieldExpression object)
„„ Case field (DataCompositionUserFieldCase object)
The system defines the field type automatically based on its properties.
User Field Variants
It is a description of alternatives set that defines case field value. They are
described using the DataCompositionUserFieldsCaseVariants object.
Chapter 10. Data Composition System 1-609

The  Items property of this object contains a  collection of user case field variants
consisting of DataCompositionUserFieldsVariant objects.
Work with Auto-Fields
If a settings structure item contains DataCompositionAutoGroupField,
DataCompositionAutoSelectedField and DataCompositionAutoOrderItem
auto-fields, they are converted as follows:
„„ DataCompositionAutoGroupField
„„ DataCompositionAutoSelectedField
„„ DataCompositionAutoOrderItem

10.3.6.3. Available Objects

Available objects are a  set defining the objects that can be used as nested objects
in  composition. Nested reports are an example of these objects.

10.3.6.4. Available Fields

Available fields are a  set of fields that can be used for data composition settings
and are identified and processed correctly at the subsequent composition stages.
Available fields have different applications. The  following field collections can be
identified:
„„ Fields for selection (SelectionAvailableFields property)
„„ Group fields (GroupAvailableFields property)
„„ Order fields (OrderAvailableFields property)
„„ Data parameter fields (DataParametersAvailableFields property)
„„ Filter fields (FilterAvailableFields property)
„„ Structure item filter fields used for all structure items except the top-level
(StructureItemsFilterAvailableFields property)
„„ Additional filter fields used for conditional appearance (AdditionalFil-
terAvailableFields property)
All the listed properties contain value collections with DataCompositionAvaila-
bleField objects.
In the data composition schema wizard and the report data composition schema
settings, available fields are ordered as follows: first, alphabetically ordered
non-resource fields, then alphabetically ordered resource fields. System folders are
the last to be displayed in  the list.
Available Filter Field
Available fields of a special type are designed for orders. They have the same
properties as standard available fields, but also provide sets of available comparison
types and available field values required to generate order items correctly.
1-610 1C:Enterprise 8.3. Developer Guide

10.3.6.5. Data Composition Settings Composer

The settings composer is represented by the 1C:Enterprise script DataCom-
positionSettingsComposer object. This object is intended to link data
composition settings and the data composition schema. The  source of available settings
for a  settings editor is  built on basis of the data composition schema.

10.3.7. User Settings of Data Composition System

Certain settings can be marked for the user to edit them in a separate form.
This  mechanism is  known as user settings.
Composition supports both user and complete settings. User settings are added on
to the complete settings, thus forming settings that are actually executed.

10.3.7.1. User Settings Object Model

User settings can be used to edit the following objects:
„„ DataCompositionFilter
„„ DataCompositionFilterItem
„„ DataCompositionFilterItemGroup
„„ DataCompositionOrder
„„ DataCompositionSelectedFields
„„ DataCompositionConditionalAppearance
„„ DataCompositionConditionalAppearanceItem
„„ DataCompositionSettingsParameterValue
„„ DataCompositionGroup
„„ DataCompositionTableGroup
„„ DataCompositionChartGroup
„„ DataCompositionTable
„„ DataCompositionChart
„„ NestedDataCompositionSchema
„„ DataCompositionStructureItemCollection
„„ DataCompositionTableStructureItemCollection
„„ DataCompositionChartStructureItemCollection
These objects have the following properties:
„„ UserSettingID – identifies the user setting object. If this property is  set, the
object is  considered a  user object and must be edited in  the user settings.
If a  setting is  interactively marked as a  user setting, the system auto-generates
a  unique ID and fills this property with the ID's string presentation.
Chapter 10. Data Composition System 1-611

„„ UserSettingPresentation – is a string used to display a presentation

in  the user settings. The  schema wizard allows the user to enter presentations
in  multiple languages.
„„ ViewMode – is  used to define quick settings. For details on this feature see the
sections below.
In the object model, user settings are represented by a  special DataCompositio-
nUserSettings object. This  object has the Items property. It  is  a collection of
user settings items. The  following objects are valid:
„„ DataCompositionFilter
„„ DataCompositionFilterItem
„„ DataCompositionFilterItemGroup
„„ DataCompositionOrder
„„ DataCompositionSelectedFields
„„ DataCompositionConditionalAppearance
„„ DataCompositionConditionalAppearanceItem
„„ DataCompositionParameterValue
„„ DataCompositionGroup
„„ DataCompositionTableGroup
„„ DataCompositionChartGroup
„„ DataCompositionTable
„„ DataCompositionChart
„„ DataCompositionNestedObjectSettings
„„ DataCompositionSettingStructure

10.3.7.2. Setup of User Settings Items

A settings item can be marked as a  user item in  the user item setup form invoked
by the Custom settings item property command.

Fig. 250.  Open a  User Setting

1-612 1C:Enterprise 8.3. Developer Guide

The user item setup form can be used to specify that the item is  a user item, select
its presentation and edit mode.

Fig. 251.  ser Setting Property

The Custom settings item propertiy command can be used to set up user settings for
the current structure item in  the settings structure list. Each structure item has got
its own list of adjustable items.
Object Adjustable Items
Report ■■ Selected fields
■■ Order
■■ Filter
■■ Conditional appearance
■■ List of group
Group/ ■■ Group
table group/ ■■ Selected fields
chart group ■■ Filter
■■ Order
■■ Conditional appearance
■■ List of nested groups
Chart ■■ Chart
■■ Selected fields
■■ Conditional appearance
■■ List of series groups
■■ List of point groups
Table ■■ Table
■■ Selected fields
■■ Conditional appearance
■■ List of row groups
■■ List of column groups
Nested schema ■■ Nested report
■■ Selected fields
■■ Filter
■■ Order
■■ Conditional appearance
■■ List of groups

Depending on the call source, the Properties command of a  user settings item
can be used to modify various settings:
„„ Filter list – user settings for the current item/filter groups,
„„ List of output and data parameters – user settings for the current parameter,
„„ Conditional appearance list – user settings for the current conditional appear-
ance item.
Chapter 10. Data Composition System 1-613

Additionally the Custom Settings command of the structure table can open a  modal
form that displays user settings with their default values.

10.3.7.3. Editing User Settings

The UserSettings object is  edited in  a table (see fig. 253).

Fig. 252.  User Settings Editor

TIP
It makes sense to designate settings as user settings (out of the various settings
provided by the data composition system) if they are meant for report manage-
ment by the end user. It  is  assumed that the user will only operate these settings.
For example, a  query (functioning as a  data set for the report) might contain many
fields that can be used for filtering. However, the report developer believes there
is  a number of filter items that are used most frequently. Therefore, it  is  logical
they can be designated as user settings. In  this case the user can edit both "special"
filter items (the Goods Item row on fig. 253) and the entire filter (the Filter row
on fig. 253).
It also makes sense to designate the following settings as user:
„„ Period or date – virtually or all reports
„„ Groups and conditional appearance – for spreadsheet reports
„„ Account value – for accounting reports, etc.
For each report, the developer makes a decision as to what settings need to be
designated as user settings in  this report (or report variant).

10.3.7.4. Quick User Settings

The developer can single out certain user settings edited by the user most frequently
(e.g., filter by product in the Product Inventory report or filter by organization
in  an accounting report). In  this case a  user setting can be designated as a  quick
setting (by selecting Quick access for the ViewMode property). These settings can
be directly edited in  a report form.
1-614 1C:Enterprise 8.3. Developer Guide

Fig. 253.  Quick User Settings

The table used to edit user settings also has got the ViewMode property that defines
whether all user settings or quick settings only are displayed.
If a  user does not like the current quick user settings, they can change their content,
such as exclude settings that will not be changed very often.
The user needs to run the More  – Change settings assortment… (All actions  –
Change settings assortment…) command in  the report settings edit window.

Fig. 254.  Editing quick user settings

The left side of the form shows all the user settings that can be selected as quick
settings, and the right side shows the settings currently being edited in  the report
form.
Filter editing forms and conditional appearance forms contain commands to edit the
user settings item properties. Thus, the user can drag filter or conditional appear-
ance items that are frequently modified to quick user settings.
You can also manage quick user settings in the settings edit form using the
Edit in  report form column. By default this is  not shown in  the form. You need
Chapter 10. Data Composition System 1-615

to enable it  using the All actions  – Change form... command in  the edit settings
window.
In this case you can't add new settings, but you can quickly change existing settings.

Fig. 255.  Edit in  Report Form column

10.3.7.5. Settings Composer

The settings composer has the UserSettings property. It  contains values of the
edited user settings. The  property cannot be written using the 1C:Enterprise script.
Moreover, the settings composer has the LoadUserSettings() method that loads
user setting values passed as its parameters.
The GetSettings() method can be used to obtain a  copy of the current settings
(with regard to the user settings).
The LoadSettings() method loads the passed settings into the settings composer
(the user settings are re-filled on the basis of the passed data).

10.3.7.6. Fillup of User Setting Values

When user setting values are filled, appropriately filled items are added to the user
settings for various settings items.
The UserSettingID property and the properties that are actually edited in the
user settings are filled in the appropriate user items for the following types:
DataCompositionFilterItem, DataCompositionFilterItemGroup,
DataCompositionConditionalAppearanceItem, DataCompositionParame-
terValue, DataCompositionGroup, DataCompositionTableGroup, DataCom-
positionChartGroup, DataCompositionTable, DataCompositionChart,
NestedDataCompositionSchema.
An object of the appropriate type is created for the following types: Da-
taCompositionFilter, DataCompositionConditionalAppearance, DataCom-
positionOrder, DataCompositionSelectedFields. The object's collection
is  appended by items with the ViewMode property not set to Inaccessible.
1-616 1C:Enterprise 8.3. Developer Guide

There are some exceptions:

„„ Items are not added if marked as user items. For example, a  user filter cannot
be appended by a  filter item marked as user;
„„ Items are not added if they contain user items. For example, a  group of condi-
tions cannot be added if it  contains items marked as user;
„„ The ViewMode property is  not analyzed for nested items. They are either added
or not added together with their parents.
A DataCompositionSettingStructure object is created for the following
types: DataCompositionStructureItemCollection, DataCompositi-
onTableStructureItemCollection, DataCompositionChartStructu-
reItemCollection. The  object contains groups that already exist in  the structure.
It  can only include groups with the specified group fields (detail records are not
added to the object). Groups are placed in  the object until a  detail record, branch,
table, nested schema, unused group or user-structured group is  encountered.

10.3.7.7. Applying User Settings

User settings are applied to the main settings in  the GetSettings() method of the
settings composer. The  following actions are performed:
„„ Item contents are copied to the appropriate user setting items for the following
types: DataCompositionFilterItem, DataCompositionConditionalAp-
pearanceItem and DataCompositionParameterValue.
„„ Items stored in the main settings and marked as Inaccessible are left
unchanged for the following types: DataCompositionFilter, DataCom-
positionConditionalAppearance, DataCompositionOrder and DataCom-
positionSelectedFields. Items from the user settings are moved to the
main settings. They are added to the end of the collection for Filter, Selec-
tedFields and ConditionalAppearance or to the beginning of the collection
for Order.
„„ The Use property is set in the appropriate main settings item (based on the
User Settings Item Use flag) for the following types: DataCompositionFil-
terItemGroup, DataCompositionGroup, DataCompositionTableGroup,
DataCompositionChartGroup, DataCompositionTable, DataComposi-
tionChart and DataCompositionNestedObjectSettings.
„„ An item of the main settings structure is  searched for appropriate groups that
are then correctly ordered for the DataCompositionSettingStructure type.
Missing groups are created. Groups that could not be found in  the user settings
or have been disabled by the user are not deleted; instead, they are marked.
It  saves them for possible future use. User groups with an empty set of fields
(detail records) are ignored.
Chapter 10. Data Composition System 1-617

10.4. DATA COMPOSITION TEMPLATE

A data composition template is represented by the 1C:Enterprise script
DataCompositionTemplate object and consists of multiple nested objects.
The  data composition template is  an instruction for the data composition system
on how to perform data composition. The  composition template already includes
descriptions of area templates, texts of executed queries, group positions, etc.

10.4.1. Data Composition Template Sections

Each data composition template contains a variety of objects that describe its
sections. Let us review these sections.

Fig. 256.  Data Composition Template Sections

Data Sources
The data composition template can contain several data source descriptions.
A data source means a source from where data are retrieved. 1C:Enterprise
infobase is  used as a  data source.
Data sources are described in  the template's DataSources property that contains
a  value collection consisting of DataCompositionTemplateDataSource items.
Several data sources that specify one infobase using a connection string can be
created.
1-618 1C:Enterprise 8.3. Developer Guide

Data Sets
The data composition template data sets contain a description of the data to be
obtained in  data composition.
They are described in  the data composition template's DataSets property.
Several data sets can exist.
Nested data sets are treated as standard data sets. They are always associated with
their parents. If a  filter condition is  specified for a  nested data set, its association
with the parent data set is  considered inner.
Data Composition Template Data Set Field
A data set can contain descriptions of fields available for this data set. Fields with
no descriptions in  data sets are not available. If a  certain field is  present in  a data
set query but does not exist in  the data set fields description, this field is  not avail-
able for use.
Data set fields are described in  the data set's Fields property that contains a  value
collection consisting of DataCompositionTemplateDataSetField items.
Data Composition Template Parameter Values
The data composition template can contain parameters in  any of its expressions.
Parameter values are described in the data composition template's Para-
meterValues property that contains a  value collection consisting of DataCompo-
sitionTemplateParameterValue items.
Data Composition Template Data Set Links
Data sets within the data composition template can be linked. The  data composi-
tion template describes links between data sets.
Data set links are described in the data composition template's DataSetLinks
property that contains a value collection consisting of DataCompositionTem-
plateDataSetLink items.
Area Templates in  Data Composition Template
During composition execution, area templates are output to the composition result.
These area templates are also stored in  the data composition template.
Templates are described in  the data composition template's Templates property
that contains a value collection consisting of DataCompositionTemplateAr-
eaTemplateDefinition items.
Data Composition Template Body
The previous sections of the data composition template specify where to receive
information. Indication of how to compose data is in the data composition
template body. The  data composition template body consists of separate items.
Chapter 10. Data Composition System 1-619

The following item types can be used:

„„ Group – describes a  group output to the result;
„„ Detail records – describes the data set's detail records output to the result;
„„ Table – describes a  table output to the result;
„„ Chart – describes a  chart output to the result;
„„ Template – describes templates used for output.

Table Group
It describes a  table group and is  represented by the 1C:Enterprise script DataCom-
positionTemplateTableGroup object.
A table group contains the same properties as an ordinary group, with the following
differences:
„„ Table group body and table group hierarchical body can only contain items
included in  the table body, i.e. only table groups, table detail records and table
group templates. The hierarchical body can also contain a table hierarchical
group that indicates a  location where hierarchical group records are output;
„„ Table group templates are used as header and footer templates;
„„ The following properties can be used:
○○ OverallsTemplate – specifies the template used to output overalls by
groups and having the DataCompositionTemplateTableGroupTemplate
type.
○○ OverallsPlacement – describes the overalls placement for a group and
has the DataCompositionTotalPlacement type.
Table Detail Records
They describe table detail records and are represented by the 1C:Enterprise script
DataCompositionTemplateTableRecords object.
Table Group Template
A table group template describes templates used for outputting table groups and
is represented by the 1C:Enterprise script DataCompositionTemplateTab-
leGroupTemplate object.
Chart Group
It describes chart groups and is  represented by the 1C:Enterprise script DataCom-
positionTemplateChartGroupBody object.
A chart group contains the same properties as an ordinary group, with the following
differences:
„„ The chart group body and chart group hierarchical body can only contain chart
group templates and chart groups. The hierarchical body can also contain
1-620 1C:Enterprise 8.3. Developer Guide

a chart hierarchical group that indicates a location where hierarchical group

records are output;
„„ There are no header and footer templates.

Chart Group Template

A chart group template describes templates used for outputting chart groups
and is represented by the 1C:Enterprise script DataCompositionTempla-
teChartGroupTemplate object.

Area Templates
An area template is  a declarative description of the output data position as well
as the visual presentation required for the output of data to differently formatted
documents.
There are several fundamentally different area templates:
„„ The area template itself
„„ Plan area templates
The template structure is  shown on fig. 257.

Fig. 257.  Template Structure

Area templates are represented by the 1C:Enterprise script DataComp-

ositionAreaTemplate object. The latter is a collection of DataComposi-
tionAreaTemplateTableRow objects.

10.4.1.1. Area Template Structure

As mentioned above, an area template is a collection of DataComposi-
tionAreaTemplateTableRow objects. A Row is a collection of cells positioned
horizontally from left to right. Thus, several adjacent rows of a  data composition
area table make a  rectangular table.

Table Cell Collection

This object is  a collection of table row cells. It  is  described by the 1C:Enterprise
script DataCompositionAreaTableCells object. The  collection consists of table
cells that represent DataCompositionAreaTemplateTableCell objects.
Chapter 10. Data Composition System 1-621

A table cell is  a rectangular area used for outputting data in  differently formatted
documents. Cells can contain output fields, text and formatting.
Template Item Collection
A template item collection (DataCompositionAreaTemplateItems object)
is  a collection of fields (DataCompositionAreaTemplateField objects). These
objects can appear in the collection in an arbitrary order. Data in these objects
is  used for outputting to differently formatted documents.
Field
This item is  a field output in  a table cell or list item. A field can contain an arbi-
trary value and its appearance. A field is described by the 1C:Enterprise script
DataCompositionAreaTemplateField object.
Table Cell Appearance
Table cell appearance is a collection of objects that describe the formatting of
a table cell. It is described by the 1C:Enterprise script DataCompositionAr-
eaTemplateTableCellAppearance object.

Field Appearance
Field appearance is a collection with a single object – the Format appearance
item. It is described by the 1C:Enterprise script DataCompositionAreaTem-
plateFieldAppearance object.

10.4.1.2. Chart Area Template Structure

There are three types of plan area templates:
„„ A chart template (DataCompositionAreaTemplateChartTemplate object)
„„ A chart resource template (DataCompositionAreaTemplateChartRe-
sourceTemplate object)
„„ A chart group template (DataCompositionAreaTemplateChartGroupTem-
plate object)
One chart template, one chart resource template and several chart group templates
are generated when chart templates are created. The  number of group templates
corresponds to number of points and series in  a chart.
Principle of Operation
Area templates are used for outputting reports to differently formatted documents.
An area template is a component of the data composition template definition
(DataCompositionSchemaTemplateDescription object).
In order to output values of the output report fields in  area template cells or list
items, assign a  value of the DataCompositionSchemaParameter type containing
1-622 1C:Enterprise 8.3. Developer Guide

the parameter name to the Value property of the data composition area field
(DataCompositionAreaTemplateField object). Add the parameter itself to the
template definition parameter list and assign it  a parameter name and a  name of
the output field or expression in  the data composition system expression language
as its expression.
Chart Template
A chart template is used for describing the chart type. It is described by the
1C:Enterprise script DataCompositionAreaTemplateChartTemplate object.
Chart Resource Template
A chart resource template is  used for generating chart values and is  described by
the 1C:Enterprise script DataCompositionAreaTemplateChartResourceTem-
plate object.
Chart Group Template
A chart group template is  used to generate chart points and series. It  is  described
by the 1C:Enterprise script DataCompositionAreaTemplateChartGroupTem-
plate object.

10.4.2. Appearance Templates

An appearance template is a declarative description of predefined report areas.
These descriptions are used by the template area generator for template area
generation based on data composition settings items.
To create an appearance template interactively, use the template wizard to specify
the Data composition appearance template type and then click Finish. The  appear-
ance template window will open (see fig. 258).
The wizard window contains appearance area list, appearance setting table and
spreadsheet document Preview fields that display the result of the settings selection.
Filled template areas are shown in  bold.
Use the drag-and-drop context menu to copy appearance parameters from one area
to another or to replace them.
The Standard template button loads a predefined template from the standard
template list that also includes common configuration templates.
The Clear template button removes all appearance from a  template.
To set up appearance, do the following:
„„ Select an appearance area.
„„ In the settings table, select parameters for changing and specify new appearance
values.
„„ Check results of the changes in  the Example field.
Chapter 10. Data Composition System 1-623

Fig. 258.  Appearance Template Window

If you want to output several group levels in the report, create an appropriate
number of subordinate areas for each listed area containing levels. To create an
area level, specify the area and press the Add command bar button. A row named
Level N is  added to the area list, where N stands for the group level number. Set
appearance for the group level as described above.
NOTE
If several levels are set and a  group level is  removed, the lowest level in  the
current area is  always deleted, even if another one is  selected in  the list.
Appearance Template Structure
Every appearance template consists of a certain number of appearance template
areas. An appearance template area has a  name – a  string listing the appearance
template areas and specifying for which area the given template is  to be used and
an appearance item collection.
An appearance item has two properties:
„„ Level – a  positive number; if the level is  0, the appearance is  considered to be
applied by default to all templates of an area of a  certain type;
„„ Appearance – a  collection containing the appearance property names and their
values.
Appearance templates are represented by the 1C:Enterprise script DataComposi-
tionAppearanceTemplate object.
1-624 1C:Enterprise 8.3. Developer Guide

Data Composition Appearance Template

This object is  a collection of appearance template areas. The  collection is  imple-
mented as parameter values. The  parameter name is  an area name. An area name
is  a predefined string from the area list. The  parameter value is  a DataComposi-
tionAppearanceTemplateArea object.
Data Composition Appearance Template Area
This object is  a description of a  predefined area and a  collection of items of the
appearance template area (DataCompositionAppearanceTemplateAreaItem
objects).
Data Composition Appearance Template Area Item
This object is a description of a template area for a certain hierarchy level.
If 0 is  specified as a  level number, then the appearance template is  considered to
be used for all areas of this type.

10.4.3. Generator of Template Areas

Use the template area generator to dynamically form data composition area
templates used to output the data composition results in documents of various
formats. An area template is  understood as a  declarative description of output data
location and appearance.
Operation of the template area generator consists of the following stages:
„„ Generation of common report templates
„„ Generation of group templates
„„ Placement of groups
„„ Placement of output group fields
„„ Use of an appearance template
„„ Use of conditional appearances
„„ Merging of cells
Let us consider every stage of the operation of the template area generator.
Generation of Common Report Templates
At this stage the template area generator creates common templates based on the
data composition settings. The  type and number of templates depends on an item
type of the data composition setting.
Group Template
A special template – group header – is generated for a group. This template
contains the names of the output fields in  the left part of the template and names of
the output resource fields in  the right part of the template, as in  the example below.
Chapter 10. Data Composition System 1-625

Contractor Contractor.Code Count Sum

Nomenclature Nomenclature.Code Nomenclature.Description

Table Template
The following group of templates is  generated for a  table:
„„ Table header template. This  template contains the names of the output table
row fields, as in  the example below.
Contractor Contractor.Code
Nomenclature Nomenclature.Code Nomenclature.Description

„„ Template of totals by rows. This  template contains the Total special word and
names of the resource fields if they are output horizontally, as in  the example
below.
Total
Count Sum

„„ Template of totals by columns. This  template contains the Total special word
and names of the resource fields if they are output vertically, as in  the example
below.
Total Count
Sum

„„ Overalls template. This  template contains the resource fields that are output
in the table and are required to display the overalls in a table, as in the
example below.
Presentation(Sum(Sales.SalesVolume)) Presentation(Sum(Sales.SalesVolume))

Location of the template data within the table is  shown below.
Table Header Column area Total template by rows
Row area Resource area Totals area by rows
Total template by columns Totals area by columns Template of overalls

The location of the totals templates by columns and rows is managed by the
OverallsHorizontalLocation and OverallsVerticalLocation properties,
respectively. The  following options of the overalls location are possible:
„„ None – overalls are not output.
Table Header Column area

Row area Resource area

1-626 1C:Enterprise 8.3. Developer Guide

„„ Begin – overalls are output in  the first column or in  the first row of a  table,
respectively.
Table Header Total template by rows Column area
Total template by columns Template of overalls Totals area by columns
Row area Totals template by rows Resource area

„„ End – overalls are output in  the last column or the last row of a  table, respec-
tively.
Table Header Column area Total template by rows
Row area Resource area Totals area by rows
Total template by columns Totals area by columns Template of overalls

„„ BeginAndEnd – overalls are output in the first column/row and in the last
column/row of a  table.
Table Header Total template by rows Column area Total template by rows
Total template Template of overalls Totals area by columns Template of overalls
by columns
Row area Totals area by rows Resource area Totals area by rows
Total template Overalls template Totals area by columns Template of overalls
by columns

„„ Auto – column totals are located in  the last row, whilst row totals are located
in  the last column.
Chart Template
This template contain the chart's appearance properties.

Generation of Group Templates

The data composition setting contains three types of groups:
„„ Group
„„ Table group
„„ Chart group
Every group type has its own set of area templates. However, the location of groups
relative to each other, the location of the output fields within the group areas and
the location of the resource fields is  unified. The  following stages can be singled
out in  group area template generation:
„„ Group template type identification. The group template type is obtained
from the DataCompositionGroupTemplateType property of the DataCom-
positionOutputParameterValues object. This property is meaningful
only for simple groups, i.e. groups that are not included in  a table or a  chart.
The  following location options are possible for the selected fields:
○○ Auto – automatic identification of location for the selected fields: if a  group
contains a  nested table, chart, nested report or group with a  Vertical group
Chapter 10. Data Composition System 1-627

template type, then the selected fields are located vertically, otherwise horizon-
tally.
○○ Horizontal – location of the selected fields is  horizontal, from left to right.
Contractor Contractor.Code
Nomenclature Nomenclature.Code Nomenclature.Description
Alex-2002 00009
1C:Accounting 8 00013 1C:Accounting 8

○○ Vertical – location of the selected fields is  vertical, one under another.
Contractor Alex-2002
Contractor.Code 00009
Nomenclature 1C:Accounting 8
Nomenclature.Code 00013
Nomenclature.Description 1C:Accounting 8

„„ Location of groups relative to each other. The location of groups relative

to each other is managed by the GroupFieldsPlacement property of the
DataCompositionOutputParameterValues object. The following location
options are possible:
○○ Together – groups are located under each other. Below is  an example for
groups by contractor and nomenclature.
Contractor Contractor.Code
Nomenclature Nomenclature.Code Nomenclature.Description
Alex-2002 00009
1C:Accounting 8 00013 1C:Accounting 8

○○ Separately – each group is located in a separate area. The groups are

located following each other from left to right. The  output group fields are
output in  the nested groups as well.
Contractor Contractor.Code Nomenclature Nomenclature.Code Nomenclature.Description
Alex-2002 00009
Alex-2002 00009 1C:Aspect 7.7 00015 1C:Aspect 7.7
Compact trading system

○○ SeparatelyAndInTotalsOnly – each group is  located in  a separate area.

The  groups are located following each other from left to right. The  output
fields are output only in  this group:
Contractor Contractor.Code Nomenclature Nomenclature.Code Nomenclature.Description
Alex-2002 00009
1C:Aspect 7.7 00015 1C:Aspect 7.7
Compact trading system
1-628 1C:Enterprise 8.3. Developer Guide

„„ Location of output fields. There are two types of fields: output fields (owner
fields and/or their attributes) and resource fields. The output of these fields
have considerable differences:
○○ Output of fields. As mentioned above, there are owner fields
and attribute fields. Owner fields are output in an area template
in accordance with their sequence order in  the data composi-
tion setting. Location of attribute fields is managed by a special
AttributePlacement parameter of the DataCompositionOut-
putParameterValues object. The  following location options are possible:
□□ Together – attribute fields are located together in  a separate column and
are separated by a  comma when they are output.
Contractor Contractor.Code
Nomenclature Nomenclature.Code, Nomenclature.Description

□□ Separately – every attribute field is  located in  a separate column.

Contractor Contractor.Code
Nomenclature Nomenclature.Code Nomenclature.Description

□□ TogetherWithOwner  – attribute fields are located together with their

owner field in  a separate column and are separated by a  comma when
they are output.
Contractor, Contractor.Code
Nomenclature, Nomenclature.Code, Nomenclature.Description

□□ SpecialPosition – attribute fields are located in  a special column of

a  group in  the right-most position.
Contractor Contractor.Code
Nomenclature Nomenclature.Code, Nomenclature.Description

○○ Output of fields located in folders. Use the Folder Placement property

to manage the location of these fields. The  following location options are
possible:
□□ Auto  – fields are output depending on the group type. If a  group
is  simple, the fields are output horizontally; if a  group is  of table type,
then they are output vertically.
Contractor
Nomenclature Nomenclature attributes
Nomenclature.Code Nomenclature.Description Nomenclature.MainSupplier

Contractor
Nomenclature Nomenclature attributes
Nomenclature.Code
Nomenclature.Description
Nomenclature.MainSup
Chapter 10. Data Composition System 1-629

□□ Horizontally – fields are output horizontally from left to right.

Contractor
Nomenclature Nomenclature attributes
Nomenclature.Code Nomenclature.Description Nomenclature.MainSup

□□ Vertically – fields are output vertically one under another.

Contractor
Nomenclature Nomenclature attributes
Nomenclature.Code
Nomenclature.Description
Nomenclature.MainSup

□□ InSeparateColumn  – fields are output in  a separate column in  the

right-most position:
Contractor Contractor.Code
Nomenclature Nomenclature attributes
Nomenclature.Code Nomenclature.Description Nomenclature.MainSup

□□ Together – fields are output together and are separated by commas.

Contractor
Nomenclature Nomenclature attributes
Nomenclature.Code, Nomenclature.Description
Nomenclature.MainSupplier

○○ Output of resource fields. Location of resource fields is  managed through

the special ResourcePlacement property of the OutputParameters
object. The  following location options are possible:
□□ Horizontally – resource fields are located horizontally from left to right;
□□ Vertically – resource fields are located vertically one under another.
If a  folder has no header, no space is  left for the header in  the template. In  this
case fields are output based on the Folder Placement property.

Use of Appearance Template

After the groups and fields are placed, the appearance template is  applied to the
created area. When the appearance template is applied, the previously defined
appearance properties (such as BackColor or TextColor) are added to all the items
of an area template. It  is  worth mentioning that there are many area appearance
templates.
Use of Conditional Appearance
After applying the appearance template, conditional appearances are applied to
the area template. Use the conditional appearance to add the appearance properties
1-630 1C:Enterprise 8.3. Developer Guide

containing logical expressions to the area template. As a  result of the calculation

of a  logical expression, a  decision is  made about what value of the appearance
property must be used.
Merge Cells
A generated area template can have unfilled cells. Such cells must be merged to
obtain a  more visual representation of an area template. The  following cell loca-
tion options are possible:
„„ Unfilled cells are located to the right of the filled cells. Cells that are located to
the right are merged with the cells on the left.

Fig. 259.  Unfilled Cells to the Right

„„ Unfilled cells are located under the filled cells. Cells that are located below are
merged with the cells above.

Fig. 260.  Unfilled Cells at the Bottom

„„ Unfilled cells are located to the right and under the filled cells. Cells that are
located to the right are merged with the cells on the left. Then cells that are
located below are merged with the cells above.

Fig. 261.  Unfilled Cells at the Bottom and to the Right

10.4.3.1. Generation of Data Composition Template

The data composition template is  generated on the basis of the data composition
schema and settings. The  data composition schema is  created by the report devel-
oper and the settings are entered by the user.
The composition template is generated using the 1C:Enterprise script object,
DataCompositionTemplateComposer.
This object has no properties and has one method (Execute()) which receives the
data composition schema, data composition settings, variable where the Detail-
Chapter 10. Data Composition System 1-631

Data object is placed and the appearance template. This method returns the
created data composition template.
The template composer:
„„ creates a  composition template;
„„ modifies the data set queries for obtaining the information the user requires and
places them in  the composition template;
„„ generates filters in  the query text or the data set description;
„„ if necessary, creates data sets for obtaining and checking the hierarchy;
„„ creates the required parameters with values set by the user in  the data composi-
tion template;
„„ fills in  body items of the data composition template, in  which it  places groups,
tables, etc. and fills in  their parameters;
„„ uses the template area generator (see page 1-624). If an appearance template
is  specified (parameter № 4), this template is  applied to the generated template;
„„ creates the DetailsData object and places it  in  the passed variable if param-
eter № 3 is  specified. The  created object should be used in  the composition
processor and in  processing the details.
When the data composition template compiler generates a data composition
template it  analyzes the Group parameter value of the EvalExpression() func-
tion. If the parameter contains a  name of the group that exists in  the settings, the
template compiler does not change this name. Otherwise, the template compiler
searches in the current group's parent groups for the group with group fields
containing all the fields specified in the Group parameter of the EvalExpres-
sion() function and then puts the name of the group found in  this parameter.
For example, if the Nomenclature, NomenclatureCharacteristic string
is  specified as the parameter for the EvalExpression() function, then during the
template generation the template compiler locates a  group for the Nomenclature
and NomenclatureCharacteristic fields and places the name of the group
found into the generated template. The  group is  searched in  groups that are avail-
able in  the place where the group is  evaluated. Thus, when the template compiler
generates an expression for a table cell, the group will be searched in column
groups for which a  cell is  displayed; row groups for which a  cell is  displayed;
and groups in  which a  table is  nested. Groups to which the EvalExpression()
function can be applied are found in  this way. If multiple groups are found, the
closest group is selected. In a table, a group is searched in a row, then in a
column, and then a  group is  searched above the table.
If the group is  not found, the expression is  replaced with NULL.
Actually, this allows you to use EvalExpression() in  user fields by specifying
groups by group field names rather than by names alone.
1-632 1C:Enterprise 8.3. Developer Guide

Example:
DataCompositionschema = GetDataCompositionschema();
ExcutableSettings = GetExcutableSettings();
TemplateComposer = New DataCompositionTemplateComposer;
CompositionTemplate = TemplateComposer.Execute(DataCompositionSchema, ExecutableSettings);

The created data composition template can be used for execution, i.e. for obtaining
the result.

10.5. DATA COMPOSITION PROCESSOR

Data composition is executed using the 1C:Enterprise object, DataCompositi-
onProcessor.
The data composition template is  transferred to the processor input.
The operation of the data composition processor is very simple: after the data
composition template has been set for the data composition processor, you can
sequentially obtain the data composition result items from this object; you can then
further use them, e.g. output into a  spreadsheet document or save for further use.
Below is  an example of working with the data composition processor:
FormElements.SDResultSpreadsheetDocument.Clear();

DCTemplate = GetCompositionTemplate();

DCProcessor = New DataCompositionProcessor;

DCProcessor.Initialize(DCTemplate);

OutputProcessor =
New DataCompositionResultSpreadsheetDocumentOutputProcessor;
OutputProcessor.SetDocument(FormElements.SDResultSpreadsheetDocument;
OutputProcessor.BeginOutput();

While True Do
DCResultItem = DataCompositionProcessor.Next();
If DCResultItem = Undefined Then
Abort;
EndIf;

OutputProcessor.OutputItem(DCResultItem);
EndDo;

OutputProcessor.EndOutput();

When the data composition process is  initialized, the following can be specified:
„„ External data set object: a  structure that contains the external data set name as
its key and a  data set as its value;
„„ Details data: an object where drill down information is  placed;
Chapter 10. Data Composition System 1-633

„„ External function use feature: a flag that indicates whether functions of the
configuration's common modules can be used.

10.6. FUNCTIONAL OPTIONS AND RIGHTS TO VIEW FIELDS

IN  REPORTS
When the system obtains the default report settings, it automatically does the
following:
„„ If the user has no rights to view a  field interactively or the field is  associated
with the disabled functional options, it becomes unavailable for user setup.
In  other words, it  is  not displayed in  the list of available fields.
„„ If the field is  linked to the attribute which type is  disabled by the functional
option then this field is  removed from the list of available fields.
„„ The query table and attributes of this table become unavailable if the functional
options disables the configuration object that.
„„ If the field that cannot be viewed by the user due to insufficient rights or
is  associated with a  disabled functional option, is  used in  a user field, the user
field is  removed and is  not used to set a  filter.
„„ The data composition system field is  considered unavailable if all fields used
in this field's expression are linked to disabled functional options. All fields
included in  the field query expression are used, as are any expressions from
unions.
„„ All fields that cannot be viewed by the user due to insufficient rights or are
associated with a disabled functional option, are removed from the group
fields. If you remove a  group field and the group has no group fields with the
enabled use flag, the entire group is deleted, while its contents (e.g., if the
group includes a  table) replaces the group.
„„ If a  row or column group is  removed and the table has no other groups, the
table is  deleted.
„„ If a  series or point group is  removed and the chart has no other groups, the
chart is  deleted.
„„ All fields that cannot be viewed by the user due to insufficient rights or are
associated with disabled functional options, are removed from the appearance
fields of a conditional appearance item. If the appearance field is removed
from the conditional appearance item and the item has no other appearance
fields with the enabled use flag, the item is  also deleted.
„„ If a  conditional appearance item filter uses a  field that cannot be viewed by the
user due to insufficient rights or is  associated with disabled functional options,
the conditional appearance item is  deleted.
If a  field used to be available and the user has saved its setting and loads it  in  the
future (when the field is unavailable), the fields are not automatically removed
1-634 1C:Enterprise 8.3. Developer Guide

from the setting. This  functionality allows the user to replace unavailable fields by
other fields or to remove their use from the settings.
If the AutoFillCheck parameter is  set to True when the Execute() method of
the DataCompositionTemplateComposer object is  executed, the system checks
whether fields are available to the current user and whether a  field exists in  an
enabled functional option. If the settings use an unavailable field, an exception
is  raised. If the parameter is  False, no check is  performed.
NOTE
If a  report is  execute from an auto-generated form, the system checks whether
fields are available to the current user and whether a  field exists in  an enabled
functional option.

10.7. DATA COMPOSITION RESULT

The data composition result is  a set of items of the data composition result. The  data
composition result does not exist as a  1C:Enterprise script object; only a  set of items
of the data composition result exists, with these items forming the result.
If necessary, items of the data composition result can be placed in a universal
collection of values, e.g. Array, to manipulate the result as a  whole.
The result items can be obtained using the DataCompositionProcessor object or
they can be created and filled in  by means of 1C:Enterprise script.
Use the output processor to output items of the data composition result in  a spread-
sheet document.
Review an example of data items below.
Item 1

Property Value
Item type Begin
Templates TableHeader,
ColumnHeader,
RowHeader,
Resources
Placement of nested items Vertically

Item 2
Property Value
Item type Beginning
Placement of nested items Horizontally

Item 3
Property Value
Item type BeginEnd
Template name TableHeader
Chapter 10. Data Composition System 1-635

Item 4

Property Value
Item type BeginEnd
Template name ColumnHeader

Item 5

Property Value
Item type End

Item 6

Property Value
Item type Begin
Placement of nested items Horizontally

Item 7

Property Value
Item type BeginEnd
Template name RowHeader

Item 8

Property Value
Item type BeginEnd
Template name Resources

Item 9

Property Value
Item type End

Item 10

Property Value
Item type End

The output result for such items must look like the following:
TableHeader ColumnHeader
RowHeader Resources

If item 2 contained TableHeader and RowHeader templates, a template from

this item would be used when outputting item 3; however a  template from item 1
would be used when outputting item 7, as item 2 is  finished with item 5.
1-636 1C:Enterprise 8.3. Developer Guide

The result items can be saved in  XML using the standard tools, as shown in  the
example below.
XMLWriter = New XMLWriter;
XMLWriter.SetString();
XMLWriter.WriteStartElement("result");

DataCompositionTemplate = GetCompositionTemplate();

DataCompositionProcessor = New DataCompositionProcessor;

DataCompositionProcessor.Initialize(DataCompositionTemplate);

While True Do
DataCompositionResultItem = DataCompositionProcessor.Next();
If DataCompositionResultItem = Undefined Then
Abort;
EndIf;
XDTOSerializer.WriteXML(XMLWriter, DataCompositionResultItem,
"item", "http://v8.1c.ru/8/data-composition-system/scheme");
EndDo;

XMLWriter.WriteEndElement();

FormElements.DataCompositionResult. SetText(XMLWriter.Close());

10.7.1. Composition Result Output to Spreadsheet Document

Use the DataCompositionResultSpreadsheetDocumentOutputProcessor
object to output a  report to a  spreadsheet document.
Composition result items can be obtained using the data composition processor or
generated by any other tools.
Below is  an example of data composition result output in  a spreadsheet document:
FormElements.SDResultSpreadsheetDocument.Clear();

DataCompositionTemplate = GetCompositionTemplate();

DataCompositionProcessor = New DataCompositionProcessor;

DataCompositionProcessor.Initialize(DataCompositionTemplate);

OutputProcessor = New
DataCompositionResultValueCollectionOutputProcessor;
OutputProcessor.SetDocument(FormElements.SDResultSpreadsheetDocument;
OutputProcessor.BeginOutput();

While True Do
DataCompositionResultItem = DataCompositionProcessor.Next();
If DataCompositionResultItem = Undefined Then
Abort;
EndIf;
OutputProcessor.OutputItem(DataCompositionResultItem);
EndDo;

OutputProcessor.EndOutput();
Chapter 10. Data Composition System 1-637

You can also use the Output() method of the OutputProcessor object. Specify
DataCompositionProcessor as a  method parameter. In  this case layout result
output appears as follows:
OutputProcessor.Output(DataLayoutProcessor);

The data composition processor freezes the table tile if one table or one group
is  shown in  the report (possibly with nested groups). You can manage the fixation
(left and top) using the output setting FixedLeft and FixedTop.

10.7.2. Composition Result Output to Value Table

and Value Tree
You can output the report to a value table or a value tree by means of the
DataCompositionResultValueCollectionOutputProcessor object.
The  SetObject() method is similar to the SetDocument() method. If the
SetObject() method is  not called, the result is  output to a  value table.
Composition result items can be obtained using the data composition processor or
generated by any other tools.
Below is  an example of layout result output to a  value tree:
TemplateComposer = New DataCompositionTemplateComposer;
DataCompositionTemplate = TemplateComposer.Execute(
DataCompositionSchema,
SettingsComposer.Settings,
,
,
Type("DataCompositionValueCollectionTemplateGenerator"));

DataCompositionProcessor = New DataCompositionProcessor;

DataCompositionProcessor.Initialize(DataCompositionTemplate);

OutputProcessor = New
DataCompositionResultValueCollectionOutputProcessor;
OutputProcessor.SetObject(ResultTree);
OutputProcessor.BeginOutput();

While True Do
DataCompositionResultItem = DataCompositionProcessor.Next();
If DataCompositionResultItem = Undefined Then
Abort;
EndIf;
OutputProcessor.OutputItem(DataCompositionResultItem);
EndDo;

OutputProcessor.EndOutput();
1-638 1C:Enterprise 8.3. Developer Guide

The following limitations exist for layout result output to a  value table or tree:
„„ Settings must only contain groups and detail records. No tables, charts or nested
reports are allowed;
„„ All folders specified in  the selected fields are ignored;
„„ Neither conditional appearance nor field appearance specified in the data
composition schema can be used;
„„ Only the following output parameters are allowed:
○○ Vertical placement of overalls;
○○ Field header type;
○○ Record count;
○○ Records percent.
„„ Predefined templates are not used.
Two template types are implemented to output results to a  value table or tree: the
Header Template (DataCompositionAreaTemplateValueCollectionHeader)
and the Contents Template (DataCompositionAreaTemplateValueCollection).

10.8. CALCULATION OF TOTALS BY BALANCE FIELDS IN  DATA

COMPOSITION SYSTEM
In terms of the data composition template, a balance field is a field that has
a  Balance flag.

10.8.1. Calculation of Totals by Balance Fields

If the data composition template has a  data set with an opening balance field, the
data set must also contain a  corresponding closing balance field and vice versa.
All the period fields described in  the data set must have continuous numbering,
starting with 1.
To calculate totals by data source fields correctly, the data must meet the following
criteria: the period fields and dimension fields must be unique within the data, i.e.
data must not contain rows with identical period and dimension field values.
Use the following algorithm when calculating the totals by balance fields.
If it  is  necessary to calculate the totals of a  balance field for a  group by a  period
field:
„„ If the grouping has already been carried out by all the period fields:
○○ For every combination of the dimension fields, by which grouping has been
carried out:
□□ record which is  the closest to the current period is  obtained;
□□ if the obtained record corresponds to the current period, the opening and
closing balance is  obtained from this record;
Chapter 10. Data Composition System 1-639

□□ otherwise if the obtained record has a  previous period, a  closing balance

of the record is  used as an opening and closing balance;
□□ otherwise an opening balance of the obtained record is  used as an opening
and closing balance.
Alternatively (grouping has not yet been carried out by all the period fields):
„„ For every combination of the dimension fields, by which grouping has been
carried out:
○○ the first and the last records in  which fields of the used periods are equal to
the current period are obtained;
○○ if the records are found, then the first record is  used as the opening balance
and the last as the closing balance;
○○ if records are not found, the closest record is  obtained and its balances are
used as the opening and closing balance, depending on whether the obtained
record precedes or follows the current period.
Alternatively (grouping by the period field hasn’t been carried out):
„„ the first chronological records for the unused dimension fields are used as
records of the opening balance; the last records are used as records of the
closing balance.

10.8.2. Calculation of Totals by Accounting Balance Fields

The calculation of the totals by accounting balance fields is  similar to the calcula-
tion of totals by standard balance fields. In  addition, the account field information
is  used when calculating totals by these fields. If totals are calculated for a  group
by an account field or if grouping by an account field precedes the group, for which
the totals are calculated, the account type is  used for calculation. Otherwise the
account type is  considered to be active/passive.
Depending on the type of account, the total balance is calculated using the
following formulae:
„„ If the obtained balance is  > 0
Dr Cr
Active Balance 0
Passive 0 Balance
Active/Passive Balance 0

„„ If the obtained balance is  < 0

Dr Cr
Active Balance 0
Passive 0 Balance
Active/Passive 0 Balance
1-640 1C:Enterprise 8.3. Developer Guide

10.8.3. Template Composition

To ensure the correct calculation of totals, the template composer executes addi-
tional actions when generating a  template:
„„ If the opening balance is  used, it  automatically adds the closing balance field
to the query, even if it  is  not used and vice versa.
„„ If the dimension attribute field is used, it automatically adds the dimension
field to the query, even if it  is  not used.

10.9. WORKING WITH HIERARCHY

IN  DATA COMPOSITION SYSTEM
In the data composition system, the following items can be used within hierarchy:
„„ Hierarchical groups
„„ IN HIERARCHY condition
Let us consider the above items in  more detail.

10.9.1. Hierarchical Groups

When a  group is  created, a  user can specify that a  hierarchical group is  required
for a  certain field of the group.
For the system to carry out hierarchical grouping, the data composition processor
must know where to obtain the data to build the hierarchy. This  is  implemented by
creating a  data set and linking it  to itself.
Consider the following example. Assume it  is  necessary to build a  hierarchy for
the field of the Catalog.Nomenclature type.
The data set for the hierarchy looks like the following:
SELECT
Nomenclature.Ref AS Ref,
Nomenclature.Parent AS Parent
FROM
Catalog.Nomenclature AS Nomenclature
WHERE
Nomenclature.Ref IN(&Refs)

For this data set it  is  necessary to define the link from the Parent field to the
Nomenclature field with the Ref parameter. Therefore, the data set can be used to
obtain all the item parents in  sequence.
The data set for hierarchy construction can either be expressly described in the
data composition schema or automatically generated by the composer of the data
composition template.
Chapter 10. Data Composition System 1-641

If the hierarchy data set is  specified in  the composition schema, it  is  necessary to
add a  query of the following type:
SELECT
Nomenclature.Ref AS Ref,
Nomenclature.Parent AS Parent
{SELECT
Ref.*,
Parent}
FROM
Catalog.Nomenclature AS Nomenclature
WHERE
Nomenclature.Ref IN(&Refs)

This data set must be linked to itself, as described above. Additionally it  is  neces-
sary to create a  link to the data set from the field, for which the hierarchy must be
built.

10.9.2. Hierarchical Detail Records

Detail records with hierarchy can be output to a  report, using data set link settings.
For example, define the Nomenclature data set:
SELECT
Nomenclature.Ref,
Nomenclature.Parent,
Nomenclature.Code,
Nomenclature.Description,
Nomenclature.IsFolder
FROM
Catalog.Nomenclature AS Nomenclature
WHERE Nomenclature.Parent IN (&Parents)

Define the Nomenclature data set link to itself.

Set the Ref field as the source expression and the Parent field as the destination
expression. Specify the Parents field as a  link parameter that can get a  list of
parameters. Thus, the system selects the Ref field value from each row of the data
set and retrieves records that contain this value in the Parent field. To ensure
that child items are selected only in  groups, set the link condition expression to be
equal to the IsFolder field. Use the Value(Catalog.Nomenclature.EmptyRef)
expression as the initial value of the hierarchical link. It  means that at the top level
of the hierarchical data set, records, where the Parent field is  an empty reference
to the Nomenclature catalog, are retrieved.
To output such a  data set to a  report, simply output detail records in  the composi-
tion schema settings (add Code and Description to the selected fields list).
The result is  shown on fig. 262.
1-642 1C:Enterprise 8.3. Developer Guide

Fig. 262.  Hierarchical Detail Records

10.9.3. Output of a  Single Item in  Multiple Parent Records

When creating a hierarchy, the data composition system enables you to output
a  single item to several parent records.
Review an example.
Create two catalogs within the configuration: Children and Employees.
In the Employees catalog, generate the following records: Mary Jones, John Jones.
In the Children catalog, generate the following record: Samuel Jones.
Assume the Children information register contains the following records:
Child Parent
Samuel Jones John Jones
Samuel Jones Mary Jones

Create a  query for the Children data set which will get the list of children:
SELECT
Children.Ref
FROM
Catalog.Children as Children
Chapter 10. Data Composition System 1-643

Additionally create a  query for the Hierarchy data set which will get hierarchical
records:
SELECT
EmployeeChildren.Child AS Ref,
EmployeeChildren.ChildParent AS Parent
FROM
InformationRegister.EmployeeChildren AS EmployeeChildren
WHERE
EmployeeChildren.Child IN(&Ref)

MERGE ALL

SELECT
Employees.Ref,
NULL
FROM
Catalog.Employees AS Employees
WHERE
Employees.Ref IN(&Ref)

The first query union selects the children's parents. The  second part of the query
selects employees, since the hierarchical set also has to contain hierarchical records.
Define links between the data sets.
Specify the Children data set as the link source and the Hierarchy data set as the
destination. The  Ref field is  the source expression and another Ref field is  the
destination expression. Specify the Ref field as the link parameter and indicate that
a  list of parameters is  allowed.
Define the hierarchical link. Link the Hierarchy data set to itself, Parent being
the source field and Ref being the destination field. Specify the Ref field as the link
parameter and indicate that a  list of parameters is  allowed.
IMPORTANT!
The hierarchical data set field that the data set is  linked to must have the same
name as in  the source data set. Otherwise the system fails to obtain field attributes
for the hierarchical set, nor does it  obtain presentation for hierarchical values.
In the report settings, create the hierarchical group by the Ref field and switch the
field’s presentation to Parent. Execute the report:

Fig. 263.  Resulting Table

This will result in  the Samuel Jones record appearing in  both groups.
1-644 1C:Enterprise 8.3. Developer Guide

10.9.4. IN HIERARCHY Condition

Users can specify the IN HIERARCHY condition for a  field. In  this case the user
should obtain records that are in  the hierarchy of the specified reference.
If such a condition is specified in the global filter, this condition is included
in the query text as the IN HIERARCHY condition. If the condition is not used
in the global filter, the data composition processor must have the data set that
contains the references meeting the condition, to process it.
Such a  data set can be either expressly described in  the data composition schema
or automatically generated by the template composer.

10.10. USE OF DATA COMPOSITION SYSTEM

IN  APPLICATION DEVELOPMENT
When application solutions are developed, the data composition system can be used
by the 1C:Enterprise script based on the object model described above.
Moreover, the data composition system can be applied in  visual report generation.
For example, after the Report configuration object is created, a template with
a  data composition schema can be generated for the report. To do this, click the
Open button next to the Main data composition schema text box.

Fig. 264.  Data Composition Schema Creation

The Open data composition schema button opens the main data composition
schema. If no schema is  available, a  new one is  created and assigned as the main
schema.
Chapter 10. Data Composition System 1-645

All of the above actions result in  opening the template wizard that can be used to
create a  template containing the data composition schema.

Fig. 265.  Template Wizard

Clicking Finish opens the data composition schema wizard that is  used to create
a  data composition schema (see page 1-547) or load an existing schema from an
XML-document.
After the data composition schema is  created, the report is  ready for use and can
be launched in  the 1C:Enterprise mode. When the report is  launched, the system
auto-generates a  report form and a  settings form.
In addition to the main report form, the following can be selected at the Forms tab:
„„ A report settings form that opens upon execution of the Settings command
in  the 1C:Enterprise mode and is  used to specify parameters for user settings
(see page 1-610).
„„ A report variant editing form (to open it, select More  – Change variant
(All actions  – Change variant) in  the menu of the automatic report form) that
can be used by advanced users to edit the current report variant (see page
1-599).
1-646 1C:Enterprise 8.3. Developer Guide

Fig. 266.  Report Form Settings

If the forms auto-generated by the system in  the course of report use and based on
the data composition system, are not convenient for the end users, the application
developer can create custom forms. It  can be done in  the report form wizard.

Fig. 267.  Report Form Wizard

Chapter 10. Data Composition System 1-647

10.10.1. Input Parameters

Input parameters can be specified in the data composition schema for data set
fields, calculated fields and parameters. These parameters describe how values are
to be entered for fields in  a filter or parameters. For example, Quick choice can be
enabled for the Nomenclature field in  the Inventory Balances report. This  feature
can later be used, when a  filter by nomenclature is  set up. A special selection form
can be selected for the Warehouse field in  the same report.
For details on input parameters see the built-in help.

10.10.2. Use of Metadata Object Properties in  Reports

If a data composition schema uses a query data set, information about input
parameters and some appearance parameters is  retrieved from metadata objects for
the data set fields. Thus, if the data composition schema does not have an input or
output parameter, its value is  automatically retrieved from an appropriate metadata
object.
The following input parameters are retrieved from metadata objects:
„„ Mask
„„ Choice parameter links
„„ Link by type
„„ Items of a  link by type
„„ Selection form
„„ Edit format
„„ Quick choice
Additionally the following output parameters are retrieved from metadata objects:
„„ Format
„„ Mark negatives
„„ Multiline mode

10.10.3. Background Report Execution

Situations may arise in  the system operation process where reports are generated
for a long period of time. It is  is a good idea for a user to have the ability to
perform operations in  the system while a  report is  being generated. This  ability
is  provided by the background report generation method (using background jobs).
An automatically generated form report uses background report execution in  client/
server mode, and in the file mode version, direct report generation is used. If
background report execution is  not required in  the client/server mode, you can use
the ComposeResult() report form extension method, specifying the direct report
generation attribute as the parameter.
1-648 1C:Enterprise 8.3. Developer Guide

Example:
ComposeResult(ResultCompositionMode.Directly);

If during background report generation user settings are interactively changed or

the report variant is  changed or selected, report execution will be stopped and the
spreadsheet document will be shown with lighter colors.
If during background report generation the report form is closed, report execu-
tion will be stopped automatically, even if the StandardProcessing parameter
is  set to False in  the BeforeClose report form event handler. Report execution
is  stopped (as well as the background job) after the OnClose report form event
handler is  called.
The status window can be displayed during background report execution.
The  status window will be generated if this is  allowed (StatusAutoShowMode)
and if the report is generated for longer than 2 seconds (4 seconds in the slow
connection mode). The  data composition system uses the ShowStatus property of
the spreadsheet document field to show report status. If the report was generated for
the specified time, the status is  not shown and the result is  shown instead.
Report generation completion is  validated by the client application within the set
period of time. The  interval between every next validation is  1.4 times longer than
the previous one (but not longer than 20 seconds).
The StatusAutoShowMode report form extension property is  used to manage the
report status display mode. This  property specifies how the spreadsheet document
showing report results will display report status. By default (e.g., for an auto-
matically generated form) this property is  set to Auto. This  means that the status
window will show that the report is  up-to-date and is  still being generated.

10.11. SPECIFICS OF USING OF DATA COMPOSITION SYSTEM

„„ The data composition system does not allow use of data paths with names
that are identical to keywords: CASE; WHEN; THEN; ELSE; END; IS; NOT; LIKE;
ESCAPE; DISTINCT.
„„ If a standard period parameter has an empty begin or end date, its nested
BeginDate and EndDate parameters are considered unspecified. In other
words, if the Period parameter has an empty begin date, the Period.Be-
ginDate parameters is  considered unspecified. A similar approach is  used for
the Period.EndDate parameter and the period end date. Consequently, param-
eters with expressions that use the Period.BeginDate and Period.EndDate
parameters are also considered unspecified.
„„ A query is invalid if it contains the DISTINCT keyword and its ORDER BY
clause indicates an expression that is  not in  the selection list.
„„ Grouping by period field attribute fields is  not allowed.
Chapter 10. Data Composition System 1-649

„„ If the user has no rights to view a  metadata object interactively, the composi-
tion system makes all the object table fields unavailable.
Assume the following query is  used as a  data set:
SELECT
Doc.Ref.Date,
Doc.Ref.Number,
Doc.Nomenclature,
Balances.Balance
FROM Document.Invoice.Content AS Doc
LEFT JOIN AccumulationRegister.NomenclatureAccounting.Balance Balances
BY Doc.Nomenclature = Balances.Nomenclature

If the user has no interactive rights for the Invoice or Invoice.Content table,
the Date, Number and Nomenclature fields are unavailable. If no rights are
granted for the AccumulationRegister.NomenclatureAccounting table,
the Balance field is  unavailable. If the user has no rights to any tables, none of
the fields is  available.
„„ The hierarchical data set field that the data set is  linked to must have the same
name as in  the source data set. Otherwise attributes fields cannot be retrieved
from the hierarchical data set.
„„ If a dataset query in the selection list results in an expression representing
usage of the REPRESENTATION() function to the expression in  another field,
the field getting the representation will not be available in  settings when fields
are automatically populated.
„„ An error will occur during data composition when grouping is  executed for the
calculated field and the group requires an extension of the period.
„„ Autoindentation is  used only for the top left template cell in  data composition
system group templates.
„„ If you use a batch query in the data composition system, the fields that are
not used in  the consequent batch queries are deleted from the list of selections
and grouping fields. If a  query that forms a  temporary table does not contain
a  single field, the query is  removed from the batch query. Data sets from which
no fields are used are also removed from the resulting composition template. To
prevent field removal, you need either to use the field, or to set the Required
checkbox in  the field role of a  data composition layout.
„„ When data composition result is  is put to a  collection of values the fields of
different groups, that contain a  reference to the one and the same data composi-
tion field, are put to the one column of the collection.
„„ When MERGE or MERGE ALL is  used in  the data composition data set query with
automatic filling of available settings and when a  filter is  applied to the field
attribute, the filter is  applied only in  those parts of union where this attribute
exists. A filter is  applied only to fields with expressions that are not equal to 0.
1-650 1C:Enterprise 8.3. Developer Guide
Chapter  11

ACCOUNTING

Accounting in the 1C:Enterprise system is done by the Charts of accounts

and Accounting registers configuration objects. Since these objects are closely
connected, this chapter outlines the features they provide.
The subsequent sections discuss the issues of configuring the mentioned objects.

11.1. OVERVIEW
The Designer allows you to organize accounts among several charts of accounts and
to build a  custom hierarchy of subaccounts for each chart of accounts. Accounting
totals are stored separately by the 1C:Enterprise system for each chart of accounts.
Flexible account numbering, using both numbers and letters, is  permitted for the
charts of accounts.
Analytical accounting is possible for any account or subaccount, using various
analytical combinations. 1C:Enterprise system catalog items, documents or random
numbers, dates and strings may be objects of analytical accounting.
Configuration tools allow maintaining an unlimited number of accounting types
for each chart of accounts. Typical examples of account types are quantitative and
foreign currency accounting.
An accounting type is  selected during the editing of the chart of accounts. The  type
of accounting to be maintained can be selected for a  particular account.
The Designer provides tools to set up accounting for multiple enterprises in  the
same infobase. You can derive the information on the final amount for a  separate
enterprise or for all enterprises collectively. This  function may be useful for enter-
prises with a  consolidated balance.
1-652 1C:Enterprise 8.3. Developer Guide

11.2. CHARTS OF ACCOUNTS

A chart of accounts is  one of the basic concepts in  accounting. A chart of accounts
is  a set of synthetic accounts intended for grouping information on the enterprise's
commercial operations. Data stored in  synthetic accounts enables the user to get
a  complete picture of the state of enterprise’s funds in  monetary terms.
The 1C:Enterprise system provides flexible capabilities for maintaining charts of
accounts. In  fact, it  is  by setting the chart of accounts that the required accounting
system is  organized.
Multiple charts of accounts. The  1C:Enterprise system can have several charts of
accounts and books can be kept under all charts of accounts simultaneously. From
a  technical standpoint, the total number of charts of accounts you can keep in  the
system is  unlimited and defined only by real accounting needs.
For example, this kind of "multi-chart" accounting can be useful for joint enter-
prises that need to conduct their accounting with two or more accounting standards
simultaneously.
Subaccounts. Charts of accounts in  1C:Enterprise support the "account – subac-
count" multilevel hierarchy. Each chart of accounts can include an unlimited
number of top-level accounts. Each account can also have an unlimited number of
subaccounts. Every subaccount, in  its turn, has subaccounts of its own – and so on.
The  number of subaccount levels in  the 1C:Enterprise system is  unlimited.
The structure of the account code can be specified when a chart of accounts
is  created in  the form of a  template consisting of an arbitrary sequence of char-
acters. Technically, the structure of an account code does not affect the hierarchy
of accounts, but when creating the structure of accounts, we recommend that you
adhere to the code structure.
Separate account editing. Errors in  accounting are known to occur often due to
the incorrect application of the approved chart of accounts. The most common
situation is  an absence of analytical accounting in  cases where a  detailed balance
is  needed. In  such cases, although the accounting is  formally correct (everything
"fits"), the bottom line results are incorrect. For this reason it  is  often useful to
restrict end users when setting up charts of accounts.
To accomplish this, 1C:Enterprise allows you to divide the editing process up for
charts of accounts.
First, the chart of accounts can be edited by the specialist who configures
1C:Enterprise in  the Designer.
New charts of accounts can be created in the Designer. The main properties
of a chart of accounts are specified during configuration of the given chart of
accounts: the account and length of its code; the maximum count of Extra Dimen-
sions an account (subaccount) can have and other properties. Here you can also
enter the necessary accounts and subaccounts (predefined accounts) in  the chart of
accounts, as well as set up the accounting types for the accounts.
Chapter 11. Accounting 1-653

Secondly, when operating 1C:Enterprise, the end user can add custom accounts
and subaccounts to the charts of accounts, but he/she cannot delete the predefined
accounts and subaccounts created in  the Designer.
Storing accounting totals. Accounting totals are stored in accounting regis-
ters, using the chart of accounts structure. Totals information can be viewed
in  accounting register forms and can also be derived using the 1C:Enterprise script
which has methods for obtaining account turnovers and balances for any type of
accounting, both for an account or subaccount as a  whole or divided into analytical
accounting objects.

11.3. ANALYTICAL ACCOUNTING

Company asset information which is  recorded in  accounts is  often summary-like
in  nature. For example, a  standard chart of accounts contains account 10 called
"Materials" and consolidating "general information about availability and move-
ment of raw materials, materials, fuel, spare parts, package materials, etc. possessed
by the company". Account 10 may have several subaccounts opened for various
kinds of materials. But organized this way, the subaccounts store the total values of
materials by type and account 10 stores the total value of all the materials.
To get detailed information on the availability of certain materials, it  is  necessary
to set up analytical accounting for materials. In  this case the subaccount totals are
split into smaller totals representing the value of specific materials.
A special mechanism called Extra Dimension organizes analytical accounting
in 1C:Enterprise.
Notion of Extra Dimensions. An analytical accounting object in 1C:Enterprise
is called an Extra Dimension. The term "Extra Dimension" may represent
any analytical accounting objects: fixed assets, intangible assets, materials
organizations, subordinates, contracts and budgets. The  multiplicity of single-type
analytical accounting objects is  called an Extra Dimension type.
For example, liabilities to customers and clients are necessarily kept according to
normative documents, separately for each customer and client. In  1C:Enterprise,
the list of customers and clients (assuming they are only entities) is  called Organi-
zations extra dimension type and any entity in  this list is  called Extra Dimension.
The 1C:Enterprise Designer allows the creation of any number of Extra Dimension
types to achieve the required completeness in  analytical accounting for the company.
As a  universal means for describing the properties of analytical accounting objects,
the Chart of characteristic types objects are used.
IMPORTANT!
Using primitive types is  not recommended for charts of characteristic types used
as Extra Dimension types in  the chart of accounts. It  may have a  substantial
effect on performance when writing accounting register records. It is recom-
mended to use reference types only.
1-654 1C:Enterprise 8.3. Developer Guide

Setting up analytical accounting. In  1C:Enterprise, analytical accounting can be

kept for any account or subaccount. To do this, when editing charts of accounts,
an appropriate Extra Dimension type is  attached to the required account or subac-
count. Several different types of Extra Dimensions can be attached to an account
or subaccount (the maximum count is  defined in  the Maximum number of extra
dimensions property), thus allowing analytical accounting to be kept in  any neces-
sary combination.
Information about business operations is entered into 1C:Enterprise as accounting
register records. Analytical accounting objects should be specified for each corre-
sponding account of the record if analytical accounting is  appointed for these accounts.
For example, in  industrial companies the following types of Extra Dimensions can
be attached to the production cost account: Cost types for types of cost accounting,
Goods for types of manufactured goods account (products, services) and Subdivi-
sions for department accounting. Analytical information on costs can be derived
from any of these types of Extra Dimensions.
Moreover, the analytical accounting features of 1C:Enterprise allow you to keep
a  record of the same analytical object in  different combinations.
Thus, a single catalog can be appointed to various types of Extra Dimensions.
For example, a  company buys components from suppliers and sells finished goods
to customers. In this case in 1C:Enterprise, the Organizations catalog can be
appointed as the Vendors and Buyers Extra Dimension types.
Extra dimensions and subaccounts. Chart of accounts properties in  1C:Enterprise
(especially a  large number of nested levels of subaccounts or a  long subaccount
code) still allow you to set up analytical accounting using subaccounts instead of
Extra Dimensions. However, the features of analytical accounting using subac-
counts and Extra Dimensions are fundamentally different.
Subaccounts have a hierarchical structure subordinate to a specific synthetic
account. For example, to record customer debt owed to the enterprise in the
customer control account (account 62 in the standard chart of accounts),
it  is  possible to open a  separate subaccount for each customer to record their debt.
This  method allows you to obtain information on the total sum the enterprise owes
to a  certain customer, as well as the total sum of the liabilities to all customers –
derived by adding up all the debt amounts from all the subaccounts.
However, if a buyer organization also becomes a supplier to the enterprise, an
account will need to be set up for recording operations with this entity as a  supplier.
By keeping analytical accounting in  subaccounts for this new vendor, it  is  obvi-
ously necessary to open a  new subaccount, this time in  the account for operations
with suppliers (account 60). Now, if you keep the record in  this subaccount, you
can obtain the information about mutual settlements with this entity as a  supplier.
But to obtain information about the general status of mutual settlements with
this entity, you need to combine the records on settlements with this entity from
Chapter 11. Accounting 1-655

two different accounts. To do so, you need to remember which subaccount of the
customers' account and which subaccount of the suppliers' account correspond to
this specific entity, then retrieve the information on the status of settlements with
this entity and process it.
When using Extra Dimensions, one Extra Dimensions list, like Organizations,
for example, is  attached to all the accounts (subaccounts) for which you need to
keep analytical accounting on entities. The  record of a  specific entity as a  supplier
is  kept in  the corresponding control account. If the entity also becomes a  buyer,
there is  no need to create a  new entry in  the entity list, since it  has already been
entered as a vendor. 1C:Enterprise combines the information from two control
accounts for one entity automatically. In  the same way, you can combine data from
any accounts recording operations that a  specific entity is  a part of.
Multi-level analysis. Multi-level analysis allows you to obtain accounting totals
with different levels of detail. If you use Extra Dimensions to keep analytical
accounting, then to perform a  multi-level analysis, appoint a  chart of characteristic
types as the Extra Dimensions types (see page 1-309). Using Charts of character-
istic types objects allows you to keep records with the necessary degree of detail.
Using the characteristic value type limits the number of nesting levels (for example,
as a  value type, any hierarchical catalog can be used and using a  composite type
is  also allowed).
In conducting analytical accounting using subaccounts, multi-level analytical
accounting is  implemented by using subaccounts of different levels.

11.4. TYPES OF ACCOUNTING

As has already been noted, 1C:Enterprise allows you to use an unlimited number
of accounting types. Typical examples of accounting types are quantitative and
foreign currency accounting.
Using the Designer, an unlimited number of different accounting types can be set
up. Accounting types are defined by subordinate Accounting flag objects of the
Chart of accounts object.

11.5. ACCOUNTING REGISTER RECORDS AND RECORD SETS

The main concept in  accounting is  a business transaction. A transaction is  any
business action capable of causing a  change in  the state of the enterprise’s assets.
1C:Enterprise uses documents to enter data on business transactions. A document
enables you to enter data on a  business transaction into the system and record the
transaction date and time as well as its amount and content.
Accounting data on a transaction are automatically generated on the basis of
the document (a Document data object) and recorded in accounting registers.
The generation procedure is defined in the Designer using the 1C:Enterprise
1-656 1C:Enterprise 8.3. Developer Guide

script tools. When transaction data are entered, you can describe how transaction
attributes are to be filled with various data from the document that generates the
transaction.
In the 1C:Enterprise system, the accounting of a business transaction is always
linked to its parent document: if the document must be edited, the transaction data
are regenerated when the document is  posted; if the document is  deleted, the busi-
ness transaction data are deleted as well.
In general, each business transaction consists of an arbitrary number of postings.
In  the 1C:Enterprise system, each accounting posting corresponds to an accounting
register record and a  set of accounting register records is  analogous to a  business
transaction. For a  description of the posting procedure see page 1-660.

11.6. CONSOLIDATED ACCOUNTING

According to the existing legislation, entities that have departments, including
those with a separate balance (affiliated branches, subsidiaries), must maintain
accounting for the activities of all of their departments. For these entities, the ability
to account for all of their departments in  a single infobase and to obtain a  consoli-
dated report is very important. In composing accounting reports, it is also
advisable to provide separate reports on the departments' main business operations
to avoid unnecessary questions from the tax authorities.
The 1C:Enterprise accounting tools allow you to keep accounting records for
several enterprises (or departments of one enterprise) in  the same infobase simul-
taneously. The completion of this task consists of creating accounting register
dimensions containing references to a  department.
The information entered in  these dimensions while operating 1C:Enterprise is  used
as a flag indicating separate totals. 1C:Enterprise automatically sets up a totals
storage system, dividing them according to the value of the dimension. Using the
1C:Enterprise script, you can derive information from the totals for a particular
company or for all companies.

11.7. CREATION OF CHART OF ACCOUNTS

To manage charts of accounts, 1C:Enterprise uses the Chart of accounts configura-
tion objects. Data objects of this kind are accounts (accounting registers) used for
grouping the assets in  1C:Enterprise. The  Designer allows you to create virtually
an unlimited number of charts of accounts. All charts of accounts created in  the
Designer can be used simultaneously.
As described earlier, charts of accounts in  1C:Enterprise support the "account –
subaccounts" multilevel hierarchy.
Chapter 11. Accounting 1-657

11.7.1. Chart Of Accounts Properties

Use the editing window (see page 1-59) or the properties palette to edit the Chart
of accounts object properties and create subordinate objects. This  section contains
a  description of properties specific to the Chart of accounts configuration object.
Code mask – is  used to describe an account and subaccount code structure. A mask
string can include the following special characters:
„„ ! – transforms any entered character to upper case.
„„ 9 – allows to enter any numeric character.
„„ # – allows to enter an arbitrary numeric character, – (minus sign), + (plus sign)
or a  space character.
„„ N – allows to enter any alphanumeric characters.
„„ U – allows to enter any alphanumeric characters which are automatically
converted to uppercase.
„„ X – can be used to enter an arbitrary character.
„„ @ – allows to enter any uppercase alphanumeric character or a  space character.
„„ ^ – this character may not be entered by the user interactively, it  can only be set
from the 1C:Enterprise script.
„„ h – can be used to enter characters denoting hexadecimal numbers.
Any special character to be used in  the mask must be preceded by \.
If the code mask contains periods or does not contain commas, all periods are auto-
matically replaced by commas when the account code is  entered.
Autoorder by code – if this property is  defined, then ordering by the Order field
is  implemented instead of ordering by account code.
Order length – if the length is  greater than zero, the Order field is  used by default
to order the chart of accounts.
NOTE
The maximum length of such attributes as Code length, Description length and Order
length is  628.

Attributes – various descriptions of an account or subaccount are indicated; for

example, the name for account 10 is  Materials.
Accounting flags – the list of accounting types is defined. Typical examples of
accounting types are foreign currency and quantitative accounting. Configuration
developers can create as many types of accounting as they need to complete their
specific task.
Tabular sections – tabular sections are not used with standard charts of accounts.
Setting up simultaneous data accounting in  different charts of accounts to provide
a  detailed account corresponding to multiple charts of accounts is  a good example
of using the Tabular Sections subordinate objects.
1-658 1C:Enterprise 8.3. Developer Guide

Maximum number of extra dimensions – defines the maximum count of Extra

Dimensions (up to 50) used to set up analytical accounting.
Extra dimension types – the Chart of characteristic types object is  indicated (see
page 1-309).
Extra dimension accounting flags – the list of Extra Dimensions accounting flags
is  created. In  setting up analytical accounting for the accounts, these flags allow
you to define the use of an Extra Dimension when forming predefined accounts.

11.7.2. Setting up Various Accounting Types

Any number of accounting types can be defined for each chart of accounts.
When creating an account or subaccount, you must indicate a  use flag for each
type of accounting defined for this account.

11.7.3. Generation of Account List (Predefined Accounts)

Accounts are created as data objects in  the Designer.
To create a  list of predefined accounts in  the Chart of accounts object's proper-
ties palette in  the Predefined property, click the Open link. The  list of accounts
window appears.

Fig. 268.  Chart of Accounts

The list of accounts is  managed using the Actions menu commands.
The account data are formed in  the account editing window (see fig. 269).
The Type attribute specifies the type of account: Active, Passive or Active/Passive.
For off-balance accounts, check the Off-balance check box. The totals for off-
balance accounts are discarded when totaling the balance.
The Order field is  designed for custom accounts ordering. The  length of the field
is defined in the Order length property. If the length of the field is  greater than
zero, this field is used by default to order the chart of accounts. If the chart of
accounts has the Autoorder by code property set, then ordering by the Order field
Chapter 11. Accounting 1-659

is  used instead of ordering by account code or description. The  GetCodeOrder()

method that creates an account order string for the account code mask is  used to
fill the Order field by account code.

Fig. 269.  Predefined Account Editing

The first list contains the accounting flags defined for the Chart of accounts object.
Select the check box in  the Accounted column to indicate that the edited account
belongs to a  certain accounting type.
For each entry in  the lower list, the following parameters are defined. In  the Extra
dimension type column, one of the predefined characteristic types is  selected. If
this chart of accounts has subordinate objects defined in the Extra dimension
accounting flags branch, the list is appended with columns according to the
number of these objects. You should check each Extra Dimension type if analytical
accounting is  required for this Extra Dimension type.
In the 1C:Enterprise mode, the end user can add custom accounts and subaccounts
in the charts of accounts, as well as edit account properties, but he/she cannot
delete accounts and subaccounts created in the Designer. In the 1C:Enterprise
mode, the following attributes only can be modified for the accounts created in  the
Designer:
„„ Account parent
„„ Account code
„„ Account description
„„ Order
1-660 1C:Enterprise 8.3. Developer Guide

11.8. ACCOUNTING REGISTERS

To show accounting information for business transactions, 1C:Enterprise uses the
accounting registers described in  the Accounting registers branch of the configura-
tion tree.

11.8.1. Accounting Register Properties

In its appearance, the accounting register resembles an accumulation register.
Editing an accounting register means developing its structure: sets of dimensions,
resources and register attributes; screen and print forms to view the register records
are also created, if necessary (see page 1-59).
The main feature of the accounting register is  that it  is  connected to the chart of
accounts and supports the double-entry system. Every accounting register record
always contains the required attributes Account Dr (debit account) and Account Cr
(credit account) for the registers supporting correspondence and the Account
attribute for those that do not support correspondence.
The Enable totals splitting property enables the totals splitting mechanism that
ensures a greater concurrency of writing to the register (for a description of
a  similar property for accumulation registers see page 1-326).
NOTE
Such values as UUID, BinaryData, and any unlimited length string cannot serve
as the type of accounting register dimensions.

11.8.2. Accounting Register Records

For a  business transaction entered by a  document to cause changes in  the totals,
the document must generate accounting register records.
The records from a  particular document represent a  group (through the recorder
document) that always "holds" together when any changes are made to the docu-
ment attributes or records. The  order of record creation is  also defined using the
1C:Enterprise script.
The structure of a record is built by 1C:Enterprise dynamically depending on
the configuration of various accounting items during the editing of the chart of
accounts. For example, a record may contain attributes for entering the corre-
sponding accounts, amounts, analytical accounting objects, quantities, currency
types and amounts in  foreign currency.
Besides these attributes, you can create additional attributes for the record in  the
Designer, containing any other necessary information. For example, it  can be an
attribute for storing comments in  the record.
Chapter 11. Accounting 1-661

In operating 1C:Enterprise, the user can disable records and then re-enable them.
Disabled entries do not affect the account balance or turnovers. Records are enabled
and disabled using the Active property.
This feature is  useful in  accounting for planned business transaction, i.e. those that
will occur in  the future. Disabling records for such a  transaction, you can keep the
real totals unchanged. When these transactions take place, it  is  sufficient to simply
re-enable them.
When entering records, 1C:Enterprise performs various predefined operations,
making the user's work with the system faster and easier. For example, if analytical
accounting is set for a corresponding account, the system automatically opens
the list of analytical accounting objects (Extra Dimensions), so that the user can
select the required object. Many aspects of 1C:Enterprise behavior can be set up by
editing accounting register record properties.
1-662 1C:Enterprise 8.3. Developer Guide
Chapter  12

PERIODICAL CALCULATIONS

Periodical calculations are calculations made with a  certain frequency; they are
closely bound one to another based on a number of rules and affect each other
within a  period.
The mechanisms of periodical calculations allow you to set up their order and
correlation and organize the recording of their results.
Calculation of salary that computes accruals and withholdings is  a typical example
of a  periodical calculation. Calculations are usually performed on a  monthly basis
and the results of one calculation can depend on the results and availability of other
calculations.
The Charts Of calculation types and Calculation registers configuration objects are
used for calculations in  1C:Enterprise. Since these objects are closely connected,
this chapter outlines the features they provide.
The subsequent sections discuss the issues of configuring the mentioned objects.

12.1. MAJOR CONCEPTS

Period. The  concept of period is  important for calculations. Typically, a  period
is  described by the date it  begins and the date it  ends. If periodicity is  defined
for a calculation, describe the period of calculation validity or registration by
indicating any date. This  date is  used to identify the period's start date which also
describes this period. Defining a period in this fashion optimizes execution of
queries that select records within the specified period.
Calculation periodicity. It defines the period over which calculations recorded
in  a particular register are (can) be performed. It  is  specified in  the calculation
register's Periodicity property. The  value of this property determines the period
of register record validity (if the register is  periodical). For example, if the register
periodicity is  Month, the document date (e.g., November 2008) is  selected as the
1-664 1C:Enterprise 8.3. Developer Guide

action period for record generation and this date is  used by the system to assign
11/01/2008 as the action period's start date.
Registration period is  the start date of the period indicated when registering the
calculation (it is defined on the basis of the recorder document date). Assume
salary for May 2008 is  calculated in  June 2008 (calculation periodicity: Month).
May 2008 is  the action period (the date 05/01/2008 is  entered in  the database),
while June 2008 is  the registration period (the date 06/01/2008 is  entered in  the
database).
Action period is the period's start date determined based on the value of the
Periodicity property. Assume the document points out that calculation
is  performed for May 2008. The  action period for the Periodicity property of
the Month register is  defined by the date 05/01/2008; for the Quarter register –
by 04/01/2008.
Calculation action period indicates the period over which the calculation is  made.
The  period is  defined by its beginning and end dates. Assume a  sick-list record
for May 2008 has an action period of 05/01/2008; in this case the calculation
action period is  defined by the beginning date (e.g., 05/06/2008) and the end date
(e.g., 05/15/2008).
Displacement mechanism or action period competition is discovering the
connections between calculation types during the calculation action period. Compe-
tition results from inability to run multiple calculations at a  time. You need to select
the calculation to be performed in  this period. The  displacement mechanism is  set
up in  the description of a  specific calculation type. You can adjust these settings
in the Displacing section (for calculation types). For example, Salary Payments
and Sick Leave Payments cannot be applied at the same time. This  means that the
sick leave payment displaces the salary payments. In  other words, when the sick
leave is  active, the salary is  not calculated. For a  description of the displacement
mechanism see page 1-668.
Actual action period – if a  calculation is  not displaced by other calculations, the
actual action period is  equal to the action period. If there are displacing calcula-
tion types, the actual action period is  defined as a  combination of non-overlapping
periods during which this calculation is not displaced. fig. 270 below shows
a  graphical representation of an actual action period when the Salary calculation
is  displaced by the Sick Leave calculation.
The actual action period represents secondary data, i.e. the result of system calcula-
tions. The  actual action period is  recalculated with the entry of any set, including
an empty one (posting undone).
IMPORTANT!
Calculation results do not depend on the data entry (registration) sequence.
Basic period defines the period where (basic) calculation results used for the
current calculation are selected. For example, when the premium pay for May
2008 is  accrued, the results of the accruals performed by certain calculation types
Chapter 12. Periodical Calculations 1-665

over a  certain period (e.g., Salary, Additional Pay, Vacation Pay) are taken
into account. This  is  the basic period for the premium pay calculation. The  link
between calculation types by basic period is  set up in  the description of a  specific
calculation type in  the Base section (calculation types).

Fig. 270.  Displacement Mechanism

12.2. CHARTS OF CALCULATION TYPES

These configuration objects are designed to create calculation types used in  calcu-
lation registers.
A reference to a  calculation type is  one of the main properties of the calculation
register records, rendering different and diverse calculation register entries.
Use the editing window (see page 1-59) or the properties palette to edit the Chart
of calculation types object properties and create subordinate objects. The  unique
properties of charts of calculation types are discussed below in  addition to their
general properties.

12.2.1. Calculation Property Category

Dependence on base calculation type – if the Dependence on base calculation typr
property value is  not Does not depend, then the list of basic calculation types can
be specified for a chart of calculation types. The list of basic calculation types
is  defined by the Base charts of calculation types property.
Base charts of calculation types  – specifies a  list of calculation types that can be
included in  the list of basic calculation types. The  list of basic calculation types
is  used by the calculation register in  the base retrieval mechanism.
Uses action period – if this property is  set, the current chart of calculation types
can be assigned to a  calculation register with an action period. Moreover, a  list
of displacing calculation types can be specified for each calculation type. The  list
1-666 1C:Enterprise 8.3. Developer Guide

of displacing calculation types determines how the displacement mechanism works

for a  particular calculation register (see page 1-668).
The properties specified in  this category define what attributes are included in  the
list when calculation type forms are created. If the Dependence on base calculation
type property is  set to Depends by action period (Depends by registration period),
you can place a  table box for basic calculation type selection in  the form. If the
Uses action period property is set, a table box for displacing calculation type
selection can be placed in  the form.

12.2.2. Predefined Calculation Types

Plans of calculation types have a special feature: predefined calculation
types created at the configuration stage. The user cannot delete them in the
1C:Enterprise mode.
To edit the list of predefined calculation types, go to the properties palette, open
the Other tab and click Predefined. The  list of predefined calculation types for this
chart of calculation types appears (for an example, see fig. 271).

Fig. 271.  Predefined Charts of Calculation Types

The list of predefined calculation types can be edited using the Actions menu items.
Attributes (basic and leading) of predefined calculation types depend on the proper-
ties set for this chart of calculation types object in  the Calculation category.
Each predefined calculation type is  edited in  the modal window. The  main prop-
erties of a  calculation type are set in  the Main tab.

Fig. 272.  Editing Chart of Calculation Types

Chapter 12. Periodical Calculations 1-667

If the Dependence on base calculation type property is  set to Depends by action
period (Depends by registration period), the form contains the Base tab. This  tab
lists the calculation types that are basic for the current calculation type and define
how the base retrieval mechanism works for a  particular calculation register (see
fig. 273).
Thus, in  the example below (see fig. 273), Salary and Additional pay calculation
types are basic for the Sick leave calculation type.

Fig. 273.  Basic Accruals for Calculation Type

If the Uses action period property is set, the form contains the Displacing tab.
It  lists the calculation types displacing the current calculation type over the action
period and thus defining how the displacement mechanism works for a  particular
calculation register.

Fig. 274.  Displacing Calculation Types

A displacing calculation type should be selected from the listed calculation types
(see fig. 274). In  the example above, no displacing calculation types exist the Sick
leave calculation type. However, when describing the Salary calculation, select
Sick leave.
The Leading tab lists the calculation types defining how the recalculation
mechanism work for a  particular calculation register (i.e., the register this list of
calculation types is  assigned to).
1-668 1C:Enterprise 8.3. Developer Guide

Fig. 275.  Leading Calculation Types

In the 1C:Enterprise mode, the user can create custom calculation types in  addi-
tion to the predefined types and set the necessary properties for them. To do so,
a  form is  created in  the Designer in  which the table boxes for basic, leading and
displaced calculation types, depending on the properties set for this list of calcula-
tion types, should be placed.

12.3. CALCULATION REGISTERS

12.3.1. General Information on Calculation Registers
A calculation register is a configuration object that ensures recording of
computation results performed by calculations from the chart of calculation types.
For example, calculation registers enable accruals for individuals (salary, sick pay,
vacation pay and so on).
Calculation register entries can affect the status of other register entries. There are
two types of mutual impact exhibited by accounting records in the calculation
register: competition for the action period and interdependence in  the base period.
Let us illustrate these mutual impacts.

12.3.1.1. Displacement Mechanism

Action period competition can be illustrated by salary and vacation pay accruals
for an individual. The  same period of time cannot cover both a  salary entry and
a  vacation pay entry, i.e. the periods of time for which these accruals are made
cannot intersect. This kind of entry (register record) behavior is implemented
in  the calculation register using the concept of register record action period. Every
calculation register record has an actual action period usually determined by a  set
of multiple periods of time.
Thus, if a vacation pay entry is valid from 03/03/2008 to 03/13/2008, a salary
accrual entry can, for example, have the actual action period consisting of two
intervals: from 03/01/2008 to 03/02/2008 and from 03/14/2008 to 03/20/2008.
Action period competition is supported by the calculation register displacement
mechanism, whose operation is defined by the displacing calculations, action
period dates, etc.
Chapter 12. Periodical Calculations 1-669

12.3.1.2. Recalculation Mechanism

The base action period dependency for entries can be illustrated by salary accruals
and salary-dependent average earnings for an individual. If the status of salary
entries in  the register changes for a  period (entries are deleted, modified or added),
the results for average earnings entries are also adjusted if they exist in  the period.
To implement this kind of mutual impact of calculation register entries, the concept
of calculation register base period is  introduced. Thus, if the average earnings entry
has a  base period between 01/01/2008 and 03/31/2008 (i.e. it  uses the three-month
average earnings), then any change in  the salary entries for the same period cause
the average earnings entry to be modified.

12.3.2. Editing Calculation Register

The Calculation registers configuration tree branch is  designed to manage calcula-
tion registers.
Editing a  calculation register includes specifying a  list of calculation types, action
period and base period support and periodicity; developing the register structure
(sets of dimensions, resources and attributes); creating screen forms and print forms
for viewing register records (if necessary).
NOTE
Such values as UUID, BinaryData, and any unlimited length string cannot serve
as the type of accounting register dimensions.
The unique calculation register properties are discussed in  this section in  addition
to general object properties.
Use the editing window to edit properties of Calculation register objects and create
subordinate objects (see page 1-59).
Chart of calculation types is  the main characteristic of a  register. For details see
page 1-665. Only one chart of calculation types can be specified for a  calculation
register.
Action period – setting this property creates a  mutual competitive impact of register
records. Salary accrual and sick pay are a  good example of competitive records –
you cannot be sick and work at the same time, i.e. get both the salary and sick pay.
These calculations are mutually exclusive for each point in  time and the system
must guarantee that entering one of them excludes the other.
An action period based on the calculation register limits the number of records with
similar dimension values, registration periods, and calculation types.
When an actual action period is evaluated (which is performed for each entry
of the register record set), a  memory shortage error may occur if a  large number
of similar entries are used in  calculation. What this means in  real terms is  that
the number of records active during one and the same time period is limited.
1-670 1C:Enterprise 8.3. Developer Guide

For instance, one and the same employee could have been issued a salary for
a  single period multiple times.
The limitation value depends on a  number of conditions (the database engine used,
computer technical parameters, etc.), but under no circumstances does this limita-
tion impact real practice.
Schedule – this property is available if the Action period property is set.
This  property provides a  link to the information register where a  time schema for
the source data of this calculation is  described. A schedule should be specified for
the calculations, depending on the source data distributed within the action period,
according to a certain rule. For example, it can be an organizational timesheet
broken down into days, a  lecture schedule in  hours, etc.
Schedule value – this property is available if the Action period property is set.
This property is used to select a resource of the information register defined
in the Schedule property.
For example, the OrganizationWorkSchedule information register can be
specified as a  schedule. This  register has the attributes WorkDay (Boolean type)
and WorkHours (Number type). The  former shows whether the current date is  a
workday; the latter specifies the number of work hours. Selecting WorkDay means
that the calculation analyzes whether a certain day of the period is a work day
(i.e., whether or not salary should be calculated for this day). Selecting WorkHours
means that the specified calculation is  performed on the basis of the number of
working hours. The  allocation itself is  set in  the 1C:Enterprise mode (manually or
using the 1C:Enterprise script).
Schedule date – this property is available if the Action period property is set.
This  property specifies a  Date-type dimension of the information register defined
in the Schedule property. Depending on the property value, binding to values of the
information register resource selected in  the Schedule value property is  created.
Base period – setting this property creates a  mutual coherent impact of the register
records. The dependency of pay calculated by averages on the pay calculated
in  the base period is  a good example of coherent register records.
Periodicity defines the period in  which records are registered and can affect each
other (for registers supporting an action period).
Recalculations are subordinate register objects that define the rules of register
records' mutual impact. The register's Dimension property in the Link group of
the object property palette indicates the main dimension of the current register that
is  to be recalculated in  case of changes of the leading register data defined in  the
leading registers' Data property. For example, an individual's withholdings are
recalculated if accruals (salary, premium pay) change.
If the Base period property is set, recalculation data are created automatically.
If the property is not set the user must create the recalculation data manually
(a special form to enter recalculations and their mechanism should be developed at
the design stage).
 1С:ENTERPRISE 8.3
Developer Guide

Part 2

Developer Guide
Part 2

Moscow
1C Company
2013
 ENTIRE COPYRIGHT TO SOFTWARE
AND DOCUMENTATION BELONGS TO 1C Company
By purchasing 1С:Enterprise software system
you hereby agree to protect rights of 1C Company
and refrain from making copies of the software
and documentation without prior written permission from 1C Company.

© 1C, LLC, 1996–2013

1C Company, Moscow, 123056, P.O. 64
Sales Department: 21, Seleznevskaya st.,
Phone: +7 (495) 737-92-57,
Fax: +7 (495) 681-44-07,
E-mail: [email protected]
URL: www.1c-dn.com
Software development group: A. Alekseev, A. Bezborodov, D. Beskorovainov, P. Vasilets,
A. Vinogradov, A. Volkov, I. Golshtein, E. Gornostayev, G. Damie, A. Darovskikh, O. Derut,
N. Evgrafov, B. Evtifeev, D. Zaretsky, D. Ivashov, S. Kopienko, N. Korsakov, S. Kravtchenko,
V. Kudryavtsev, P. Kukushkin, A. Lakutin, M. Leybovitch, G. Leontyev, A. Lekhan,
A. Makeev, A. Medvedev, E. Mitroshkin, S. Murzin, S. Nuraliev, L. Onuchin, M. Otstavnov,
D. Pavlenko, A. Plyakin, A. Rukin, D. Rusanov, E. Silin, D. Sluzhbin, A. Smirnov, V. Sokolov,
P. Solodky, V. Sosnovsky, D. Sysoenkov, A. Toporkov, V. Tunegov, A. Trubkin, V. Philippov,
A. Tsylyabin, V. Cheremisinov, P. Chikov, A. Chicherin, A. Shevtchenko, A. Scherbinin.
Documentation: V. Baidakov, V. Dranishchev, E. Korolkova, A. Krayushkin, I. Kuznetsov, M. Lavrov,
A. Monichev, A. Plyakin, M. Radchenko.
Technical support group: O. Bagrova, M. Belokon, E. Garifullina, V. Davydova, O. Dmitrenko,
A. Evdokimova, L. Ermakova, Yu. Zhestkov, S. Zholudev, M. Zholudeva, O. Zavalskaya,
N. Zayavlina, G. Korobka, Yu. Lavrova, S. Lepeshkina, S. Mazurin, S. Markov, A. Markova,
Yu. Misan, V. Nikolaeva, A. Pavlikov, I. Panin, O. Pekhtereva, S. Postnova, A. Prokurovsky,
G. Stepanenko, N. Stepanov, V. Tantasheva, T. Tokareva, G. Yastrebova.
QA group: A. Galochkin, B. Ziatdinov, A. Lapin, E. Medvedev, S. Potapov, N. Shargunova.

Book Title: 1C:Enterprise 8.3. Developer Guide. Part 2

Publication Number: 83.102.02
Publication Date:
 TECHNICAL SUPPORT LINE
Registered users can receive technical support from 1C Company or authorized
1C partners.
To complete your registration, fill out the registration form and mail it to the
1C partner through which you have purchased the product. The address is printed
on the registration form.
Refer to the software registration card for the telephone number and e-mail
address of the technical support service.
When you dial the hot line, ensure that you are not far from your computer and
you have this guide and your registration card with you. Be prepared to provide
the support representative with the brand and technical specifications of your
computer and printer.
When you dial the hot line, you will be connected with a technical specialist.
Be ready to provide the name of your company, your software version number
(it can be found on the software distribution CD and on your registration card) and
other registration information. The information that you provide will be verified
against the registration form that you sent out.
The technical support specialist might attempt to reproduce your situation on their
computer. They might provide the solution immediately or consult software devel-
opers. The log of all support calls is maintained, so when calling about a previous
issue you can refer to the date and time of your previous call.

WE ARE ALWAYS HERE TO HELP YOU!

2-674 1C:Enterprise 8.3. Developer Guide
 CONTENTS

PART 1
Introduction.................................................................................................................................1-21
Structure of the Guide............................................................................................................1-21
What You Need To Know......................................................................................................1-23
The Books Included in  the Documentation...........................................................................1-23
Training Materials and Additional Opportunities...........................................................1-24
Text Files Included in  the 1C:Enterprise 8.3 Distribution Kit.......................................1-24
About 1C:Enterprise 8 Page...................................................................................................1-24
1C:Developer Network..........................................................................................................1-24
Agreed Notation.....................................................................................................................1-25
Chapter 1. Concept of the System.............................................................................................1-27
1.1. Configurability................................................................................................................1-27
1.2. Functioning of the System..............................................................................................1-27
1.3. Basic Concepts of the System.........................................................................................1-28
1.3.1. Configuration Concept..........................................................................................1-29
1.3.2. Configuration Object............................................................................................1-30
1.3.3. Command Interface...............................................................................................1-39
1.3.4. Form......................................................................................................................1-40
1.3.5. Module..................................................................................................................1-40
1.3.6. Template...............................................................................................................1-41
1.4. Operation Modes.............................................................................................................1-42
1.4.1. File Mode .............................................................................................................1-42
1.4.2. Client/Server Mode...............................................................................................1-42
1.5. Development Tools.........................................................................................................1-43
Chapter 2. Work with Configuration.......................................................................................1-47
2.1. Opening Configuration....................................................................................................1-47
2.2. Saving Configuration......................................................................................................1-48
2.3. Closing Configuration.....................................................................................................1-48
2.4. Saving Configuration to File...........................................................................................1-49
2.5. Loading Configuration from File....................................................................................1-49
2.6. Configuration Object Tree..............................................................................................1-49
2-676 1C:Enterprise 8.3. Developer Guide

2.7. Metadata Tree Sort Settings............................................................................................1-50

2.8. Creation and Deletion of Configuration Objects.............................................................1-50
2.8.1. Create Configuration Objects...............................................................................1-50
2.8.2. Deletion of Configuration Objects........................................................................1-52
2.8.3. References to Configuration Objects....................................................................1-52
2.9. Properties Palette.............................................................................................................1-53
2.10. More Window...............................................................................................................1-56
2.11. Object Editing Window.................................................................................................1-59
2.12. Create Help Content Section.........................................................................................1-63
2.13. Work with Database Configuration...............................................................................1-63
2.13.1. Database Configuration Object Tree..................................................................1-63
2.13.2. Update of Database Configuration.....................................................................1-64
2.13.3. Background Database Configuration Update.....................................................1-67
2.13.4. Saving Database Configuration to File...............................................................1-71
2.13.5. Comparison of Configuration and Database Configuration...............................1-72
2.13.6. Cancellation of Configuration Changes..............................................................1-72
2.14. 1C:Enterprise Launch....................................................................................................1-72
2.15. Download/Upload of Configuration Files.....................................................................1-72
2.16. Configuration Dump and Restoration...........................................................................1-74
2.17. Working with a  mobile application..............................................................................1-76
2.18. Configuration Report.....................................................................................................1-76
2.19. Global Search and Replacement...................................................................................1-77
2.20. Customization of Designer Work Space.......................................................................1-80
2.20.1. Panel Customization...........................................................................................1-81
2.20.2. Configuration Window.......................................................................................1-81
2.20.3. Use of Window Display Modes..........................................................................1-81
Chapter 3. Application Interface...............................................................................................1-83
3.1. Open Forms in  Separate Windows.................................................................................1-84
3.1.1. Main Application Window...................................................................................1-84
3.1.2. Auxiliary Window................................................................................................1-88
3.2. Open Forms in  Tabs.......................................................................................................1-90
3.2.1. The Main Application Window............................................................................1-90
3.2.2. The Auxiliary Window.........................................................................................1-98
3.3. Taxi Interface..................................................................................................................1-98
3.3.1. Main application window.....................................................................................1-98
3.3.2. The auxiliary window.........................................................................................1-110
Chapter 4. 1C:Enterprise Script.............................................................................................1-113
4.1. Brief Description and Purpose of 1C:Enterprise Script................................................1-113
4.2. Source Text Format in  Program Modules....................................................................1-114
4.2.1. What is  a Program Module?..............................................................................1-114
4.2.2. Program Module Execution Context..................................................................1-114
4.2.3. Types of Program Modules................................................................................1-115
4.2.4. Program Module Format.....................................................................................1-119
4.2.5. Special Characters Used in  Source Text............................................................1-121
4.3. Primitive Data Types.....................................................................................................1-122
4.4. Assignment Operator.....................................................................................................1-126
4.5. Script Expressions.........................................................................................................1-126
4.5.1. Arithmetic Operations.........................................................................................1-126
Contents 2-677

4.5.2. Concatenation Operation....................................................................................1-127

4.5.3. Logical Operations..............................................................................................1-127
4.6. Operators and Syntactic Constructs..............................................................................1-128
4.7. Major Techniques and Practices...................................................................................1-146
4.7.1. Calls to Object Properties...................................................................................1-146
4.7.2. Enhancement of Object and Form Context.........................................................1-147
4.7.3. Passing Procedure and Function Parameters......................................................1-148
4.7.4. Work with Collections of Values........................................................................1-154
4.7.5. Use of Numbers and Indices...............................................................................1-154
4.7.6. Work with System Enumerations.......................................................................1-154
4.7.7. Work with Predefined Values.............................................................................1-154
4.8. System Startup Versions...............................................................................................1-156
4.8.1. Execution of Procedures and Functions..............................................................1-157
4.8.2. Use of Objects, Their Properties and Methods...................................................1-163
Chapter 5. Configuration Objects...........................................................................................1-165
5.1. Configuration Properties...............................................................................................1-165
5.1.1. General Property Category.................................................................................1-165
5.1.2. Presentation Property Category..........................................................................1-167
5.1.3. Development Property Category........................................................................1-169
5.1.4. Help Content Property Category.........................................................................1-169
5.1.5. Compatibility Property Category........................................................................1-169
5.2. Managed Application Module.......................................................................................1-171
5.3. External Connection Module........................................................................................1-172
5.4. Session Module.............................................................................................................1-172
5.5. Common Configuration Branch....................................................................................1-172
5.5.1. Subsystems.........................................................................................................1-173
5.5.2. Common Modules..............................................................................................1-174
5.5.3. Session Parameters.............................................................................................1-179
5.5.4. Roles and Access Rights.....................................................................................1-180
5.5.5. Common Attributes............................................................................................1-204
5.5.6. Exchange Plans...................................................................................................1-207
5.5.7. Filter....................................................................................................................1-208
5.5.8. Event Subscription..............................................................................................1-209
5.5.9. Scheduled Jobs....................................................................................................1-210
5.5.10. Functional Options and Their Parameters........................................................1-211
5.5.11. Defined types....................................................................................................1-223
5.5.12. Settings Storages...............................................................................................1-223
5.5.13. Common Forms................................................................................................1-229
5.5.14. Common Commands........................................................................................1-230
5.5.15. Command Groups.............................................................................................1-230
5.5.16. Common Templates..........................................................................................1-230
5.5.17. Common Pictures..............................................................................................1-230
5.5.18. XDTO Packages...............................................................................................1-233
5.5.19. Web-services.....................................................................................................1-241
5.5.20. WS-references...................................................................................................1-244
5.5.21. Style Elements..................................................................................................1-246
5.5.22. Languages.........................................................................................................1-247
5.6. Common Properties of Configuration Objects..............................................................1-250
5.6.1. General Properties...............................................................................................1-250
5.6.2. Metadata Object Presentation.............................................................................1-250
2-678 1C:Enterprise 8.3. Developer Guide

5.6.3. Custom Presentation of Data..............................................................................1-251

5.6.4. Standard Attributes.............................................................................................1-253
5.6.5. Predefined data...................................................................................................1-254
5.6.6. Input by String....................................................................................................1-258
5.6.7. Forms..................................................................................................................1-263
5.6.8. Commands..........................................................................................................1-266
5.6.9. Attribute Fill-in Mechanism for New Objects....................................................1-266
5.6.10. Attribute Fill Check..........................................................................................1-268
5.6.11. Indexing Object Attributes................................................................................1-273
5.6.12. Rights................................................................................................................1-273
5.6.13. Quick Choice....................................................................................................1-274
5.6.14. Choice Parameter Links....................................................................................1-274
5.6.15. Choice Parameters............................................................................................1-277
5.6.16. Other.................................................................................................................1-278
5.7. Constants.......................................................................................................................1-279
5.7.1. Properties of a  Constant.....................................................................................1-279
5.8. Catalogs.........................................................................................................................1-280
5.8.1. Catalog Properties...............................................................................................1-281
5.8.2. Properties of Catalog Attributes.........................................................................1-285
5.8.3. Predefined Catalog Items....................................................................................1-285
5.9. Documents.....................................................................................................................1-285
5.9.1. Document Properties...........................................................................................1-286
5.9.2. Document Posting Mechanism...........................................................................1-290
5.9.3. Numerators.........................................................................................................1-293
5.9.4. Document Sequences..........................................................................................1-294
5.9.5. Entering Documents Based on Existing Objects................................................1-298
5.10. Document Journals......................................................................................................1-299
5.10.1. Journal Creation................................................................................................1-299
5.10.2. Journal Editing..................................................................................................1-299
5.10.3. Document Journal Columns.............................................................................1-300
5.11. Enumerations...............................................................................................................1-301
5.12. Reports and Data Processors.......................................................................................1-303
5.12.1. External Reports and Data Processors..............................................................1-304
5.13. Charts of Characteristic Types....................................................................................1-309
5.14. Registers......................................................................................................................1-316
5.14.1. Information Registers.......................................................................................1-317
5.14.2. Accumulation Registers....................................................................................1-323
Chapter 6. Command Interface...............................................................................................1-337
6.1. General Structure of Command Interface.....................................................................1-337
6.1.1. Sections and Subsections of Main Application Window....................................1-337
6.1.2. Types of Commands...........................................................................................1-338
6.1.3. Command Groups...............................................................................................1-342
6.2. Creation of Global Command Interface........................................................................1-343
6.2.1. Subsystems.........................................................................................................1-343
6.2.2. Commands..........................................................................................................1-344
6.2.3. Command Parameterization................................................................................1-345
6.2.4. Creation of Default Command Interface............................................................1-346
6.2.5. Command Interface Property..............................................................................1-347
6.2.6. Editing Sets of Commands.................................................................................1-347
6.2.7. Role-Based Setup of Default Command Visibility.............................................1-348
Contents 2-679

6.3. Service Navigation Features..........................................................................................1-349

6.3.1. Links...................................................................................................................1-349
6.3.2. User Notifications...............................................................................................1-350
6.3.3. Display Status of Lengthy Processes..................................................................1-351
6.3.4. Messages.............................................................................................................1-353
6.3.5. How Keyboard Shortcuts Work..........................................................................1-357
6.4. Command Interface Development Procedure...............................................................1-358
Chapter 7. Forms......................................................................................................................1-361
7.1. Form Attributes.............................................................................................................1-362
7.1.1. Form Data Types................................................................................................1-363
7.1.2. Conversions Between Application Object Data and Form Data........................1-368
7.1.3. Dynamic List......................................................................................................1-369
7.1.4. Attribute Properties.............................................................................................1-377
7.1.5. Form Conditional Appearance............................................................................1-378
7.1.6. Formatted Documents.........................................................................................1-381
7.2. Form Parameters...........................................................................................................1-384
7.2.1. Standard Form Parameters..................................................................................1-385
7.2.2. Form Parameters Handling: Example.................................................................1-386
7.3. Form Commands...........................................................................................................1-388
7.4. Form Module.................................................................................................................1-390
7.5. Form Elements..............................................................................................................1-391
7.5.1. Common Properties of Form Elements..............................................................1-392
7.5.2. Form....................................................................................................................1-396
7.5.3. Field....................................................................................................................1-400
7.5.4. Decoration...........................................................................................................1-402
7.5.5. Table...................................................................................................................1-402
7.5.6. Button.................................................................................................................1-405
7.5.7. Group..................................................................................................................1-405
7.5.8. Special Command Bars.......................................................................................1-407
7.5.9. Form Element Behavior......................................................................................1-408
7.5.10. Rules of Form Elements Placement..................................................................1-408
7.5.11. Form Element Boundaries Alignment..............................................................1-412
7.5.12. Drag-and-Drop Mechanism..............................................................................1-419
7.6. Form Command Interface.............................................................................................1-421
7.7. Different approaches to modality..................................................................................1-421
7.7.1. Overview.............................................................................................................1-421
7.7.2. Using blocking windows....................................................................................1-424
7.7.3. Method mapping.................................................................................................1-425
7.8. Work with Form from 1C:Enteprise Script...................................................................1-426
7.8.1. How to Open a  Form.........................................................................................1-426
7.8.2. Redefining an Opened Form...............................................................................1-427
7.8.3. Modification of Form Elements Properties........................................................1-428
7.8.4. Form Modification..............................................................................................1-429
7.8.5. Working with Dynamic Lists..............................................................................1-433
Chapter 8. Work with Queries................................................................................................1-441
8.1. Query Data Sources (Tables)........................................................................................1-441
8.2. Query Language............................................................................................................1-442
8.2.1. Syntax Diagram for Query Language Constructs...............................................1-442
8.2.2. Comments in  Query Language..........................................................................1-443
2-680 1C:Enterprise 8.3. Developer Guide

8.2.3. Use of Predefined Configuration Data................................................................1-443

8.2.4. Query language keywords..................................................................................1-445
8.2.5. Main Sections of Query Text..............................................................................1-446
8.2.6. Query Description...............................................................................................1-446
8.2.7. Selection Fields Description...............................................................................1-450
8.2.8. Query Sources Description.................................................................................1-453
8.2.9. Query Result Filtration.......................................................................................1-460
8.2.10. Query Result Groups........................................................................................1-461
8.2.11. Conditions for Aggregate Function Values......................................................1-462
8.2.12. Query Union.....................................................................................................1-463
8.2.13. Query Result Ordering......................................................................................1-464
8.2.14. Autoorder Results.............................................................................................1-467
8.2.15. Calculation of Query Totals..............................................................................1-468
8.2.16. Expressions in  the Query Language................................................................1-473
8.2.17. Conditions in  Query Language........................................................................1-488
8.3. Execution and Use of Queries in  the 1C:Enterprise Script..........................................1-496
8.3.1. Major Techniques and Practices.........................................................................1-496
8.3.2. Work with Temporary Tables.............................................................................1-504
8.3.3. Working with Batch Queries..............................................................................1-508
Chapter 9. Work with Data......................................................................................................1-509
9.1. Object Locks.................................................................................................................1-509
9.1.1. Pessimistic Lock.................................................................................................1-509
9.1.2. Pessimistic Lock and Transactions.....................................................................1-511
9.1.3. Optimistic Lock..................................................................................................1-511
9.2. Transactions..................................................................................................................1-511
9.2.1. Explicit Calls to Transactions.............................................................................1-512
9.2.2. Nested Transaction Call......................................................................................1-514
9.2.3. Impact of Transactions on Program Objects.......................................................1-515
9.3. Managed Locks.............................................................................................................1-515
9.3.1. General Information on Locks............................................................................1-515
9.3.2. Managed Locks...................................................................................................1-516
9.3.3. Setting Lock Mode in  Configuration.................................................................1-518
9.3.4. Work with Managed Locks Through 1C:Enterprise Script................................1-518
9.3.5. Automatic and Managed Mode: Features...........................................................1-522
9.3.6. Working with multiple managed locks...............................................................1-523
9.3.7. Configuration Modification When Switching to Managed Lock Mode.............1-524
9.4. Exclusive mode.............................................................................................................1-528
Chapter 10. Data Composition System...................................................................................1-531
10.1. General Information on Data Composition.................................................................1-531
10.2. Common Objects of Data Composition System.........................................................1-535
10.2.1. Use Property.....................................................................................................1-535
10.2.2. Data Composition System Field.......................................................................1-535
10.2.3. Data Composition System Parameters..............................................................1-536
10.3. Data Composition Schema..........................................................................................1-536
10.3.1. Data Composition Schema Components..........................................................1-537
10.3.2. Working with Multiple Data Sets.....................................................................1-542
10.3.3. Query Language Extension for Data Composition System..............................1-544
10.3.4. Data composition system expression language................................................1-547
10.3.5. Data Composition Schema Wizard...................................................................1-589
Contents 2-681

10.3.6. Data Composition Variant Settings..................................................................1-604

10.3.7. User Settings of Data Composition System......................................................1-610
10.4. Data Composition Template........................................................................................1-617
10.4.1. Data Composition Template Sections...............................................................1-617
10.4.2. Appearance Templates......................................................................................1-622
10.4.3. Generator of Template Areas............................................................................1-624
10.5. Data Composition Processor.......................................................................................1-632
10.6. Functional Options and Rights to View Fields in  Reports.........................................1-633
10.7. Data Composition Result............................................................................................1-634
10.7.1. Composition Result Output to Spreadsheet Document....................................1-636
10.7.2. Composition Result Output to Value Table and Value Tree............................1-637
10.8. Calculation of Totals by Balance Fields in  Data Composition System.....................1-638
10.8.1. Calculation of Totals by Balance Fields...........................................................1-638
10.8.2. Calculation of Totals by Accounting Balance Fields.......................................1-639
10.8.3. Template Composition......................................................................................1-640
10.9. Working with Hierarchy in  Data Composition System.............................................1-640
10.9.1. Hierarchical Groups..........................................................................................1-640
10.9.2. Hierarchical Detail Records..............................................................................1-641
10.9.3. Output of a  Single Item in  Multiple Parent Records......................................1-642
10.9.4. IN HIERARCHY Condition.............................................................................1-644
10.10. Use of Data Composition System in  Application Development..............................1-644
10.10.1. Input Parameters.............................................................................................1-647
10.10.2. Use of Metadata Object Properties in  Reports...............................................1-647
10.10.3. Background Report Execution........................................................................1-647
10.11. Specifics of Using of Data Composition System......................................................1-648
Chapter 11. Accounting............................................................................................................1-651
11.1. Overview.....................................................................................................................1-651
11.2. Charts of Accounts......................................................................................................1-652
11.3. Analytical Accounting.................................................................................................1-653
11.4. Types of Accounting...................................................................................................1-655
11.5. Accounting Register Records and Record Sets...........................................................1-655
11.6. Consolidated Accounting............................................................................................1-656
11.7. Creation of Chart of Accounts....................................................................................1-656
11.7.1. Chart Of Accounts Properties...........................................................................1-657
11.7.2. Setting up Various Accounting Types..............................................................1-658
11.7.3. Generation of Account List (Predefined Accounts).........................................1-658
11.8. Accounting Registers..................................................................................................1-660
11.8.1. Accounting Register Properties........................................................................1-660
11.8.2. Accounting Register Records...........................................................................1-660
Chapter 12. Periodical Calculations........................................................................................1-663
12.1. Major Concepts...........................................................................................................1-663
12.2. Charts of Calculation Types........................................................................................1-665
12.2.1. Calculation Property Category..........................................................................1-665
12.2.2. Predefined Calculation Types...........................................................................1-666
12.3. Calculation Registers...................................................................................................1-668
12.3.1. General Information on Calculation Registers.................................................1-668
12.3.2. Editing Calculation Register.............................................................................1-669
2-682 1C:Enterprise 8.3. Developer Guide

PART 2
Chapter 13. Business Processes and Tasks.............................................................................2-691
13.1. Major Concepts...........................................................................................................2-691
13.2. General Information....................................................................................................2-692
13.3. Routing........................................................................................................................2-693
13.4. Addressing System......................................................................................................2-693
13.5. Starting Business Processes........................................................................................2-696
13.6. Task Performance........................................................................................................2-697
13.7. Splitting and Joining...................................................................................................2-697
13.8. Manual Control...........................................................................................................2-698
13.8.1. Business Process Completion Attribute............................................................2-698
13.8.2. Task Performance Attribute..............................................................................2-698
13.8.3. Task Removal...................................................................................................2-699
13.8.4. Task Addition...................................................................................................2-699
13.9. Conditional Jump........................................................................................................2-699
13.10. Switch........................................................................................................................2-700
13.11. Task Generation........................................................................................................2-700
13.12. Performance Check...................................................................................................2-702
13.13. Nested Process Execution.........................................................................................2-703
13.14. Business Process Completion...................................................................................2-704
13.15. Standard Business Process and Task Attributes........................................................2-704
13.16. Business Processes with Several Starting Points......................................................2-705
13.17. Feedback....................................................................................................................2-705
13.18. Flowchart...................................................................................................................2-707
13.19. Business Process Editing...........................................................................................2-707
13.20. Task Editing..............................................................................................................2-708
Chapter 14. Data Analysis and Forecasting...........................................................................2-711
14.1. Overview.....................................................................................................................2-712
14.1.1. Main Mechanism Objects.................................................................................2-713
14.1.2. Types of Data Analysis.....................................................................................2-714
14.1.3. Forecasting Models...........................................................................................2-716
14.2. The Summary Statistics Analysis Type......................................................................2-716
14.3. The Association Rules Analysis Type........................................................................2-720
14.3.1. Rules Prune Types............................................................................................2-724
14.4. The Sequential Patterns Analysis Type.......................................................................2-725
14.5. The Decision Tree Analysis Type...............................................................................2-729
14.6. The Сlusterization Analysis Type...............................................................................2-734
14.6.1. Metrics used......................................................................................................2-739
14.6.2. Clusterization methods.....................................................................................2-741
Chapter 15. Data Exchange Mechanisms...............................................................................2-745
15.1. Goals and Objectives...................................................................................................2-745
15.1.1. Universal Data Exchange Mechanisms............................................................2-745
15.1.2. Distributed Infobases........................................................................................2-746
15.2. Universal Data Exchange Mechanisms.......................................................................2-746
15.2.1. XML Documents Read and Write Tools..........................................................2-746
15.2.2. XML Serialization............................................................................................2-746
15.2.3. Exchange Plans.................................................................................................2-759
Contents 2-683

15.3. Distributed Infobases...................................................................................................2-772

15.3.1. General Principles.............................................................................................2-772
15.3.2. Exchange Plans.................................................................................................2-773
15.3.3. Working with Distributed Infobase..................................................................2-778
15.3.4. Data Exchange Scenarios in  Distributed Infobase...........................................2-784
Chapter 16. XDTO Mechanism...............................................................................................2-789
16.1. XDTO Factory.............................................................................................................2-790
16.1.1. XDTO Factory Retrieval from XSD Schema File............................................2-792
16.2. XDTO Data Types......................................................................................................2-793
16.2.1. XDTO Value Type............................................................................................2-793
16.2.2. XDTO Object Type..........................................................................................2-795
16.2.3. XDTO Property................................................................................................2-796
16.3. XDTO Data Instances.................................................................................................2-798
16.3.1. XDTO Value.....................................................................................................2-798
16.3.2. XDTO Object....................................................................................................2-799
16.3.3. XDTO Sequence...............................................................................................2-801
16.3.4. XDTO List........................................................................................................2-802
16.3.5. XРath................................................................................................................2-803
16.4. XDTO-Based XML Serialization................................................................................2-805
16.5. XML Schema Layout Recommendations...................................................................2-806
16.6. XDTO Factory Check Rules.......................................................................................2-808
16.6.1. Check Rules for XDTO Factory Proper...........................................................2-808
16.6.2. XDTO Package Check Rules............................................................................2-808
16.6.3. XDTO Value Type Check Rules......................................................................2-809
16.6.4. XDTO Object Type Check Rules.....................................................................2-812
16.6.5. Facet Limitation Rules......................................................................................2-815
Chapter 17. Web Service Mechanism.....................................................................................2-819
17.1. Provision of Functionality through Web Services......................................................2-820
17.2. Example of Web Service Implementation..................................................................2-821
17.3. Using Third-Party Vendor Web Services....................................................................2-823
17.3.1. Example of Using Static Web Service References...........................................2-824
17.3.2. Example of Using Dynamic WS References....................................................2-825
17.4. Editing Web Service Properties..................................................................................2-825
17.4.1. Operation Properties.........................................................................................2-825
17.4.2. Parameter Properties.........................................................................................2-826
Chapter 18. Job Mechanism....................................................................................................2-827
18.1. Background Jobs.........................................................................................................2-828
18.2. Scheduled Jobs............................................................................................................2-829
18.3. Running Background Jobs in  File Mode and Client/Server Mode............................2-831
18.3.1. File Mode .........................................................................................................2-831
18.3.2. Client/Server Mode...........................................................................................2-832
18.4. Creation of Scheduled Job Metadata...........................................................................2-832
Chapter 19. Full-Text Data Search Mechanism.....................................................................2-835
19.1. General Information on Full-Text Indexing................................................................2-835
19.2. Use of Full-Text Search Mechanisms.........................................................................2-837
19.3. Use of Additional Dictionaries....................................................................................2-839
2-684 1C:Enterprise 8.3. Developer Guide

Chapter 20. Temporary Storage Mechanism, Working with Files and Pictures................2-841
20.1. Temporary Storage......................................................................................................2-841
20.2. Working with Files and Temporary Storage...............................................................2-842
20.2.1. Saving Data from File in  Temporary Storage..................................................2-842
20.2.2. Data Placement in  Temporary Storage............................................................2-843
20.2.3. Data Retrieval from Temporary Storage..........................................................2-843
20.2.4. Data Deletion from Temporary Storage...........................................................2-844
20.2.5. Address Check for Temporary Storage Membership.......................................2-844
20.2.6. Attribute Address Retrieval..............................................................................2-844
20.2.7. File Retrieval from Infobase.............................................................................2-844
20.2.8. Example of File Method Use............................................................................2-846
20.2.9. Enabling Bulk File Operations.........................................................................2-847
20.2.10. Working with Temporary Storage in  Background Job..................................2-849
20.2.11. Address Support in  Picture Box....................................................................2-849
20.2.12. Access to standard directories.........................................................................2-851
20.3. Specific Features of Using in  Web Client..................................................................2-851
Chapter 21. The Event Log......................................................................................................2-853
21.1. Details Management....................................................................................................2-853
21.2. Writing Events.............................................................................................................2-854
21.3. Event Logging Management.......................................................................................2-854
21.3.1. The Access Event Parameters Configuration...................................................2-854
21.3.2. Access Denied Event Parameters Configuration..............................................2-857
21.4. Getting Event Log Records.........................................................................................2-858
21.5. Additional Methods.....................................................................................................2-862
Chapter 22. The Cryptographic Mechanism..........................................................................2-863
22.1. General Mechanism Description.................................................................................2-863
22.2. Main Concepts.............................................................................................................2-864
22.3. General Principles of Using Cryptographic Mechanisms...........................................2-864
22.4. Working with Cryptographic Modules.......................................................................2-865
22.5. Usage Examples..........................................................................................................2-866
Chapter 23. External Data Sources.........................................................................................2-871
23.1. Working with relational external data sources............................................................2-871
23.1.1. Overview...........................................................................................................2-871
23.1.2. General Usage Principles..................................................................................2-873
23.1.3. Editing External Data Source Structure............................................................2-873
23.1.4. Example of External Data Source Table Creation ...........................................2-877
23.1.5. ODBC Connection String.................................................................................2-879
23.2. Working with an external OLAP data source.............................................................2-880
23.2.1. Overview...........................................................................................................2-880
23.2.2. The general principles of usage........................................................................2-882
23.2.3. Editing external data source structure...............................................................2-883
23.2.4. Query Language Limitations When Using
an Analytical External Data Source.................................................................2-886
23.2.5. An OLAP Server Connection String................................................................2-887
23.3. External Data Source Management.............................................................................2-888
23.4. Connecting to an External Data Source in  1С:Enterprise Mode................................2-890
23.5. Using External Data Sources.......................................................................................2-890
23.5.1. The Execution Location of External Data Source Queries...............................2-890
Contents 2-685

23.5.2. Using External Data Sources............................................................................2-891

23.5.3. Rules for Converting Values.............................................................................2-893
23.5.4. An external data source included in  a separator..............................................2-894
Chapter 24. The Data Separation Mechanism.......................................................................2-895
24.1. Overview.....................................................................................................................2-895
24.2. Common Attribute Properties.....................................................................................2-897
24.2.1. Using Separated Data........................................................................................2-897
24.2.2. The Separator Value and Usage Flag...............................................................2-898
24.2.3. Users Separation...............................................................................................2-899
24.2.4. Authentication Separation.................................................................................2-900
24.2.5. Conditional Separation.....................................................................................2-900
24.3. Determining an Ability to Perform an Action or a  Dataset........................................2-909
24.4. Setting Separator Values on Startup............................................................................2-910
24.4.1. The Client Application Command Line............................................................2-911
24.4.2. The Web Client or Thin Client Connected via a  Web Server.........................2-912
24.4.3. External Connection and Connection Strings...................................................2-913
24.5. Safe Data Separation Mode.........................................................................................2-913
24.6. Data Area Deletion......................................................................................................2-915
24.7. Specifics of System Objects Behavior........................................................................2-916
Chapter 25. Developing solutions for the mobile platform...................................................2-917
25.1. General Information....................................................................................................2-917
25.2. The Application Interface............................................................................................2-918
25.3. Usage Specifics...........................................................................................................2-919
25.3.1. The Global Command Interface.......................................................................2-919
25.3.2. User Messages..................................................................................................2-919
25.3.3. Form..................................................................................................................2-919
25.3.4. Working With Files..........................................................................................2-921
25.3.5. Special Features................................................................................................2-922
25.3.6. Text Input..........................................................................................................2-924
25.3.7. Reports..............................................................................................................2-924
25.3.8. Working With Images.......................................................................................2-925
25.4. Interaction with a  mobile device during mobile application development................2-926
25.4.1. Installation of the 1C:Enterprise Mobile Platform for Developers ..................2-927
25.4.2. Publishing a  Mobile Application on the Web Server......................................2-929
25.4.3. Starting and Restarting an Application on the Mobile Platform......................2-931
25.4.4. Managing Applications on the 1C:Enterprise
Mobile Platform for Developers.......................................................................2-931
25.4.5. Mobile Application Checkup Before Publishing in  an Application Store.......2-933
25.5. Preparing the Mobile Application for Publishing in  an Application Store................2-935
25.5.1. For iOS..............................................................................................................2-935
25.5.2. For Android......................................................................................................2-936
Chapter 26. Development Tools...............................................................................................2-937
26.1. Form Editor.................................................................................................................2-937
26.1.1. Background Information...................................................................................2-937
26.1.2. Role-Based Form Setup....................................................................................2-942
26.2. Text Editor...................................................................................................................2-943
26.2.1. Editing Modules................................................................................................2-943
26.2.2. Editing Text Templates.....................................................................................2-957
2-686 1C:Enterprise 8.3. Developer Guide

26.2.3. Editing Template Text......................................................................................2-965

26.2.4. Query Text Editor.............................................................................................2-966
26.3. Configuration Command Interface Editor...................................................................2-966
26.3.1. General Rules for Setting Visibility..................................................................2-966
26.3.2. Filter by Roles...................................................................................................2-967
26.4. Start Page Work Area Editor.......................................................................................2-967
26.5. Main Section Command Interface Editor....................................................................2-968
26.6. Command Interface Editor..........................................................................................2-970
26.7. All Subsystems Editor.................................................................................................2-971
26.7.1. Subsystem Contents Setup................................................................................2-972
26.7.2. Subsystem Command Interface Settings..........................................................2-972
26.8. Query Wizard..............................................................................................................2-972
26.9. Query Wizard with Result Processing........................................................................2-979
26.10. Register Record Wizard............................................................................................2-980
26.11. Print Wizard..............................................................................................................2-982
26.12. Generation settings wizard........................................................................................2-985
26.13. Configuration Object Form Wizard..........................................................................2-987
26.13.1. Constant Form Wizard Features.....................................................................2-989
26.14. Template Wizard.......................................................................................................2-990
26.15. Format String Wizard................................................................................................2-992
26.16. Wizard for Strings in  Different Languages..............................................................2-995
26.17. Spreadsheet Document Editor...................................................................................2-996
26.17.1. Spreadsheet Documents in  1C:Enterprise......................................................2-996
26.17.2. Template.........................................................................................................2-997
26.17.3. Spreadsheet Document in  Data Input Mode................................................2-1001
26.18. Flowchart Editor......................................................................................................2-1006
26.18.1. Flowchart Editing.........................................................................................2-1007
26.18.2. Flowchart Items............................................................................................2-1007
26.18.3. Flowchart Items............................................................................................2-1009
26.18.4. Module..........................................................................................................2-1012
26.19. Picture Editor...........................................................................................................2-1012
26.19.1. Picture Editing..............................................................................................2-1013
26.19.2. Picture Collections........................................................................................2-1016
26.20. HTML Document Editor.........................................................................................2-1017
26.20.1. Visual Editing...............................................................................................2-1017
26.20.2. Editing in  HTML Format.............................................................................2-1020
26.20.3. Viewing Results............................................................................................2-1021
26.21. Localization of Configurations................................................................................2-1021
26.22. Centralized Configuration Check............................................................................2-1025
26.23. Usability Analysis for Operation of Solutions Based
on 1C:Enterprise Platform......................................................................................2-1031
Chapter 27. Debugging and Testing of Application Solutions............................................2-1033
27.1. Debugger...................................................................................................................2-1033
27.1.1. Debugger Use.................................................................................................2-1034
27.1.2. Breakpoint.......................................................................................................2-1042
27.1.3. Step-by-Step Execution..................................................................................2-1044
27.1.4. Debugging External Data Processors (Reports).............................................2-1046
27.1.5. Debug Management........................................................................................2-1046
27.1.6. Expression Window........................................................................................2-1047
27.1.7. Immediate Window.........................................................................................2-1049
Contents 2-687

27.1.8. Call Stack........................................................................................................2-1050

27.1.9. Debugging Protected Modules........................................................................2-1051
27.1.10. Use Options..................................................................................................2-1051
27.2. Performance Meter....................................................................................................2-1052
27.2.1. Available Options...........................................................................................2-1052
27.2.2. Measurement Results......................................................................................2-1053
27.2.3. Sorting Measurement Results.........................................................................2-1056
27.2.4. Selective Summarization of Measurement Results........................................2-1056
27.2.5. Performance Meter in  Client/Server Base Operation....................................2-1056
27.2.6. Saving Results................................................................................................2-1056
27.3. Server Call Delay Imitation.......................................................................................2-1057
27.4. Display of Server Calls.............................................................................................2-1057
27.5. Automated testing of applied solutions.....................................................................2-1060
27.5.1. General Information........................................................................................2-1060
27.5.2. Running the Testing system............................................................................2-1061
27.5.3. Description of features....................................................................................2-1064
27.5.4. Sample Testing Scenario................................................................................2-1068
27.5.5. Service Options...............................................................................................2-1069
Chapter 28. Compare and Merge Configurations...............................................................2-1071
28.1. Configuration Comparison Conditions.....................................................................2-1071
28.2. Launch of Configuration Comparing and Merging Mode........................................2-1072
28.3. Compare Configurations...........................................................................................2-1073
28.4. Compare Predefined Data.........................................................................................2-1074
28.5. Compare and Merge Configurations Window..........................................................2-1074
28.6. Configuration Comparison Setting............................................................................2-1075
28.7. Object Editing...........................................................................................................2-1077
28.8. Distributed Development and Support – Editing......................................................2-1077
28.9. Object Mapping.........................................................................................................2-1077
28.10. Merging Mode.........................................................................................................2-1078
28.11. Setting Order of Subordinate Objects.....................................................................2-1082
28.12. Viewing Differences...............................................................................................2-1082
28.13. Module Comparison................................................................................................2-1083
28.14. Filtering Objects and Activating Merging..............................................................2-1085
28.15. Loading Configuration from File............................................................................2-1086
Chapter 29. Distributed Configuration Development.........................................................2-1087
29.1. Configuration Repository Administration.................................................................2-1088
29.1.1. Creation of Configuration Repository............................................................2-1088
29.1.2. Open Configuration Repository......................................................................2-1089
29.1.3. Maintaining the Configuration Repository Users List....................................2-1092
29.1.4. Configuration Repository Administration......................................................2-1093
29.1.5. Repository Backup Configuration..................................................................2-1096
29.2. Working with Configuration Repository...................................................................2-1096
29.2.1. Configuration Repository Filter......................................................................2-1097
29.2.2. Locking Configuration Repository Objects....................................................2-1098
29.2.3. Object Placement in  Configuration Repository.............................................2-1099
29.2.4. Object Retrieval from Configuration Repository...........................................2-1100
29.2.5. Release of Object Locks.................................................................................2-1100
29.2.6. Update of Configuration Repository Object Statuses.....................................2-1101
29.2.7. Comparison of Configuration Repository and Current Configuration...........2-1101
2-688 1C:Enterprise 8.3. Developer Guide

29.2.8. Comparison of Configuration Repository Objects

and Current Configuration Objects.................................................................2-1101
29.2.9. Save Configuration Repository as Configuration...........................................2-1102
29.2.10. Disconnection from Configuration Repository.............................................2-1102
29.2.11. Configuration Repository History................................................................2-1102
29.2.12. Object History...............................................................................................2-1106
29.2.13. Actions with Configuration Repository without Connection.......................2-1107
29.3. Remote Work with Configuration Repository..........................................................2-1108
29.3.1. Architecture Overview....................................................................................2-1108
29.3.2. Configuration Repository Server Installation.................................................2-1110
29.3.3. Web Server Setup for Work with Configuration Repository.........................2-1111
29.3.4. Launch of Configuration Repository Server...................................................2-1116
29.3.5. Connection to Configuration Repository Server............................................2-1118
29.3.6. Creation of Configuration Repository............................................................2-1119
29.3.7. Remote Work with Configuration Repository (Special Features)..................2-1119
29.4. Recommendations on How to Use Configuration Repository..................................2-1120
Chapter 30. Configuration Distribution and Support.........................................................2-1121
30.1. Distribute Configuration...........................................................................................2-1122
30.1.1. Distribution Set Options.................................................................................2-1122
30.1.2. Creation of Distribution Files.........................................................................2-1124
30.1.3. Preparing Distribution Kits for Standard Configurations...............................2-1125
30.2. Configuration Support...............................................................................................2-1131
30.2.1. Setting Configuration Support........................................................................2-1132
30.2.2. Support Setting...............................................................................................2-1132
30.2.3. Configuration Update.....................................................................................2-1136
30.2.4. Template Directory Description File..............................................................2-1141
Chapter 31. Service Features.................................................................................................2-1143
31.1. Window Management ..............................................................................................2-1143
31.1.1. State (Window Placement Mode)...................................................................2-1143
31.1.2. Window Settings Dialog Box.........................................................................2-1146
31.1.3. Use of New Window Mode............................................................................2-1147
31.1.4. Service Windows............................................................................................2-1147
31.1.5. Closing Windows............................................................................................2-1147
31.1.6. Window Navigation History...........................................................................2-1148
31.2. Setting Designer Parameters.....................................................................................2-1148
31.2.1. General............................................................................................................2-1148
31.2.2. Texts...............................................................................................................2-1149
31.2.3. Modules..........................................................................................................2-1150
31.2.4. 1C:Enterprise Startup......................................................................................2-1154
31.2.5. Help.................................................................................................................2-1159
31.3. Calculator..................................................................................................................2-1160
31.4. Calendar....................................................................................................................2-1160
31.5. Text Templates..........................................................................................................2-1160
31.5.1. Template List Maintenance............................................................................2-1161
31.5.2. Editing Templates...........................................................................................2-1162
31.6. Syntax Assistant........................................................................................................2-1170
31.6.1. Syntax Assistant Settings................................................................................2-1171
31.6.2. Content Tab of Syntax Assistant....................................................................2-1171
31.6.3. Copying 1C:Enterprise Script Items...............................................................2-1172
Contents 2-689

31.6.4. Search in  Syntax Assistant.............................................................................2-1172

31.7. File Comparison........................................................................................................2-1175
31.7.1. Comparison of External Data Processors.......................................................2-1176
31.8. Built-in System for Help Content Retrieval..............................................................2-1176
Chapter 32. Add-Ins...............................................................................................................2-1177
32.1. Work in  Thin and Thick Clients...............................................................................2-1178
32.2. Work in  Web Client.................................................................................................2-1178
32.3. Work on Server.........................................................................................................2-1179
32.4. Examples of Add-In Use...........................................................................................2-1180
32.4.1. Native API Technology..................................................................................2-1180
32.4.2. COM Technology...........................................................................................2-1182
Chapter 33. Specifics of Cross-platform Applied Solution Development..........................2-1183
33.1. File System Specifics................................................................................................2-1183
33.2. Working with External Devices................................................................................2-1184
33.3. Rights Limitations.....................................................................................................2-1185
33.4. Fonts..........................................................................................................................2-1185
33.5. HTMLDocumentField...............................................................................................2-1185
33.6. COM, OLE, and ActiveDocument Mechanisms.......................................................2-1186
Appendix 1. URL Formats.....................................................................................................2-1187
1.1. URL Format Overview................................................................................................2-1187
1.2. Host Address Format...................................................................................................2-1188
1.3. Internal Links..............................................................................................................2-1189
1.3.1. Infobase Object Link........................................................................................2-1189
1.3.2. Infobase Object Attribute Link.........................................................................2-1190
1.3.3. Infobase Object Tabular Section Attribute Link...............................................2-1190
1.3.4. Infobase Register Record Link.........................................................................2-1190
1.3.5. Infobase Register Record Attribute Link..........................................................2-1191
1.3.6. Report Link.......................................................................................................2-1191
1.3.7. Data Processor Link..........................................................................................2-1191
1.3.8. Section Link......................................................................................................2-1191
1.3.9. Link to the Navigation Point Created by the Standard Command...................2-1192
1.3.10. Temporary Storage Link.................................................................................2-1192
1.3.11. Link to an External Data Source Table Record..............................................2-1192
1.3.12. Links to Global Command Interface Commands...........................................2-1192
1.3.13. Links to Lists..................................................................................................2-1193
1.3.14. Link to the start page......................................................................................2-1193
Appendix 2. Rules for Generating Standard Commands
and Automatic Form Headers....................................................................................2-1195
Appendix 3. List of Auto-Saved Settings..............................................................................2-1199
Appendix 4. Full-Text Search Expressions...........................................................................2-1207
Appendix 5. Description of Access Rights............................................................................2-1209
Appendix 6. System Behavior in  Various Modes................................................................2-1213
6.1. Special Characteristics of Low Connection Speed Mode...........................................2-1213
6.2. Special Characteristics of Compatibility Mode..........................................................2-1214
6.3. Specific Characteristics of Web Client.......................................................................2-1220
6.4. Web Client Specifics for iPad.....................................................................................2-1228
2-690 1C:Enterprise 8.3. Developer Guide

6.5. Specifics of System Object Behavior with Enabled Data Separation Mode...............2-1229
6.5.1. Changing Separator Values..............................................................................2-1229
6.5.2. Object Numeration............................................................................................2-1230
6.5.3. Real-Time Timestamp......................................................................................2-1230
6.5.4. Predefined Data.................................................................................................2-1230
6.5.5. Access Rights....................................................................................................2-1231
6.5.6. Users.................................................................................................................2-1231
6.5.7. Exchange Plans.................................................................................................2-1232
6.5.8. Functional Options............................................................................................2-1233
6.5.9. Scheduled Jobs..................................................................................................2-1233
6.5.10. Background Jobs.............................................................................................2-1234
6.5.11. Web Services..................................................................................................2-1235
6.5.12. Constants.........................................................................................................2-1235
6.5.13. Registers.........................................................................................................2-1235
6.5.14. Document Sequence.......................................................................................2-1238
6.5.15. Infobase Options.............................................................................................2-1239
6.5.16. Session List.....................................................................................................2-1239
6.5.17. Connection List...............................................................................................2-1239
6.5.18. The Event Log................................................................................................2-1239
6.5.19. Settings and Favorites.....................................................................................2-1243
6.5.20. History............................................................................................................2-1243
6.5.21. Queries............................................................................................................2-1244
6.5.22. Managed Transaction Locks...........................................................................2-1244
6.5.23. Exclusive mode...............................................................................................2-1244
6.5.24. Deleting Marked Objects................................................................................2-1245
6.5.25. Full-text search...............................................................................................2-1245
6.6. Running the Client Application in  Linux...................................................................2-1246
6.7. Specifics of Mobile Application Operations...............................................................2-1247
Appendix 7. Operation of Various DBMS............................................................................2-1249
7.1. General Features..........................................................................................................2-1249
7.2. File Database...............................................................................................................2-1249
7.3. IBM DB2 Server.........................................................................................................2-1250
7.4. Microsoft SQL Server.................................................................................................2-1251
7.5. Oracle Database Server...............................................................................................2-1252
7.6. PostgreSQL Server......................................................................................................2-1253
Appendix 8. Work in  XBase..................................................................................................2-1255
8.1. Fields and Records......................................................................................................2-1255
8.2. Spreadsheet, Spreadsheet Structure and Database File...............................................2-1255
8.3. Indices, Index and Filter Expressions and Index File.................................................2-1256
8.4. Writing Changes to Database......................................................................................2-1256
8.5. Work with Index Files.................................................................................................2-1256
8.6. Record Deletion...........................................................................................................2-1256
8.7. Creation of Database, Index and Index File................................................................2-1257
8.8. Limitations..................................................................................................................2-1257
Appendix 9. Specifics of Using Separate Mechanisms........................................................2-1259
Appendix 10. Automatic Form Element Name Generation Rules.....................................2-1261
Chapter  13

BUSINESS PROCESSES
AND TASKS

13.1. MAJOR CONCEPTS

Business processes in 1C:Enterprise are intended to combine separate opera-
tions into chains of interrelated actions, allowing specific goals to be attained.
For example, the issuance of an invoice, acceptance of cash payment and shipment
of goods from a  warehouse can be combined into the Cash Sale of Goods business
process.
The 1C:Enterprise business processes allow formalization of the procedure
of processing various events of an organization's activities and assurance of
performers' participation therein.
The use of business process mechanisms in  applications makes them more effec-
tive, improves the final result and finds new opportunities.
Business processes allow for a  switch to process-based management and qualita-
tively improve the enterprise's operation through re-engineering and automation of
business processes.
Automation of key business processes that begin and end outside the organization
is  the most effective.
Chains of interrelated operations within a business process are presented in the
business process flowchart. A flowchart describes the logic of the business process
and its entire life cycle, from start to finish, in  the form of a  map of the passing
sequence for interrelated points in  the process.
This refers to a  successive performance of a  chain of interrelated operations as the
business process progresses.
2-692 1C:Enterprise 8.3. Developer Guide

Route point reflects a stage in the life cycle of a business process, normally
involving the performance of a  single automatic or manual operation.
Tasks in  1C:Enterprise allow record keeping for assignments sorted by performers
and reflect the progress of business processes to later points on the flowchart.
In  addition to business processes, tasks can be created by other infobase objects or
directly by users.

13.2. GENERAL INFORMATION

The 1C:Enterprise business processes mechanism has several configurable objects:
„„ Business processes
„„ Tasks
„„ Information register
„„ Session parameter
As a rule, task addressing attributes and information register dimensions are of
a  reference type (e.g., CatalogRef which is  why in  addition to the above four
types, there are also catalogs).

Fig. 276.  Flowchart of Business Processes

Main objects – business processes and tasks – interact (e.g., a business process
creates tasks and performance of a  task results in  progress in  the business process).
Auxiliary objects – session parameters, information registers and catalogs – do not
use each other or main objects.
When creating a  business process flowchart, catalogs with predefined data (roles,
departments, etc.) are used to assign values to the route points' addressing proper-
ties. Business processes create tasks when they reach further points of the flowchart
and use Addressing (information register, see below) to process group points.
Upon completion of their performance, tasks notify business processes, thus further
advancing them. They use the information register to select tasks for the current
performer in  compliance with session parameters.
Chapter 13. Business Processes and Tasks 2-693

13.3. ROUTING
The 1C:Enterprise business processes allow the use of the following routing types:
„„ Hard. The  business process has a  strict flowchart, comprising no conditional
or parallel jumps, with strictly defined recipients at each route point. This  type
involves no free or conditional routing.
„„ Free. Recipients at different points of the business process flowchart are not
preset. They are determined by software or interactively during the life cycle of
the business process.
„„ Conditional. The flowchart provides for a conditional test and progress
along the corresponding branches. Jumps can be both binary (conditional) and
multiple (switch).
„„ Parallel. The  flowchart provides for the splitting of the business process into
parallel branches with subsequent joining (wait) possible. The  business process
progresses along each of the parallel branches separately as the tasks are
performed.
In real business process flowcharts, all the above routing types are normally used.

13.4. ADDRESSING SYSTEM

The key concept in the 1C:Enterprise business processes and tasks mechanism
is the addressing system. The addressing system is mainly designed to allow
addressing business process participants not only personally, but also by roles.
Role-based addressing (routing) is a set of rules and conventions speci-
fied in metadata objects' settings which allow definition of the final recipient
(performer) based on the assigned roles, subdivision membership and other
addressing attributes.
Task addressing attributes determine the dimension of the address space as applied
to the automated application domain. They are used to determine performers that
own the tasks.
Specific performers are determined on the basis of the following task properties:
Addressing, Main addressing attribute and Current performer.
The process for determining the key addressing attribute among all addressing
attributes is  referred to as dereferencing.
Addressing is a register of updated information, linking performers (the key
addressing attribute) to departments, workgroups, functions, etc., i.e. all the other
task addressing attributes.
One of the addressing attributes is the key attribute and it indicates a specific
employee, the performer of the assignments.
2-694 1C:Enterprise 8.3. Developer Guide

Fig. 277.  Flowchart of Addressing

The following example illustrates the operation of the addressing system.

Assume an information register comprises two dimensions, role and employee,
with the following records:
Role Employee
Cashier Jones
Manager Peters

At a  certain point in  a business process (e.g., Accept Cash Payment), addressing
properties have only the Cashier role. When the business process reaches this point,
a  single task is  generated:
Task Property Value
Name Accept cash payment
Role Cashier
Employee -

When employee Jones browses his task list, the addressing system displays this
task, because the information register contains a  record attributing the Cashier role
to Jones. Employee Peters cannot see this task.
Here is  an approximate sequence of operations for the creation of two different
business processes.
1. Let us proceed from the assumption that the addressing system comprises three
dimensions: employee, role and department.
2. Create catalogs for each of the planned addressing dimensions (Employees,
Roles and Departments) and fill them in  with predefined values, e.g.:
Employees Roles Departments
Jones Cashier Accounts Department
Peters Manager Sales Department
Smith Head of Department Warehouse
Storeroom Clerk
Chapter 13. Business Processes and Tasks 2-695

3. Create an information register and add one dimension to it  per the previously
created catalog. Indicate the types for the dimensions as references to the corre-
sponding catalogs, e.g.:
Dimension Type
Employee CatalogRef.Employees
Role CatalogRef.Role
Department CatalogRef.Departments

4. Create the CurrentPerformer session parameter and assign it the Cata-

logRef.Employees type.
5. Initialize the session parameter when starting the system, e.g.:

Procedure SessionParametersSetting(RequiredParameters)

User = Catalogs.Employees.FindByDescription(UserName());
SessionParameters.CurrentPerformer = User;

EndProcedure

6. Create a  task.
7. Set the previously created information register as a  property of the Addressing
task.
8. Add addressing attributes similar to dimensions of the information register:
○○ Employee
○○ Role
○○ Department
9. Indicate the type of the task addressing attributes created in  the form of a  refer-
ence to the corresponding directory and set references to the information
register dimension in  the Addressing attributes property.
Addressing Attribute Type Addressing Dimension
Employee CatalogRef.Employees Employee
Role CatalogRef.Role Role
Department CatalogRef.Departments Department

10. Select the Employee attribute as the key addressing attribute by setting it  in  the
corresponding task property.
11. Create the first business process with a  reference to the previously created task
(the Task property) within it.
2-696 1C:Enterprise 8.3. Developer Guide

Design a flowchart of the business process by setting the required addressing

attributes for route points, selecting values from preset data in  the corresponding
catalogs.

Fig. 278.  Business Process Map

12. Create the next business process with a  reference to the same task.
13. Design a  flowchart for the new business process. And so on.
This example is  used below to comment on the key particularities of 1C:Enterprise
business processes.
Let us discuss some of them in  detail.

13.5. STARTING BUSINESS PROCESSES

A business process starts when you select the Start() method or click Start and
сlose in  the object form.
The code fragment below is responsible for software creation, recording and
startup of a  business process.

BP = BusinessProcesses.Match.CreateBusinessProcess();
BP.Date = CurrentDate();
BP.Write();
BP.Start();
Chapter 13. Business Processes and Tasks 2-697

The following sequence of operations is  performed during startup:

No Internal mechanism 1C:Enterprise script handlers
1 BeforeStart handler invocation at the startup point
2 Jump to the point of action in  compliance
with the flowchart
3 Creation of tasks (see page 2-700)

A business process can be recorded without being starting. This  option is  useful
if you would like the business process started later than it  is  created. For example,
a  business process can start upon occurrence of a  certain event.

13.6. TASK PERFORMANCE

The ExecuteTask() method checks the performance process, then marks the task
as performed and notifies the business process. If all conditions are met, the busi-
ness process jumps to the next route point.
No Internal mechanism 1C:Enterprise script handlers
1 Transaction start
2 Invocation of the task's BeforeExecute
handler
3 Invocation of the BeforeExecute handler of
the corresponding route point
4 The Completed task property is  set to True
5 Invocation of the task's OnExecute handler
6 Task object recording
7 Invocation of the OnExecute handler of the
corresponding route point
8 Business process jumps to the next route point
9 Task generation at the new route point (see page
2-700)
10 Transaction completion

13.7. SPLITTING AND JOINING

To split a  business process into several branches performed in  parallel (simultane-
ously and independently of each other), a  splitting point is  used. A splitting point
has one input and an unlimited number of outputs.
To synchronize previously split branches, a  join is  used. A business process waits
at the join until all its branches arrive. Thus, a join is a business process stage
where all tasks involving the previously split branches must be completed.
Splitting and joining may be nested. If it is, each join synchronizes only the
branches of its own splitting point.
2-698 1C:Enterprise 8.3. Developer Guide

IMPORTANT!
Splitting does not necessarily require joining. A business process may have sev-
eral parallel branches up until its completion.
Joining is impossible without splitting. If this condition is not met, the system
displays the following message when checking the flowchart: Some lines entering
merge point do not leave branch point.

13.8. MANUAL CONTROL

Business process completion and task performance attributes can be assigned
manually, overriding the business process mechanism. However, this should only
be done if all consequences involved are known.

13.8.1. Business Process Completion Attribute

If the completion attribute is assigned, the business process will be regarded as
complete, even though some of the tasks linked to it  may not have been performed.
When these tasks are performed, the business process will not progress.
The completion attribute can be assigned to non-started business processes as well.
If it  is, their startup will be impossible.
If the completion attribute is  manually removed from a  complete business process,
tasks linked to it  will remain performed. Thus, the business process will not be
complete, but all its tasks will be performed. These business processes cannot be
restarted because the system regards them as started (they have one or more tasks).
This is why, when manually removing the completion attribute, performance
attributes should also be removed from the appropriate tasks, so that the business
process returns to the required route point.

13.8.2. Task Performance Attribute

If the performance attribute is manually assigned to a task, the business process
does not jump to the next route point. In  addition, the BeforeExecute() and OnEx-
ecute() task handlers and the corresponding route point handlers are not invoked.
Manual assignment of the performance attribute can stop the business process:
it  will not be complete, but neither will it  be linked to any unperformed task.
Removal of the performance attribute from a  task can create a  parallel flow in  an
unfinished business process. Assume, for example, a  business process is  incom-
plete and has one performed task and one unperformed task. If the performance
attribute is  removed from the performed task, the business process will have two
unperformed tasks. When performing each of them, the business process will
progress from the point corresponding to the performed task. The  business process
will be considered complete when all tasks in  both parallel branches have been
performed.
Chapter 13. Business Processes and Tasks 2-699

If the performance attribute is removed from a task whose business process

is  already complete, the task is  displayed on lists as unperformed, but its perfor-
mance does not result in  progress of the business process.

13.8.3. Task Removal

Removal of unperformed tasks can stop an incomplete business process. The  busi-
ness process will be unfinished, but all its tasks will be inactive (incomplete).
Tasks reflect the real flowchart of a business process. They show which points
have been passed and which remain active (incomplete). That is  why task removal
can result in  an incorrect and inconsistent display of passed and active points on
the flowchart.
If all tasks of an incomplete business process are removed, the process will be
assigned a  non-started status.

13.8.4. Task Addition

If a new task is manually created for a complete business process, the latter
remains complete and performance of the task does not result in  its progress.
If a new task is manually created for a non-started business process, the latter
starts and upon performance of the task it  jumps to the next route point.
If a  new task is  created for a  started and incomplete business process, the latter
is  divided into parallel branches.

13.9. CONDITIONAL JUMP

For conditional branching of business processes, conditional jump points are used.
An important feature of these points is  the conditional test handler, a  mandatory
element checked during flowchart verification before saving the business process.
If the handler is missing, the system displays the following warning: Condition
point does not have a  "Condition Check" event handler.
This handler returns conditional test results that determine the selection of the next
route point. If the result is  True, the business process jumps to the Yes branch,
otherwise it  jumps to the No branch. The  default value is  False.
A sample conditional test handler is  shown below:
Procedure DiscountLimitationConditionCheck(BPRoutePoint, Result)

If GetDiscountForAccount() > GetStandardDiscount() Then

Result = True;
Else

Result = False;
EndIf;
EndProcedure
2-700 1C:Enterprise 8.3. Developer Guide

For a  multiple selection, you can use several successive conditional jump points.
Switch points, however, are easier to use.

13.10. SWITCH
To select one of the available paths, switch points are used. An important feature
of these points is  a switch handler, a  mandatory element checked during flowchart
verification before saving the business process. If the handler is missing, the
system displays the following warning: Option selection point has no handler for
event "SwitchData processor".
This handler assigns one of preset values to the Result property. A sample handler
is  shown below:
Procedure Switch (SwitchPoint, Result)
If PaymentType = Enums.PaymentType.Cash Then
Result = SwitchPoint.Cases.Cash;
ElseIf PaymentType = Enums.PaymentType.Check Then
Result = SwitchPoint.Cases.Check;
ElseIf PaymentType = Enums.PaymentType.Netting Then
Result = SwitchPoint.Cases.Netting;
ElseIf PaymentType = Enums.PaymentType.Credit Then
Result = SwitchPoint.Cases.Credit;
EndIf;
EndProcedure

In this handler, PaymentType is  a business process attribute.

An empty value of Result during the switch handler procedure results in  an error
and cancels the transaction involved in  the switch.

13.11. TASK GENERATION

Tasks are only generated when a business process reaches a point of action or
a point of a business subprocess. When passing other points (conditional jump,
splitting, joining, processing, etc.), a  business process automatically performs the
required operations and jumps to the next point according to the flowchart.
To illustrate this, let us discuss the way a  business process jumps to the first point
of action when the Start() method is  invoked.
When jumping to points of action or business subprocesses points within a  flow-
chart, a  business process can create one or more tasks. Several tasks are generated
if the route point is  marked as a  group. In  this case the business process selects
all records complying with the addressing attributes assigned to this point by the
information register (Addressing) and generates a  task for each record.
For example, if a route point is only addressed by the Cashier role and the
information register contains two type records, two tasks are generated with both
addressing attributes – role and final performer.
Chapter 13. Business Processes and Tasks 2-701

Employee Role Department

Jones Cashier
Peters Cashier

Thus, for group points on flowcharts, role-based routing is  used only once, when
a  task list is  generated.
The sequence for invocation of event handlers in the 1C:Enterprise script when
jumping to the first point of the Billing flowchart is  illustrated below:
No Internal mechanism 1C:Enterprise script handlers
1 Transaction start
2 BeforeCreateTasks() handler invocation
3 Task list generation
4 OnCreateTask() handler invocation
5 Recording all the generated tasks
6 The task's BeforeWrite() handler invocation
7 Task recording
8 The task's OnWrite() handler invocation
9 Transaction completion

At the second step, the BeforeCreateTasks() handler is called. This handler

is  invoked by the business process before the task list is  generated. This  is  why
it obtains an empty array of tasks generated and can generate them without
standard processing.
At the third step, the business process checks whether the previous handler has
returned StandardProcessing = True. If it has, the addressing attributes
assigned to the route point are dereferenced and a  task or task list (for group points)
is  generated, depending on the number of dereferencing results (e.g., number of
employees in  a department). Each task generated includes a  description, a  link to
the business process, the route point and appropriate addressing attributes.
At the fourth step, the OnCreateTask() handler is  called. This  handler obtains
the task list previously generated by the BeforeCreateTasks() handler or by the
business process. The  tasks have not yet been recorded. In  this handler, the tasks
generated can be fine-tuned: check time, priority and other additional attributes can
be assigned. This  handler also allows new tasks to be added to the array.
At the fifth stage, normal completion of the OnCreateTask() handler is  checked.
If the handler returns Cancel equal to True, task generation is terminated and
an exception is raised. In this example, it cancels the Start() method execu-
tion. If Cancel = False, all tasks in the array generated are recorded with
BeforeWrite() and OnWrite() handlers invoked for each task (steps 6 and 8
respectively).
2-702 1C:Enterprise 8.3. Developer Guide

When a business process generates a task array, the following attributes are
assigned automatically:
„„ Description identical to the description of the corresponding route point, e.g.
Billing;
„„ Reference to an instance of the business process that generated the task;
„„ Reference to a  point on the business process flowchart;
„„ Task addressing attributes identical to the addressing attributes of the corre-
sponding route point. For example, if the route point is addressed to the
Cashier role, the task's Role addressing attribute is  also assigned the Cashier
value.

13.12. PERFORMANCE CHECK

Apart from users, automated procedures can handle task performance as well. For
example, if a  task envisages document posting, an automatic procedure control-
ling such tasks can check if the document has been posted and mark the task as
performed by invoking the Execute() method.
Such automatic procedures are organized using the task's CheckExecution()
method and the corresponding handlers of route points.
A code in the 1C:Enterprise script and the sequence of operations it invokes
is  illustrated below:
If Task.CheckExecution() Then
Task.ExecuteTask();
EndIf

No Internal mechanism 1C:Enterprise script handlers

1 CheckExecution() method invo-
cation processing
2 Invocation of the task's CheckExecutionPro-
cessing() handler. If Result is False, the
CheckExecution() method immediately returns
False
3 Invocation of the CheckExecutionProcessing()
handler of the corresponding route point
4 Return of the handler invocation result
from the previous step. If the value
is  True, then the ExecuteTask()
method is  invoked

For a  description of one of the methods to use automated task performance see
page 2-705.
Chapter 13. Business Processes and Tasks 2-703

13.13. NESTED PROCESS EXECUTION

A flowchart can provide for business subprocess startup. In this case the main
business process waits for the nested process to complete before it  jumps to the
next route point.
When jumping to a  Subprocess route point, the following sequence of operations
is performed:
No Internal mechanism 1C:Enterprise script handlers
1 Transaction start
2 BeforeCreateSubBusinessProcesses()
3 Invocation of the BeforeCreateTasks()
handler for the route point
4 If StandardProcessing, then a  task
array is  generated
5 OnCreateTask()
6 Recording of previously generated task array
and creation of a  business subprocess array
7 OnCreateSubBusinessProcesses()
8 Recording and startup of business processes
generated
9 Transaction completion

Let us discuss this sequence in  detail.

At the second step, the BeforeCreateSubBusinessProcesses() handler
is  called. It  can be used to add custom business processes to the array of generated
business processes (by default, an empty array is  passed to the handler). If business
processes have been added to the array, standard generation of business processes
is  not used.
At the third step, the BeforeCreateTasks() handler is  called. An empty, non-
generated task array is  passed to the handler. If the handler does not modify the
standard processing, the task array it generates is cleared at the third step and
filled in  with a  single task with the preset description and references to a  business
process and a  route point.
At the fifth step, settings of the generated tasks can be adjusted and new tasks can
be added, if necessary.
At the sixth step, the generated tasks are recorded, then a  business subprocess of
the type specified at the route point is  created for each task. The  date is  specified
in  the new business processes and a  reference to the head task is  added.
At the seventh step, the OnCreateSubBusinessProcesses() handler is  called.
This event handler can adjust auto-generated business-processes (their number
is the same as the task number after the OnCreateTask() handler) or delete
some of them, as well as add new business-processes to them. The  list of business
processes is  recorded after handler completion.
2-704 1C:Enterprise 8.3. Developer Guide

13.14. BUSINESS PROCESS COMPLETION

Completion is the last stage in the life cycle of a business process. A business
process is automatically completed (Completed is set equal to True) when
it  reaches the point of completion, provided there are no unperformed tasks linked
to this business process.
If the Head task property is  enabled for the business process, meaning it  is  nested,
when it  is  completed, it  marks the task as performed. As a  result, the main busi-
ness process progresses.
When jumping to the point of completion, the OnComplete() handler is  invoked.
If Cancel is  set equal to True, for example, if any of the business process comple-
tion conditions have not been met, processing is  terminated. The  task at the route
point whose performance resulted in  the jump to the point of completion remains
unperformed.
Completed can be set equal to True (using the 1C:Enterprise script tools or in  the
interactive mode) in  order to terminate the business process or remove it  from the
list of active (unfinished) business processes. In  this case no handlers apart from
BeforeWrite and OnWrite are invoked. The  head task is  not performed.

13.15. STANDARD BUSINESS PROCESS AND TASK ATTRIBUTES

The tables below list predefined fields of business processes and tasks.
The following business process attributes are standard:
Attribute Type
DeletionMark Boolean
Number String or Number
Date Date
Completed Boolean
HeadTask TaskRef.<Task name>
Ref BusinessProcessRef.<Business process name>

The following task attributes are standard:

Attribute Type
DeletionMark Boolean
Number String or Number
Date Date
Description String
Completed Boolean
BusinessProcess BusinessProcessRef.<Business process name>
RoutePoint BusinessProcessRef.<Business process name>
Ref TaskRef.<Task name>
Chapter 13. Business Processes and Tasks 2-705

13.16. BUSINESS PROCESSES WITH SEVERAL STARTING POINTS

The availability of several starting points implies that the selection of a  starting
point depends on conditions external to the business process.
If a  business process has all information it  needs to decide which route to choose,
a  single starting point, followed by a  condition check or switch, is  sufficient.
If the business process has several starting points, one of them should be speci-
fied when invoking the Start() method, otherwise the system displays an error
message. This is why the following should be done when creating a business
process with several starting points:
„„ Define interactive start commands that select the appropriate starting point for
each particular case of business process start.
„„ If the business process is nested, the OnCreateSubBusinessProcesses()
handler should be added to the appropriate route points so that all business
processes from the array of generated business processes are recorded and
started at the correct point.
Example:
Procedure NestedMatchOnCreateNestedBP(BPRoutePoint, ProcessesBeingFormed, Cancel)

For each BusinessProcess from ProcessesBeingFormed Do

BusinessProcess.Write();
Points = BusinessProcesses.DocumentMatch.RoutePoints;
BusinessProcess.Start(Points.SimplifiedMatch);

EndDo
EndProcedure

In other respects, business processes with several starting points are used
in  precisely the same way normal business processes are used.

13.17. FEEDBACK
Other infobase objects (documents or catalog items) can be involved in  business
processes and influence them.
For the business process mechanism to be effective, some tasks should be
performed automatically in response to corresponding operations with other
infobase objects (e.g., when a document is posted, a discount is granted on an
invoice, goods in  stock are inventoried, etc.).
An important feature of the 1C:Enterprise business process mechanism is the
fact that it does not require a substantial modification of the applications used.
This is why response of business processes and tasks to modification of other
infobase objects is  adjustable without substantially modifying the objects.
2-706 1C:Enterprise 8.3. Developer Guide

The following example illustrates the above concept. Assume a task requires
document posting. When the document is posted, the task has to be performed
automatically, so that the user does not have to open the task list, search for the task
and execute it.
To achieve this, perform the following sequence of operations:
„„ Add a  posting notification to the document form:

Procedure AfterWrite(Cancel)

If Posted Then

Notify("DocumentPosting", , ThisObject.Ref);
EndIf;
EndProcedure

„„ Register a  notification handler. To do this, use the OnStart() handler of the

managed application module:
AttachNotificationHandler("NotificationHandler");

„„ Invoke a method (e.g., WorkWithBusinessProcesses) of the server-side

common module from the notification handler and use it  to run the required
checks and execute the task:
// Notification handler in  the managed application module
Procedure NotificationHandler(EventName, Parameter, Source)
Export
If EventName = "DocumentPosting" Then

WorkWithBusinessProcesses.ExecuteTaskForDocument(Source);
EndIf;
EndProcedure

...

&AtServer
// The  WorkWithBusinessProcesses method of the server-side common module
Procedure ExecuteTaskForDocument(DocumentRef) Export

Query = New Query;

Query.SetParameter("Param", DocumentRef);
Query.Text=
"SELECT
|Ref
|FROM
|Task.Task.TasksByExecutive
|
|WHERE
|Document = &Param";
Selection = Query.Execute().Select();
Chapter 13. Business Processes and Tasks 2-707

While Selection.Next() Do

CurrentTask = Selection.Ref.GetObject();
If CurrentTask.CheckExecution() Then

CurrentTask.ExecuteTask();

EndIf;
EndDo;
EndProcedure

Another way to have tasks performed automatically is  to create and enable a  noti-
fication handler that will select all tasks linked to a  performer, check if they should
be performed and, if so, automatically perform them.
In the sections below, we will discuss the particularities of business process and
task object configuration.

13.18. FLOWCHART
A flowchart describes the logic of the business process and its entire life cycle,
from start to finish, in  the form of a  map of the passing sequence for interrelated
points in  the process.
To edit a  flowchart, go to the Other tab in  the business process editing window
and click Route map (for details see page 2-1006).

13.19. BUSINESS PROCESS EDITING

Any number of business processes can be created at the configuration stage.
The  purpose of each business process defines its structure and properties specified
in  the configuration.
The Designer allows a  business process structure to be described and forms and
a  flowchart of the business process to be created.
Business process properties can be edited in the properties palette or the object
editing window (see page 1-59).
Besides the general properties that all metadata objects have, business processes
also have a  number of specific properties.
The Tasks property sets a  reference to a  previously configured task object. A task
already existing in  the configuration must be assigned to each business process.
Business processes use tasks to generate jobs by performers and to start business
subprocesses. If no task is  assigned, when an attempt is  made to save the database
configuration, the system displays the following error message: Business process
task not selected.
Autonumbering. When this property is selected, new business processes are
numbered automatically. An automatically assigned number can be corrected.
2-708 1C:Enterprise 8.3. Developer Guide

Number length. This  property defines the maximum length of a  business process
number. The  Designer allows this length to be set to 0 if numbers are not used
in  this type of business process.
Number type. This  property allows to select a  value type for the business process
number, Number or String. It  is  similar to the document Number format property.
The string type is  useful when a  sophisticated numbering system is  used and the
document number contains not only digits, but also letters and delimiters.
Check uniqueness. If this property is selected, when a new business process
is added, the uniqueness of its number is checked within the limits set in the
Periodicity property.
Periodicity. This  property defines the scope of document number uniqueness veri-
fication and the number recycling period. If Check uniqueness is  selected, then
Periodicity defines the limits of control.
If Autonumbering is  selected, 1C:Enterprise assigns the next consecutive number
to each new business process. Upon completion of the cycle defined in  Perio-
dicity, business process numbering restarts from 1.
The Rights tab can be used to set a  privileged mode for task creation (the Privileged
mode for task creation property):
„„ If this property is  set, the system always generates tasks in  the privileged mode
(at the server side and in file mode version). However, the privileged mode
is  not set if tasks are generated in  the client/server mode at the thick client side.
„„ When new business processes are created, this property is  set to True if the
managed application mode is  selected as the main run mode in  the configu-
ration properties; otherwise if the ordinary application mode is selected, the
property is  set to False.
In addition to the main attributes, a  set of attributes storing additional information
can be created.
If the application domain object to which the business process corresponds has both
basic properties, such as date, number, importance and check time and complex
(list) properties, such as a  list of documents submitted for approval, a  list of reso-
lutions or a  list of business process participants, a  set of tabular sections can be
created for the business process.

13.20. TASK EDITING

Tasks-type objects are designed to distribute assignments among system users and
to have them performed. Assignments can be generated by both users and business
processes.
Tasks can be used on their own or support business processes of different types.
Configuration allows creation of any number of task types. However, one task
is  normally created for all types of business processes.
Chapter 13. Business Processes and Tasks 2-709

The task structure and properties described in the configuration depend on

specifics of the application domain being automated.
You can create multiple list, selection, view and editing forms for each task.
Each task is  characterized by its number, date, time and description. When a  task
is generated by a business process, it is assigned the description of the corre-
sponding point on the business process flowchart.
Task properties can be edited in  the properties palette or the object editing window
(see page 1-59).
In addition to the general properties that all metadata objects have, tasks also have
a  number of specific properties.
Addressing. A task can be assigned a  non-periodical information register whose
dimensions can be linked with task addressing attributes. The links are used
to define the value of the main task addressing attribute based on the data stored
in  the corresponding information register. Therefore, task addressing can be both
performer-specific and role-based.
Main addressing attribute. One of the task addressing attributes can be declared
as main. In this case this is the addressing attribute that points to a specific
performer. If no performer is  specified, the value of this attribute is  determined
on the basis of the information register linked to this task (see the Addressing prop-
erty).
Current performer. Here, a  link can be added to the session parameter where the
current performer is stored. This property is used, for example, as the default
value for the Performer property of the task list table box.
Autoprefix. It  can be set to None and Business process number. If this prop-
erty is  set to Business process number, a  new task number is  automatically
appended with the number of the corresponding business process.
A group of subordinate objects, Addressing attributes, defines a set of attrib-
utes that determine the type and dimension of the addressing system for this
type of tasks, as used for the application domain being automated. One of these
attributes can be declared as main (see the Main addressing attribute property).
The  addressing attributes can be linked to the information register's dimensions.
The  system uses these links to determine the value of the main addressing attribute
if it  is  not specified. Links enable both direct and role-based addressing.
Number length. This  property determines the maximum length of a  task number.
Number type. This  property allows selection of a  value type for the task number,
Number or String. The string type is useful when a sophisticated numbering
system is  used and the document number contains not only digits, but also letters
and delimiters.
Check uniqueness. If this property is selected, when a new task is added, the
uniqueness of its number is  checked.
2-710 1C:Enterprise 8.3. Developer Guide

Autonumbering. Check this property if you want a  number to be assigned automati-

cally to the task at its creation. An automatically assigned number can be corrected.
If the application domain object to which the task corresponds has both basic
properties, such as date, number, importance and check time and complex (list)
properties, such as a list of documents submitted for approval, a set of tabular
sections can be created.
Chapter  14

DATA ANALYSIS
AND FORECASTING

Data analysis and forecast is intended for implementing tools for discovering
dependencies that are usually hidden behind large amounts of data.For instance,
one can analyze sales data and identify groups of goods that are usually purchased
together. In  the future (one of multiple variants) this information can be used to
merchandize goods at a  retail store. Goods may be grouped together (when a  buyer
comes to a  store, she or he sees a  barbecue and firelighters liquid, charcoal, meat,
fishing tackle and a  rubber boat nearby and purchases all of it) or in  different areas
of the store (a buyer comes to buy milk, and by the time he or she gets to the bread
section they will have traversed half of the store).
Another use of the data analysis mechanism is forecasting a contractor’s behavior
based on the existing data. By completing such an analysis one can find out to what
degree their purchasing volumes depend on territorial distribution, the size of the
company, period of cooperation, and other factors. Based on these dependencies,
a  new contractor’s behavior may be forecast, and a  strategy of cooperation developed.
Use the forecasting functionality to plan your purchasing campaign. For instance:
last month, a pet store sold 100 guinea pigs. The store must plan purchasing
volumes for the next month. One of the most widely used ways to do this is  to
apply an adjustment factor to past sales periods. For instance, the adjustment factor
(demand increase factor) is  1.5. Therefore, it  is  reasonable to plan to purchase 150
guinea pigs for the next month. However, if we analyze what customers buy after
they buy such a  pet, other conclusions can be drawn. By using data analysis and
forecasting features one can see that pet food, litter, hay, and other "accessories"
should be purchased.
It should be noted that this chapter mostly reviews 1C:Enterprise mechanisms and
only briefly mentions ways to use the information obtained through simple examples.
2-712 1C:Enterprise 8.3. Developer Guide

14.1. OVERVIEW
A general overview of the data analysis and forecasting mechanism can be
presented as follows:

Fig. 279.  Interaction of the data analysis mechanism elements

This is  the mechanism to be used to work with infobase data and data from other
sources, preloaded into a  value table or a  spreadsheet document.
Apply one of the types of analysis to the source data to obtain the analysis results.
The  analysis results are a  given data behavior model; it  can be displayed in  the
final document or stored for further use.
The analysis results can be used to create a  forecast model to forecast new data
behavior, in  line with the existing model.
For instance, one can analyze which goods are purchased together (on a single
invoice) and store the analysis-based forecasting model in the database. In the
future, when an invoice is  created, a  previously stored forecasting model can be
retrieved from the database. One can input new data from an invoice and receive
a  forecast as an output, i.e. a  list of goods that the next customer will probably buy
(with a  certain degree of likelihood) if these goods are offered at a  store.
Chapter 14. Data Analysis and Forecasting 2-713

14.1.1. Main Mechanism Objects

Interaction between the main objects of the data analysis and forecasting mecha-
nism can be shown as follows:

Fig. 280.  Interconnection of main objects

Data analysis is an object responsible for data analysis. A data source is set
for this object, different parameters and source data are specified. This object
results in  a data analysis result, while each type of analysis has its own object
for working with the analysis results.
„„ DataAnalysisSummaryStatisticsResult
„„ DataAnalysisAssociationRulesResult
„„ DataAnalysisSequentialPatternsResult
„„ DataAnalysisDecisionTreeResult
„„ DataAnalysisClusterizationResult
Setting data analysis columns – a collection of data analysis input columns.
A data type, column role, and additional settings depending on the type of analysis
performed are specified for each column. Data analysis parameters – a set of
parameters to be used in  data analysis. The  range of parameters depends on the
selected type of analysis. For instance, the number of clusters to divide source
objects into, a  measurement of distance between objects, etc. should be specified
for cluster analysis.
Data source – source data for the analysis. A query result, spreadsheet document
cell area, or a  value table may function as a  data source.
2-714 1C:Enterprise 8.3. Developer Guide

Data analysis result – a  special object that contains information on the result of
analysis. Each type of analysis provides its own result. For instance, Decision tree
data analysis result will be an object of type DataAnalysisDecisionTreeResult.
In  the future, the result may be output to a  spreadsheet document with the help of
the data analysis result builder. It  can be output through a  programmatic access
to its content, and can also be used to create a  forecast model. Any data analysis
result may be stored for further use.
Forecast model – is  a special object to execute forecasting on the basis of input
data (a forecast selection, selection columns settings, result settings, and analysis
result). The  type of the forecast model depends on the type of data analysis result.
For instance, a model created for Association rules, will have type Predic-
tionModelAssociationRules. This  model will output forecasts of the following
type: since this customer has purchased a  specified set of goods, he or she will buy
another set of goods with a  certain probability. The  forecasting data source is an
input to the forecasting model. The  result is  a value table that contains forecast
values.
Input column setup – is  a set of special objects that show correspondence between
forecasting model columns and forecast selection columns. For instance, a  forecast
model column named Goods may match a  Nomenclature selection column.
Result columns setup – controls which columns will be included in  the resulting
forecast model table. For instance, a nomenclature item that the customer will
probably buy and the probability of purchase can be output as an association rules
result.
Result columns – is  a table of results that includes columns specified in  output
column settings and contains forecast data. The  specific content depends on the
type of analysis.

14.1.2. Types of Data Analysis

The data analysis and forecasting mechanism implements a number of data
analysis types:
„„ Summary statistics
„„ Association rules
„„ Sequential patterns
„„ Cluster analysis
„„ Decision tree

14.1.2.1. Summary statistics

The Summary statistics analysis type is  a mechanism for gathering general infor-
mation on the data from the obtained data source. This  type of analysis is  used to
pre-analyze the information.
Chapter 14. Data Analysis and Forecasting 2-715

This analysis shows a  number of categorical and contiguous fields characteristics.

When a report is output to a spreadsheet document, pie charts to display the
contents of the fields are compiled.

14.1.2.2. Association rules

This type of analysis searches for the groups of objects or characteristic values that
usually go together, and searches for association rules. Association rules can be
used to determine what goods and services are usually purchased together.
This type of analysis can be used with hierarchical data to find association rules for
specific goods and groups of goods. An important feature of this type of analysis
is  its capability to work with both object based data sources (where each column
contains a  certain characteristic of an object) and with event based sources where
object characteristics are placed together in  a single column.

14.1.2.3. Sequential patterns

The Sequential patterns analysis type helps reveal event sequences in a data
source. For instance, this may be a chain of goods or services that are usually
bought in  sequence.
This type of analysis is useful for searching through a hierarchy and tracking
sequential specific and sequential parent groups.

14.1.2.4. Cluster analysis

A cluster analysis is  a way to divide a  source set of objects being analyzed into
groups of objects, so that each object more closely resembles objects in  the same
group rather than the objects of other groups. In the future, when the received
groups (called clusters) are analyzed, one can define what characterizes a  specific
group, and make decisions on different methods used for working with objects from
different groups. For instance, you can use cluster analysis to divide customers into
groups and use different customer relationship strategies.
Use cluster analysis parameters to set up an algorithm in  order to split and dynami-
cally change sets of characteristics that are taken into account in  analyses, and to
specify weighting factors for them.
Clusterization results may be output as a  dendrogram, a  special type of diagram
for graphically representing cluster analysis results.

14.1.2.5. Decision tree

The Decision tree analysis type is  a way to create a  hierarchical structure of clas-
sifying rules presented as a  tree.
To build a  decision tree, select a  target attribute to base the classifier on, as well as
a  number of output attributes to be used to create the rules. A target attribute may
2-716 1C:Enterprise 8.3. Developer Guide

contain information on whether a  customer started using another service provider,

whether the transaction has been successful and the work has been completed
successfully, etc. Possible input attributes are as follows: age of an employee, his
or her period of employment, the material wealth of the customer, the number of
employees in  the company, etc.
Analysis results are presented as a tree, each node of which contains a condi-
tion. In order to decide which class a certain new object should be referred to,
it is necessary to answer questions in the nodes and complete a chain of steps
from the root to a  leaf of the tree. A positive answer takes the user to the next
sub-node, while a  negative answer takes the user to a  neighboring node.
A set of analysis parameters can be used to control the accuracy of the resulting
tree.

14.1.3. Forecasting Models

Forecasting models created by the mechanism are special objects generated from
the data analysis results. In  future they can be used to automatically forecast new
data.
For instance, an association rules forecasting model created when the customer
purchases were analyzed can be used to work with a  customer at a  store, so as
to offer the goods that he or she will probably buy in  conjunction with the main
purchase.

14.2. THE SUMMARY STATISTICS ANALYSIS TYPE

The Summary statistics analysis type can be used for preliminary data analysis
(before any other type of analysis is  completed), etc.
A query result, a  value table, or a  cell area of a  spreadsheet document can be used
as a  source of data for analysis.
Source data (from the point of view of the analysis taken) may be contiguous or
discrete. Contiguous types may be Number and Date. Other types are discrete.
Different information can be obtained for the columns of different types.
Discrete data:
„„ Number of values – is  the number of values in  a data source column (NULL
is  not considered a  value).
„„ Number of unique values (except for repeated values).
„„ Mode – is the most frequent value in the data source. If the data contains
several values that occur with the same frequency, the mode is  the first such
value found.
„„ Frequency is  the number of occurrences of a  value in  the data selection.
„„ Relative frequency is  defined as a  relation between the number of occurrences
of the value to the total number of values.
Chapter 14. Data Analysis and Forecasting 2-717

„„ Accumulated frequency is the total of the value frequency and the total of
frequencies of previous data selection values.
„„ Accumulated relative frequency is  the total of the accumulated value frequency
and the total of relative frequencies of previous values.
Contiguous data:
„„ Number of values.
„„ Minimum value.
„„ Maximum value.
„„ Average.
„„ Range is  the difference between the maximum and the minimum values.
„„ Standard deviation (root-mean-square deviation).
„„ Median is  a value in  the middle of the selection.
It should be noted that if several fields of different types are analyzed simultane-
ously, they are analyzed independently (without any mutual correlation).
Let us review the characteristics mentioned in  the example.
Data selection (source of analysis) looks as follows:
Nomenclature item Quantity Nomenclature item Quantity
Folding dining table 1 Folding dinner table 1
Round stool 2 Square stool 3
"Coziness" sofa 1 "COMFORT" armchair 2
"Jeans" sofa 1 "COMFORT" armchair 2
"Jeans" armchair 2 "Wardrobe" closet 1
Kitchen table 0.9x1.7 1 Folding dinner table 1
"COMFORT" sofa 1 Square stool 2
Kitchen table 0.9x1.7 1 Dining table 1
"Summer" chair 4 "Summer" chair 2
"COMFORT" sofa 1 Round stool 2

The following characteristics will be calculated, based on data analysis for the
Count field (Contiguous analysis data type):
Characteristic Value
Values 20
Minimum 1
Maximum 4
Average 1.6
Range 3
Standard deviation 0.8208
Median 1
2-718 1C:Enterprise 8.3. Developer Guide

The following characteristics will be obtained for the Nomenclature field:

Characteristic Value
Number of values 20
Number of unique values 12
Mode Folding dining table

A frequency table for the nomenclature values will look as follows:

Fig. 281.  Frequency table

The relative frequency is  shown in  the diagram below.

Fig. 282.  Frequency diagram

Chapter 14. Data Analysis and Forecasting 2-719

To perform this analysis, use a  code fragment similar to the one below:

&OnClient
Procedure Summary Statistics(Command)
Result = AnalysisSummaryStatistics();
EndProcedure

&OnServerWithoutContext
Function AnalysisSummaryStatistics();
Analysis = New DataAnalysis;
Analysis.AnalysisType = Type("DataAnalysisSummaryStatistics");

Query = New Query;

Query.Text = "
|SELECT
|Sales.Nomenclature,
|Sales.Count
|FROM
|AccumulationRegister.Sales AS Sales";

Analysis.DataSource = Query.Execute();
AnalysisResult = Analysis.Execute();

Builder = New DataAnalysisReportBuilder();

Builder.Template = Undefined;
Builder.AnalysisType = Type("DataAnalysisSummaryStatistics");

Spreadsheet = New SpreadsheetDocument;

Builder.Output(AnalysisResult, Spreadsheet);
Return Spreadsheet;
EndFunction

Data analysis operations are performed in  a server’s out-of-context function that
returns a  spreadsheet document containing the analysis results to the client. First of
all, the DataAnalysis object is  created. Next, the type of analysis to be completed
is selected.
A query is  then defined based on the text. The  query result is  set as the source of
the analysis data. The  analysis itself is  completed when the Execute() method
of the DataAnalysis object is executed. The analysis itself has no tools for
visualizing analysis results. The DataAnalysisReportBuilder object is used
for this purpose. When this object is  created, the type of analysis to be conducted
is  re-specified. Then, the result of the received analysis is  transferred as the first
parameter of the Put() method, and the SpreadsheetDocument object created
earlier is  transferred as the second parameter.
At the conclusion of the algorithm, the spreadsheet document containing the
analysis result is  returned to the client’s Result data processor attribute with type
SpreadsheetDocument.
As a  result, data similar to that analyzed above will be obtained.
2-720 1C:Enterprise 8.3. Developer Guide

14.3. THE ASSOCIATION RULES ANALYSIS TYPE

As has already been mentioned, this analysis type searches for combinations of
objects or characteristic values that frequently go together. This  is  a way for deter-
mining groups for goods that are usually purchased together, so as to identify the most
attractive information sources (optimizing costs in  respect of these sources), etc.
A schematic view of the Association rules analysis type is  as follows:

Fig. 283.  The  association rules analysis type: execution diagram

A query result, spreadsheet document cell area, or a  value table may function as
a  data source. From the point of view of this type of analysis, source columns may
be divided as follows:
„„ NotUsed – ignored by the analysis.
„„ Object – data from this column is  used as objects (or events) of the executed
analysis. Based on the values of this column, values of another column (Item)
refer to one associated group.
„„ Item – data from this column is used to obtain stable groups of values and
create association rules.
Chapter 14. Data Analysis and Forecasting 2-721

The following analysis parameters impact the analysis result, together with column
types settings:
„„ MinSupport – determines the minimum percentage of cases when a certain
combination of elements should occur. The groups where this value is less
than the specified value are not included into the analysis result.
„„ MinConfidence – shows the minimum percentage of cases when the rule
is followed.
„„ MinImportance – groups with a  value less than the specified value are not
included into the analysis result.
„„ PruneRulesType – one of the variants of the AssociationRulesPruneType
system enumeration:
○○ Redundant – redundant rules are pruned.
○○ Covered – the rules covered by other rules are pruned.
The result of analysis is  as follows:
„„ Information on the data (number of objects, number of items, average number of
items in  an object, number of groups found, number of association rules found).
„„ Groups of items found – the contents of the group, the number of cases, and the
percentage of cases where this group occurs is  specified.
„„ Association rules detected – a source set of elements, consequent (structure
of elements), percentage of cases, confidence, and importance of the rule are
specified.
Let us review the peculiarities of this type of analysis with the following data selec-
tion (we will try to determine a  standard set of goods usually purchased together):
Recorder Nomenclature
Sales invoice No. 000000001 Folding dining table
Round stool
Sales invoice No. 000000002 COMFORT sofa
Sales invoice No. 000000003 Jeans sofa
Jeans armchair
Sales invoice No. 000000005 Kitchen table 0.9x1.7
COMFORT sofa
Sales invoice No. 000000004 Kitchen table 0.9x1.7
"Summer" chair
COMFORT sofa
Sales invoice No. 000000006 Folding dinner table
Square stool
Sales invoice No. 000000007 COMFORT armchair
Sales invoice No. 000000008 COMFORT armchair
Sales invoice No. 000000009 Wardrobe closet
Sales invoice No. 000000010 Folding dining table
Square stool
Dinner table
Sales invoice No. 000000011 "Summer" chair
Round stool
2-722 1C:Enterprise 8.3. Developer Guide

An attribute through which data is  related to one group is  called the recorder value
(a nomenclature specified in one document is considered to be simultaneously
purchased). That means that the Recorder will be an object of analysis, and the
Nomenclature will be an item of analysis.
The following code fragment will be used for analysis:
&OnClient
Procedure AssociationRules(Command)
Result = AnalysisAssociationRules();
EndProcedure

&OnServerWithoutContext
Function AnalysisAssociationRules();
Analysis = New DataAnalysis;
Analysis.AnalysisType = Type("DataAnalysisAssociationRules");

Query = New Query;

Query.Text = "
|SELECT
|Sales.Recorder,
|Sales.Nomenclature
|FROM
|AccumulationRegister.Sales AS Sales";

Analysis.DataSource = Query.Execute();

// String used as an example,

// a  default column type value.
Analysis.ColumnSetting.Nomenclature.ColumnType = DataAnalysisColumnTypeAssociationRules.Item;

// String used as an example,

// a  default prune type value.
Analysis.Parameters.RulesPruneType.Value = AssociationRulesPruneType.Redundant;

AnalysisResult = Analysis.Execute();

Builder = New DataAnalysisReportBuilder();

Builder.Template = Undefined;
Builder.AnalysisType = Type("DataAnalysisAssociationRules");

Spreadsheet = New SpreadsheetDocument;

Builder.Output(AnalysisResult, Spreadsheet);

Return Spreadsheet;
EndFunction
Chapter 14. Data Analysis and Forecasting 2-723

The analysis results will look as follows:

Fig. 284.  Association rules analysis result

The selection uses data from 11 documents (a reference in  the Recorder field), the
number of different nomenclature items is  twelve:
Nomenclature
Folding dining table
Round stool
"Coziness" sofa
Jeans sofa
Jeans armchair
Kitchen table 0.9x1.7
"COMFORT" sofa
"Summer" chair
Square stool
"COMFORT" armchair
Wardrobe closet
Dining table

The following group of goods has been found:

Fig. 285.  Group of goods found

The whole group occurs in  the document in  only two cases out of eleven (which
is shown in columns Number of cases and Percentage of cases).
The following association rules have been received:

Fig. 286.  Association rules

2-724 1C:Enterprise 8.3. Developer Guide

Let us review the second one. Position Square stool occurred together with position
Folding dining table in  two cases out of eleven in  this document. Based on this, the
support has been calculated: (2/11*100 = 18.18%).
Confidence has been calculated as follows: both nomenclature items have been
purchased in  two cases, while position Folding dining table occurred 3 times. Based
on this, confidence is  equal to 2/3*100 = 66.67%.
Importance is  evaluated as a  ratio between the rule’s confidence and the support
of Square stool position in the goods purchased. This position occurs in two
documents out of eleven (18.18%). Importance is  equal to 66.67%/18.18% = 3.67.

14.3.1. Rules Prune Types

Let us review an important parameter of this analysis type, i.e. PruneRulesType.
System enumeration AssociationRulesPruneType contains the following prune
values:
„„ Covered
„„ Redundant
Before proceeding to review prune variants, we will examine a  number of general
principles applied to association rules.
Any rule contains an antecedent and a  consequent. For example:
„„ Antecedent: If Product 1 has been purchased.
„„ Consequent: Then Product 2 will also be purchased.
Please bear in mind that the consequent has a certain degree of confidence.
In prune rules, probability characteristics may be taken into account or may be
ignored (the content of the rule is  the only thing that really matters).

14.3.1.1. Covered rules pruning

Let us review the Covered pruning option.
A rule may be covered by an antecedent or by a  consequent. For example:
„„ Rule 1. If products 1 and 3 have been purchased, then product 2 will also be
purchased.
„„ Rule 2. If product 1 has been purchased, then product 2 will also be purchased.
In this case rule 1 is considered covered, as the antecedent of the first rule
is  redundant in  respect of the antecedent of the second rule.
An example of coverage by a  consequent:
„„ Rule 1. If product 1 has been purchased, then products 2 and 3 will also be
purchased.
„„ Rule 2. If product 1 has been purchased, then product 3 will also be purchased.
Rule 2 is  covered by a  consequent as the consequent of rule 1 is  broader.
Chapter 14. Data Analysis and Forecasting 2-725

14.3.1.2. Pruning redundant rules

Coverage does not take into account the probability characteristics of the rules.
They are only considered if the Redundant pruning type is  used.
A rule is  considered redundant by antecedent if it  is  covered by an antecedent and
its confidence is  equal to the confidence of the covering rule. For example:
„„ Rule 1. If products 1 and 3 have been purchased, then product 2 will be
purchased with 75% confidence.
„„ Rule 2. If product 1 has been purchased, then product 2 will be purchased with
75% confidence.
Rule 1 is  redundant towards rule 2 (it contains an additional condition that does not
"disturb" the confidence characteristics of the rule).
Rule 1 is  considered redundant by consequent if the number of cases of this rule
is  equal to the number of cases of the covering rule.
„„ Rule 1. If product 1 has been purchased, then products 2 and 3 will be
purchased in  three cases.
„„ Rule 2. If product 1 has been purchased, then product 3 will be purchased
in  three cases.
Rule 2 is  redundant towards rule 1, as it  contains a  simpler consequent with the
same confidence characteristics.

14.4. THE SEQUENTIAL PATTERNS ANALYSIS TYPE

This type of analysis reveals sequences of events (sequence templates). It  can be
used when a  consequence of events over a  period is  one of the important indi-
cators being analyzed. For instance, a  pattern of goods purchased in  a sequence
within a  certain period of time etc. may be identified.
A schema of the Sequential patterns analysis procedure is  shown on fig. 287.
A query result, spreadsheet document cell area, or a  value table may function as
a  data source. From the point of view of this type of analysis, source columns may
be divided into the following:
„„ NotUsed – ignored in  the analysis.
„„ Sequence – data from this column is used in the analysis as an object of
a  sequence of events. The  analysis uses a  value in  this column to associate
data with a  certain sequence of events.
„„ Item – data from this column is  used as sequence elements.
„„ Time – this column is  used to determine the time of event. This  is  a manda-
tory column for this type of analysis.
2-726 1C:Enterprise 8.3. Developer Guide

Fig. 287.  A sequential patterns analysis execution diagram

The following analysis parameters impact the result of the analysis together with
column type settings:
„„ MinSupport – the minimum percentage of sequences where the sequence
template is  observed.
„„ MinInterval – an attribute used to set the minimum sequence interval (an
interval measurement unit, i.e. repetition, shall be defined).
„„ MaxInterval – an attribute used to set the maximum sequence interval (an
interval measurement unit, i.e. repetition, shall be defined).
„„ TimeSliceWindow – an attribute setting the time slice window (a time slice
window measurement unit, i.e. its repetition, shall be defined).
„„ MinLength – the minimum length of sequences searched.
„„ FindInHierarchy – a  flag of hierarchy search (covers columns of the Item
type).
Chapter 14. Data Analysis and Forecasting 2-727

A number of properties use DataAnalysisTimeIntervalUnitType. This  system

enumeration contains the following values:
Second
Minute CurrentMinute
Hour CurrentHour
Day CurrentDay
Week CurrentWeek
TenDays CurrentTenDays
Month CurrentMonth
Quarter CurrentQuarter
HalfYear CurrentHalfYear
Year CurrentYear

The sequence templates found are the main result of the analysis. These templates
contain the following information:
„„ contents of a  sequence template
„„ number of cases when this sequence has been observed
„„ maximum intervals between events (if there are only 2 events, there is one
interval)
„„ minimum intervals between events (if there are only 2 events, there is one
interval)
„„ percentage of cases when the sequence has been executed
„„ average intervals between events (if there are only 2 events, there is one
interval)
Let us review how this type of analysis is  executed using the following data selec-
tion:
Contractor First purchase Second purchase Third purchase Interval
V.I. Bondarev Folding dining table COMFORT sofa COMFORT 25 days, 31 days
Round stool armchair
I.P. Ivanov Jeans sofa
Jeans armchair
B.S. Petrov Kitchen table 0.9x1.7 COMFORT 43 days
"Summer" chair armchair
COMFORT sofa
G.O. Sidorov Folding dining table
Square stool
V.K. Stepanov Folding dining table
Square stool
Dining table
D.E. Fedorov Kitchen table 0.9x1.7 Wardrobe closet "Summer" chair 58 days, 29 days
Comfort sofa Round stool
2-728 1C:Enterprise 8.3. Developer Guide

Data from the Contractor column will define affiliation to a certain chain of
events, i.e. they define the sequence of analysis. The  Nomenclature is  an element
of the sequence received.
To perform this analysis, use a  code fragment similar to the one below:
&OnClient
Procedure SequentialPatterns(Command)
Result = AnalysisSequentialPatterns();
EndProcedure

&OnServerWithoutContext
Function AnalysisSequentialPatterns();
Analysis = New DataAnalysis;
Analysis.AnalysisType = Type("DataAnalysisSequentialPatterns");

Query = New Query;

Query.Text = "
|SELECT
|Sales.Contractor,
|Sales.Nomenclature,
|Sales.Period
|FROM
|AccumulationRegister.Sales AS Sales";

Analysis.DataSource = Query.Execute();

Analysis.ColumnsSetting.Period.ColumnType = DataAnalysisColumnTypeSequentialPatterns.Time;
AnalysisResult = Analysis.Execute();

Builder = New DataAnalysisReportBuilder();

Builder.Template = Undefined;
Builder.AnalysisType = Type("DataAnalysisSequentialPatterns");

Spreadsheet = New SpreadsheetDocument;

Builder.Output(AnalysisResult, Spreadsheet);
Return Spreadsheet;
EndFunction

The Period field is  defined as Time directly from the code (it is  not analytically).
Analysis parameters set by default:

Fig. 288.  Analysis parameters

Chapter 14. Data Analysis and Forecasting 2-729

The following data has been obtained in  the analysis:

Fig. 289.  General analysis data

The number of elements is  12. This  is  also the number of nomenclature positions
that occur in  the data selection.
Two sequences have been found:

Fig. 290.  Sequences found

The first sequence occurs in two cases out of five. Therefore, support is 40%.
Since the sequence depth is  2, each of these intervals contains one value.

14.5. THE DECISION TREE ANALYSIS TYPE

This type of analysis can be used to obtain a  cause-and-effect hierarchy of condi-
tions that facilitates making decisions. For instance, you can obtain a  condition
tree that will (within a  certain degree of probability) help understand the reasons
behind the termination of agreements with customers and define the conditions
determining the agreement to be signed. Company managers may be profile-
oriented so as to serve different groups of customers, etc.
A schema of the Decision tree analysis procedure is  shown on fig. 291.
From the point of view of this type of analysis, source columns may be divided into
the following:
„„ NotUsed
„„ Input
„„ Predictable
Analysis parameters used:
„„ MinCaseCount – minimum number of items in  a node
„„ MaxDepth – maximum depth of the tree
„„ SimplificationType – simplification type of the decision tree
The result of the analysis is  as follows:
„„ decision tree
„„ classification errors
2-730 1C:Enterprise 8.3. Developer Guide

Fig. 291.  Decision tree analysis execution diagram

Let us review how this type of analysis is  executed with the following data selec-
tion:
Number Number Company Agreement Type Status
Contractor
of retail spots of cars age date of agreement of relations
ZAO Igor 1 0 Less than Less than Dealer Infringement
a  year a  year of contract
ZAO TorgMebel 15 4 From three Less than Distributor Terminated
to ten a  year by contractor
years
ZAO TorgMebel 1 10 From three From one to Distributor Terminated
to ten three years by contractor
years
ICP Dubrava 1 1 From one Less than Dealer Terminated
to three a  year by contractor
years
Store 15 1 1 Over 10 From three to L o n g - t e r m Not termi-
years ten years partner nated
OOO Gross 3 2 Less than Less than L o n g - t e r m Not termi-
a  year a  year partner nated
Chapter 14. Data Analysis and Forecasting 2-731

Number Number Company Agreement Type Status

Contractor
of retail spots of cars age date of agreement of relations
OOO Intaris 7 3 From three From one to L o n g - t e r m T e r m i n a t e d
to ten three years partner by contractor
years
OOO TorgTrest 2 2 Over 10 From three to L o n g - t e r m Not termi-
years ten years partner nated
PBOUL Kuro- 0 1 Less than Less than Dealer Not termi-
chkin a  year a  year nated

To perform this analysis, use a  code fragment similar to the one below:
&OnClient
Procedure DecisionTree (Command)
Result = AnalysisDecisionTree();
EndProcedure

&OnServerWithoutContext
Function AnalysisDecisionTree();
Analysis = New DataAnalysis;
Analysis.AnalysisType = Type("DataAnalysisDecisionTree");

Group = Catalogs.Contractors.FindByDescription("Legal entities");

Query = New Query;
Query.Text = "
|SELECT
|Contractors.Reference,
|Contractors.RetailCount,
|Contractors.VehicleCount,
|Contractors.OrganizationPeriodOfWork,
|Contractors.AgreementDate,
|Contractors.ContractKind,
|Contractors.TerminationOfRelations,
|FROM
|Catalog.Contractors AS Contractors
|WHERE
|(NOT Contractors.IsFolder AND Contractors.Parent = &Parent)";

Query.SetParameter("Parent", Group);

Analysis.DataSource = Query.Execute();

Analysis.Parameters.SimplificationType.Value = DecisionTreeSimplificationType.DontSiplify;
AnalysisResult = Analysis.Execute();

Builder = New DataAnalysisReportBuilder();

Builder.Template = Undefined;
Builder.AnalysisType = Type("DataAnalysisDecisionTree");

Spreadsheet = New SpreadsheetDocument;

Builder.Output(AnalysisResult, Spreadsheet);
Return Spreadsheet;
EndFunction
2-732 1C:Enterprise 8.3. Developer Guide

The following decision tree is  the result of the analysis:

Fig. 292.  Decision tree

This tree can be presented as the following schema:

Fig. 293.  Schema view of the decision tree

Chapter 14. Data Analysis and Forecasting 2-733

Classification errors appear when the received rules do not match the reality (source
data selection):

Fig. 294.  Classification errors

Based on the data specified, there are no errors in  the received classification, i.e.
data in  the actual selection matches classification data.
An example above is  based on the DontSimplify value of the Simplification-
Type analysis parameter. This parameter value is set programmatically in the
example above. If a  Simplify value is  set for the parameter, the decision tree will
look as follows:

Fig. 295.  Decision tree

Tree simplification means that tree nodes are turned into leaves (redundant
branching is  pruned) using specific rules (or formulas, see below).
The following should be taken into consideration in deciding whether a node
should be turned into a  leaf:
„„ Errors – number of errors in  a node
„„ ChildErrors – number of errors in  child nodes
„„ Leaves – number of leaves in  a node
„„ Cases – number of cases
2-734 1C:Enterprise 8.3. Developer Guide

The following condition must be met to turn a  node into a  leaf:

In this example, the condition is  satisfied for nodes Company age (0.5 < 1).

Fig. 296.  Classification errors

For instance, in one case the real sample contained the value Terminated
by contractor, while according to classification it should have been Not
terminated, etc.

14.6. THE СLUSTERIZATION ANALYSIS TYPE

A cluster analysis is  a mathematical multidimensional analysis that uses multiple
indicators that characterize a  number of objects so as to group them in  clusters
so that the objects of one cluster are more homogeneous, are similar to each other
when compared to objects of other clusters.
This analysis is based on calculating the distance between objects. Based on
distances between objects, they are grouped into clusters. There are several different
ways to measure the distance (different metrics can be used). The following
metrics are supported
„„ Euclidean
„„ Squared euclidean
„„ City block
„„ Maximum
Chapter 14. Data Analysis and Forecasting 2-735

When a distance between objects is measured, one of several algorithms for

distributing objects among clusters can be used. The following clusterization
methods are supported:
„„ Nearest neighbor
„„ Furthest neighbor
„„ K-means
„„ Centroid
The cluster analysis mechanism can be schematically presented as follows:

Fig. 297.  Cluster analysis execution diagram

A data source is  provided as input to the DataAnalysis object. A query result,
spreadsheet document, cell area, or a  value table may function as a  data source.
Source columns are defined as input or not used. It  should be noted that all column
values are included in DataAnalysisColumnTypeClusterization system
enumeration. This  enumeration includes further values (both not used and input),
but these other values are used to build forecasts.
2-736 1C:Enterprise 8.3. Developer Guide

Analysis is  performed in  accordance with the analysis parameters set.
Let us use the following code fragment as an example to illustrate how cluster
analysis can be performed:

&OnClient
Procedure ClusterAnalysis (Command)
Result = AnalysisClusterization();
EndProcedure

&OnServerWithoutContext
Function AnalysisClusterization();
Analysis = New DataAnalysis;
Analysis.AnalysisType = Type("DataAnalysisClusterization");

Group = Catalogs.Contractors.FindByDescription("Legal entities");

Query = New Query;
Query.Text = "
|SELECT
|Contractors.Reference,
|Contractors.RetailCount,
|Contractors.VehicleCount,
|Contractors.OrganizationPeriodOfWork,
|Contractors.AgreementDate,
|Contractors.ContractKind,
|Contractors.TerminationOfRelations,
|FROM
|Catalog.Contractors AS Contractors
|WHERE
|(NOT Contractors.IsFolder AND Contractors.Parent = &Parent)";

Query.SetParameter("Parent", Group);

Analysis.DataSource = Query.Execute();

// Metrics selection.
Analysis.Parameters.DistanceMetric.Value =
DataAnalysisDistanceMetricType.SquaredEuclidean;

// Clusterization method selection.

Analysis.Parameters.ClusterizationMethod.Value = ClusterizationMethod.KMean;

AnalysisResult = Analysis.Execute();

Builder = New DataAnalysisReportBuilder();

Builder.Template = Undefined;
Builder.AnalysisType = Type("DataAnalysisClusterization");

Spreadsheet = New SpreadsheetDocument;

Builder.Output(AnalysisResult, Spreadsheet);

Return Spreadsheet;
EndFunction
Chapter 14. Data Analysis and Forecasting 2-737

A query is  processed for catalog Contractors. According to the conditions of the
query, only detailed catalog entries from the Legal entities group are selected.
Executing this code will define the following values as initial analysis settings
(some of them are set explicitly, others are set by default).

Fig. 298.  Analysis parameters

The content of these columns has been defined on the basis of the query selection
fields. By default, they are defined with an equal weighting. The  Contiguous data
type has been defined for the Number and Date types, with the Discrete data type
for all other types. If column parameters need to be changed, this can be done as
follows:
Analysis.ColumnsSetting.VehicleCount.AdditionalParameters.Weight = 2;

Weighting has been increased for column VehicleCount in  this string.
The data selection which will be analyzed is  as follows:
Number Number Company Agreement Type Status
Contractor
of retail spots of cars age date of agreement of relations
ZAO Igor 1 0 Less than Less than Dealer Infringement
a  year a  year of contract
ZAO TorgMebel 15 4 From three Less than Distributor Terminated
to ten a  year by contractor
years
ZAO TorgMebel 1 10 From three From one to Distributor Terminated
to ten three years by contractor
years
ICP Dubrava 1 1 From one Less than Dealer Terminated
to three a  year by contractor
years
Store 15 1 1 Over 10 From three to L o n g - t e r m Not termi-
years ten years partner nated
OOO Gross 3 2 Less than Less than L o n g - t e r m Not termi-
a  year a  year partner nated
2-738 1C:Enterprise 8.3. Developer Guide

Number Number Company Agreement Type Status

Contractor
of retail spots of cars age date of agreement of relations
OOO Intaris 7 3 From three From one to L o n g - t e r m Terminated
to ten three years partner by contractor
years
OOO TorgTrest 2 2 Over 10 From three to L o n g - t e r m Not termi-
years ten years partner nated
PBOUL Kuro- 0 1 Less than Less than Dealer Not termi-
chkin a  year a  year nated

The analysis result will be as follows:

Fig. 299.  Cluster analysis result

Note that the analysis outputs data concerning the clusters found (their number,
centers, and the distance between them). No data about which objects (in our
case, contractors) are members of what clusters is obtained from the analysis.
Chapter 14. Data Analysis and Forecasting 2-739

This  behavior can be observed if the analysis parameters are not set explicitly (the
TableFillType parameter, in  particular).
To see the object distribution among the clusters as a  result of the analysis, define
the following code string before the analysis (but after defining its type):
Analysis.Parameters.TableFillType.Value = DataAnalysisResultTableFillType.UsedFields;

14.6.1. Metrics used

First of all, we note the following: even though input columns in the example
above were of a  contiguous type (a notion of distance is  obvious for this type),
discrete type columns (references to catalogs, enumeration values, etc.) can be used
in  the analysis.
We now review the metrics that can be used in  a cluster analysis.

14.6.1.1. Euclidean
This metric calculates the distance between two objects using the following
formula:

Where:
„„ Xi, Yi – attribute values of two objects (the distance between which we need to
determine)
„„ Wi – weighting factor of an attribute (set in  the analysis column)
„„ i – attribute number, from 1 to n
„„ n – number of attributes
For instance, objects are characterized by a  property that is  9 for one object and 5
for another one. The  weighting factor of this attribute is  1. The  distance between
the objects is  as follows:

14.6.1.2. Squared euclidean

This metric calculates the distance between two objects using the following formula:

Where:
„„ Xi, Yi – attribute values of two objects (the distance between which we need to
determine)
2-740 1C:Enterprise 8.3. Developer Guide

„„ Wi – weighting factor of an attribute (set in  the analysis column)

„„ i – attribute number, from 1 to n
„„ n – number of attributes
For instance, objects are characterized by a  property that is  5 for one object and 3
for another one. The  weighting factor of this attribute is  2. The  distance between
the objects is  as follows:

14.6.1.3. City block

This metric calculates the distance between two objects using the following
formula:

Where:
„„ Xi, Yi – attribute values of two objects (the distance between which we need to
determine);
„„ Wi – weighting factor of an attribute (set in  the analysis column);
„„ i – attribute number, from 1 to n;
„„ n – number of attributes.
For instance, objects are characterized by two attributes that have values of 3 and 5,
7 and 3. The  weighting factor of the first one is  2, of the second – 1:

Fig. 300.  Object characteristics

Chapter 14. Data Analysis and Forecasting 2-741

14.6.1.4. Maximum
This metric calculates the distance between two objects using the following
formula:

Where:
„„ Xi, Yi – attribute values of two objects (the distance between which we need to
determine)
„„ Wi – weighting factor of an attribute (set in  the analysis column)
„„ i – attribute number, from 1 to n
„„ n – number of attributes
For instance, objects are characterized by two attributes that have values of 3 and 5,
7 and 3. The  weighting factor of the first one is  2, of the second – 1 (see fig. 300):

14.6.2. Clusterization methods

A variant of the clusterization method determines the principles that will be used
to affiliate an object to a  certain group, and which algorithm will be used to form
clusters.
Any clusterization algorithm is  aimed at the following:
„„ Minimizing variability inside clusters,
„„ Maximizing variability between clusters.
Differences between these methods will be examined with the objects shown
in  figure (see fig. 301).
Let us imagine that objects are distributed into two groups. The  first one includes
objects 1, 2, and 3. The  second group consists of objects 4, 5, and 6.

Fig. 301.  Groups of objects

2-742 1C:Enterprise 8.3. Developer Guide

14.6.2.1. Nearest neighbor

A clusterization method that connects an object to the group with a minimal
distance to the nearest object.
In this example, object 7 will belong to a  group that includes object 4. The  closest
objects of two groups are objects 4 and 3. The  distance to object 4 is  minimal.

14.6.2.2. Furthest neighbor

A clusterization method that connects an object to the group with a minimal
distance to the furthest object.
In this example, object 7 will belong to a  group that includes object 5. The  furthest
objects of two groups are objects 1 and 5. The  distance to object 5 is  less great.

14.6.2.3. Centroid
A clusterization method that connects an object to the group with a minimum
distance to the centroid.

Fig. 302.  Groups of objects

The example shown in  the picture adds object 7 to a  group that contains objects 4,
5, and 6. The  distance to the centroid (an imaginary object with average attribute
values) is  minimal.

14.6.2.4. K-means
This method selects the objects that come first in  the selection. They are considered
to be centers of clusters. Then, the following object is  selected, and is  affiliated to
one or another cluster based on its distance to the centers of clusters. The  center of
the cluster to which an object has been added is  recalculated.
Chapter 14. Data Analysis and Forecasting 2-743

The procedure continues until all objects have been analyzed. New selection
of objects is made afterwards (starting from the first one). The procedure
is  repeated until cluster centers change.

Fig. 303.  Sample objects layout

For instance, objects 1 and 2 have been arbitrarily selected as cluster centers. Object
3 is  added to the cluster with a  center in  object 1. The  center of the first cluster
is recalculated (it is between object 1 and 3). Object 4 is added to the second
cluster (its center is  also recalculated).
After all objects under analysis have been processed, objects 1 and 3 relate to
cluster 1, while the second cluster includes all other objects (with a  center suppos-
edly in  the center of a  triangle formed by objects 4, 7, and 6).
Then objects are selected and distributed between the clusters again (cluster centers
are constantly recalculated).
In the third selection of objects, object 2, which was initially the center of the
second cluster will probably relate to the first cluster.
At the end of algorithm execution, cluster 1 will include objects 1, 2, and 3.
The  second cluster will include objects 4, 5, 6, and 7.
2-744 1C:Enterprise 8.3. Developer Guide

14.6.2.5. Data output to a  dendrogram

If an algorithm that differs from a K-Mean algorithm is used to output cluster
analysis data, the results of such a cluster analysis are output as a dendrogram
(the analysis algorithm should support outputting cluster distribution of the objects
under analysis):

Fig. 304.  Dendrogram

Chapter  15

DATA EXCHANGE
MECHANISMS

15.1. GOALS AND OBJECTIVES

Data exchange mechanisms are a  set of 1C:Enterprise tools used to arrange data
exchange between different infobases and between infobases and external software
systems. Data exchange mechanisms can be classified in  two levels:
„„ Universal data exchange mechanisms
„„ Distributed infobases

15.1.1. Universal Data Exchange Mechanisms

Universal data exchange mechanisms can be used together, separately and
in different combinations, to arrange data exchange between 1C:Enterprise
infobases and other software systems. Other 1C:Enterprise infobases can serve as
software systems to exchange data with. In  this case infobases that exchange data
can generally have different configurations.
Additionally universal data exchange mechanisms can be used to arrange exchanges
with software systems that are not based on 1C:Enterprise. The  following factors
enable this:
„„ Data exchange format based on the XML language is a generally accepted
means of data representation today.
„„ Data exchange tools can be used to arrange multiple data transfer schemas, due
to their modular organization and flexibility.
„„ Protocols established by the data exchange mechanisms are not complex and
can be reproduced in  external software systems.
2-746 1C:Enterprise 8.3. Developer Guide

15.1.2. Distributed Infobases

A distributed infobase has a hierarchical structure, consisting of separate
1C:Enterprise infobase nodes that exchange data in  order to synchronize configu-
rations and data.
Control mechanisms developed to manage distributed infobases are based on
universal data exchange mechanisms, but allow some additional possibilities not
accessible through universal mechanisms.
The main difference between distributed infobases and universal data exchange
mechanisms is that universal mechanisms allow the construction of open data
exchange schemas, whereas distributed infobases are designed with a narrower
purpose and a  task of configuration change transfer to child nodes.

15.2. UNIVERSAL DATA EXCHANGE MECHANISMS

The following can be classified as universal mechanisms:
„„ XML documents read and write tools
„„ XML-serialization
„„ Exchange plans

15.2.1. XML Documents Read and Write Tools

Data exchange participants are expected to communicate in XML format.
This  way, reading and writing XML becomes the basis for data exchange.
Tools for reading and writing XML documents give you broad leverage in  working
with XML documents. This  set of tools does not provide the means to represent
1C:Enterprise data in  XML format.
1C:Enterprise has the following objects for reading and writing XML documents:
XMLReader, XMLWriter and XSLTransform. The  platform also enables operations
with XML data in FastInfoset format by means of FastInfosetReader and
FastInfosetWriter objects.

15.2.2. XML Serialization

The main task of XML-serialization is to support the reading and writing of
1C:Enterprise data objects to and from XML.
The basic tools for reading and writing XML do not provide a  sufficient foundation
for this task. They do not define 1C:Enterprise data presentation formats in  XML
and do not allow you to read/write data objects to or from XML in  an accepted
format.
Chapter 15. Data Exchange Mechanisms 2-747

15.2.2.1. Data Presentation in  XML-Serialization

In its final state, each 1C:Enterprise data object is  represented as an XML item
containing the value of the data object.
In terms of XML representation, value types can be classified as simple or complex.
Simple data types have values represented by the XML-serialization subsystem as
text-only XML items.
The values for complex types are represented as XML items containing nested
items.
An XML data type is  assigned to each corresponding 1C:Enterprise data type with
values that can be represented in  XML.
Each XML data type is  characterized by the type name and the associated names-
pace.
The XML data type can be:
„„ One of the types defined in  the "XML Schema Part 2: Datatypes" document
from the W3C consortium (namespace: http://www.w3.org/2001/XMLSchema);
„„ A predefined 1C:Enterprise type (namespace: http://v8.1c.ru/data);
„„ A type produced by 1C:Enterprise configuration metadata (not associated with
any namespace).
The XML data type can be expressly set in a data object XML-representation.
To set the XML data type, the XML item containing the value representation must
contain the type attribute associated with the http://www.w3.org/2001/XMLSchema-
instance namespace, whose value is  stored in  the XML data type.
Another possible way to set the XML data type is  using the name of the XML root
item containing the value representation. The  root item representing the data object
need not be specified and can be arbitrary. However, if the root item name is  not
specified when writing values in  XML, then it  is  assigned according to the type
of value recorded. When reading data from XML, the value type can be assigned by
the root item name if it  is  not specified in  the type attribute.
In reviewing examples of different XML value representations and in  subsequent
sections, we will use the following namespace equalities:

xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:v8="http://v8.1c.ru/data"

Representation of Simple Type Values in  XML

The following 1C:Enterprise types are considered simple from an XML representa-
tion standpoint:
„„ Number
„„ String
2-748 1C:Enterprise 8.3. Developer Guide

„„ Date
„„ Boolean
„„ BinaryData
„„ NULL
„„ UUID
„„ ValueStorage
„„ All references to database objects
„„ References to enumerations, defined in  metadata

Number
Description:
The XML decimal data type from the http://www.w3.org/2001/XMLSchema
namespace corresponds to the Number type.
Rules for representing values of this type are defined in the "XML Schema
Part 2: Datatypes" document.
Example:
<!-- No explicit setting of root item name -->
<decimal>45684.087</decimal>
<!-- Explicit setting of XML root item name -->
<Amount>523</Amount>
<!-- Explicit setting of XML data type-->
<Data xsi:type="xsd:decimal">64793.01</Data>

String
Description:
The string data type from the http://www.w3.org/2001/XMLSchema namespace
corresponds to the String type. String is  recorded in  XML as is.
Example:
<!-- No explicit setting of root item name -->
<string>This is  a string</string>
<!-- Explicit setting of XML root item name -->
<Name>Jones</Name>
<!-- Explicit setting of XML data type-->
<Data xsi:type="xsd:string">This is  a string</Data>

Date
Description:
Date-type values are represented as YYYY-MM-DDTHH:MM:SS, where:
„„ YYYY is the year in  four digits;
„„ MM is the month in  two digits;
Chapter 15. Data Exchange Mechanisms 2-749

„„ DD is the day of the month in  two digits;

„„ T is the letter T;
„„ HH is the hour (on a  24-hour clock);
„„ MM is the minutes;
„„ SS is the seconds.
This is  an acceptable format according to the "XML Schema Part 2: Datatypes"
document.
Example:
<!-- No explicit setting of root item name -->
<dateTime>2008-11-21T12:00:00</dateTime>
<!-- Explicit setting of XML root item name -->
<Started>2001-10-30T19:00:00</Started>
<!-- Explicit setting of XML data type-->
<Data xsi:type="xsd:dateTime">1980-08-25T10:00:00</Data>

Boolean
Description:
The boolean data type from the http://www.w3.org/2001/XMLSchema name-
space corresponds to the Boolean type.
The False value is represented by the false string and the True value
is represented by the true string. This format is provided in the "XML
Schema Part 2: Datatypes" document.
Example:
<!-- No explicit setting of root item name -->
<boolean>false</boolean>
<!-- Explicit setting of XML root item name -->
<Posted>true</Posted>
<!-- Explicit setting of XML data type-->
<Data xsi:type="xsd:boolean">true</Data>

BinaryData
Description:
The XML base64Binary data type from the http://www.w3.org/2001/XMLS-
chema namespace corresponds to the BinaryData type.
Values of this type are represented as binary data, encoded using the Base64
algorithm, described in  RFC 2045 (http://www.faqs.org/rfcs/rfc2045.html).
Example:
<!-- No explicit setting of root item name -->
<base64Binary>YWJjZGVm</base64Binary>
<!-- Explicit setting of XML root item name -->
2-750 1C:Enterprise 8.3. Developer Guide

<BinaryData>YWJjZGVm</BinaryData>
<!-- Explicit setting of XML data type-->
<Data xsi:type="xsd:base64Binary">YWJjZGVm</Data>

NULL
Description:
The XML Null data type from the http://v8.1c.ru/data namespace corresponds
to the NULL type. This  type has a  single value, represented by an empty string.
Example:
<!-- No explicit setting of root item name -->
<v8:Null/>
<!-- Explicit setting of XML root item name -->
<Selected/>
<!-- Explicit setting of XML data type-->
<Data xsi:type="v8:Null"/>

UUID
Description:
The XML UUID data type from the http://v8.1c.ru/data namespace corresponds
to the UUID type.
Values of this type are represented in XML according to generally accepted
practice and standards (ISO-11578, DCE 1.1: Remote Procedure Call  –
Universal Unique Identifier).
Example:
<!-- No explicit setting of root item name -->
<v8:UUID>3294be0f-c039-41a9-bd65-596da0dcfe68</v8:UUID>
<!-- Explicit setting of XML root item name -->
<Id>da035e32-3f7a-4d87-accf7db8cb4b</Id>
<!-- Explicit setting of XML data type ->
<Data xsi:type="v8:UUID">08839b0b-5ec3-4a53-a9f5-173312316919</Data>

ValueStorage
Description:
The XML ValueStorage data type from the http://v8.1c.ru/data namespace
corresponds to the ValueStorage type.
Values of this type are represented in  XML as ValueStorage, saved to file
and then encoded using the Base64 algorithm.
Example:
<!-- No explicit setting of root item name -->
<v8:ValueStorage>AQEOAAAAAAAAAO+7v3siUyIsIjHQoSJ9</v8:ValueStorage>
<!-- Explicit setting of XML root item name -->
Chapter 15. Data Exchange Mechanisms 2-751

<Data>AQEOAAAAAAAAAO+7v3siUyIsIjHQoSJ9</Data>
<!-- Explicit setting of XML data type-->
<Data xsi:type="v8:ValueStorage">AQEOAAAAAAAAAO+7v3siUyIsIjHQoSJ9</Data>

References to Database Objects

Description:
Each type of reference to database objects has its own corresponding XML
data type. The  name of the XML data type for references to database objects
corresponds to the name of the 1C:Enterprise reference value type in  English.
For example, in  the Currency catalog, the English name of the reference type
is  CatalogRef.Currencies. The  name of the XML data type is  identical to it.
XML data types for references to database objects are not associated with any
namespace.
Reference values are represented in  XML as UUID type values, obtained from
the references.
Example:
<!-- No explicit setting of root item name -->
<CatalogRef.Banks>911b5b8b-11f5-4993-9673-2c9a7a8995d5</CatalogRef.Banks >
<!-- Explicit setting of XML root item name -->
<Ref>911b5b8b-11f5-4993-9673-2c9a7a8995d5</Ref>
<!-- Explicit setting of XML data type-->
<Data xsi:type="CatalogRef.Banks">911b5b8b-11f5-4993-9673-2c9a7a8995d5</Data>

References to Enumerations Defined in  Metadata

Description:
Each type of reference to enumeration values defined in  the configuration has its
own corresponding XML data type. The  XML data type name for references to
enumeration values corresponds to the name of the 1C:Enterprise type in  English.
For example, in the AddressTypes catalog, the English name of the value
reference type is  EnumRef.AddressTypes. The  name of the XML data type
is  identical to it.
XML data types for references to enumeration values are not associated with
any namespace. In  XML, references to enumeration values are represented as
names corresponding to enumeration values.
Example:
<!-- No explicit setting of root item name -->
<EnumRef.AddressTypes>Legal</EnumRef.AddressTypes>
<!-- Explicit setting of XML root item name -->
<Ref>Legal</Ref>
<!-- Explicit setting of XML data type-->
<Data xsi:type="EnumRef.AddressTypes">Actual</Data>
2-752 1C:Enterprise 8.3. Developer Guide

Representation of Complex Type Values in  XML

The following 1C:Enterprise types that can be represented in  XML are classified
as complex.
„„ Type
„„ TypeDescription
„„ ConstantValueManager.<Constant name>
„„ All database objects
„„ Sets of register records, sequences and recalculations
„„ ObjectDeletion

Type
Description:
The XML Type data type from the http://v8.1c.ru/data namespace corresponds
to the Type type. The  XML item representing a  value of this type contains text
providing the name of the XML type corresponding to the 1C:Enterprise data
type.
At first glance, Type appears to be a simple data type rather than complex,
since the item representing the value of this type does not contain nested items.
However, this is  not the case. There really are no nested items. However, the
item text containing the name of the XML data type, contains the prefix for
the type namespace which must be defined in  this item or in  one of the parent
items, making the item text not entirely self-sufficient. Therefore, this type
is  not considered simple.
Example:
<!-- No explicit setting of root item name -->
<v8:Type>v8:ValueStorage</v8:Type>
<!-- Explicit setting of XML root item name -->
<Tp>xsd:string</Tp>
<!-- Explicit setting of XML data type-->
<Data xsi:type="v8:Type">v8:ValueStorage<Data>

TypeDescription
Description:
The XML TypeDescription data type from the http://v8.1c.ru/data namespace
corresponds to the TypeDescription type. The root item representing the
TypeDescription type value, includes a  set of nested items, each containing
a  component of the type description.
The nested Types item from the http://v8.1c.ru/data namespace represents
separate types entered into the type description. The  NumberQualifiers item
Chapter 15. Data Exchange Mechanisms 2-753

from the http://v8.1c.ru/data namespace contains qualifiers for numerical values.

The  StringQualifiers and DateQualifiers items from the same name-
space contain qualifiers for string and date, respectively.
Example:
<v8:TypeDescription>
<v8:Types>
<v8:Type>v8:UUID</v8:Type>
<v8:Type>CatalogRef.Banks</v8:Type>
<v8:Type>xsd:boolean</v8:Type>
<v8:Type>xsd:boolean</v8:Type>
</v8:Types>
<v8:NumberQualifiers>
<v8:Digits>10</v8:Digits>
<v8:FractionDigits>2</v8:FractionDigits>
<v8:AllowedSign>Any</v8:AllowedSign>
</v8:NumberQualifiers>
<v8:StringQualifiers>
<v8:Length>30</v8:Length>
<v8:AllowedLength>Variable</v8:AllowedLength>
</v8:StringQualifiers>
<v8:DateQualifiers>
<v8:DateFractions>Date</v8:DateFractions>
</v8:DateQualifiers>
</v8:TypeDescription>

ConstantValueManager.<Constant name>
Description:
Each of the ConstantValueManager.<Constant name> types has a  corre-
sponding XML data type (ConstantValueManager.<Constant name>), not
associated with any namespace.
Example:
<ConstantValueManager.OrganizationName>
<Value>Mobius LLC</Value>
</ConstantValueManager.OrganizationName>

Database Objects
Description:
Database objects are represented in XML as a combination of attribute
values and tabular sections. The name of the XML data type corresponding
to the database object is  defined as the name of the 1C:Enterprise value type
in  English. XML data types for database objects are not associated with any
namespace. The  list of XML items nested in  the root item is  defined by the
type of object as well as the list of attributes and tabular sections.
2-754 1C:Enterprise 8.3. Developer Guide

Each attribute is represented by an XML item, whose name corresponds to

the name of the attribute. If the attribute value type cannot be defined from the
metadata, then the XML item representing the attribute contains the xsi:type
attribute which indicates the XML value type.
Each tabular section is represented by an XML item with a corresponding
name.
Each row from the tabular section is  represented by an XML item named Row.
Tabular section attributes are represented by XML items nested in  the Row item.
Example:
XML representation for a  Document.CustomerOrder object:
<DocumentObject.CustomerOrder>
<Ref>8d106783-9726-11d7-9334-0050ba8480bd</Ref>
<DeletionMark>false</DeletionMark>
<Date>2008-04-15T12:00:00</Date>
<Number>00000006</Number>
<Posted>true</Posted>
<CompanySubdivision>
317f130d-5a08-11d7-9324-0050ba8480bd</CompanySubdivision>
<OperationalUnit xsi:type="CatalogRef.CompanyCashRegisters">
317f12f4-5a08-11d7-9324-0050ba8480bd</OperationalUnit>
<Contractor>12952ac7-5a08-11d7-9324-0050ba8480bd</Contractor>
<ContractorLegalEntityPerson xsi:type="CatalogRef.LegalEntities">
0aadfe81-5a08-11d7-9324-0050ba8480bd</ContractorLegalEntityPerson>
<DocumentCurrency>
029156b4-5a08-11d7-9324-0050ba8480bd</DocumentCurrency>
<DocumentRate>1</DocumentRate>
<AccountForVAT>true</AccountForVAT>
<AccountForIT>true</AccountForIT>
<AmountInclVAT>false</AmountInclVAT>
<AmountInclIT>false</AmountInclIT>
<Comment/>
<DocumentAmount>44077.14</DocumentAmount>
<OperationType>InvoiceForPayment</OperationType>
<SettlementAgreement>
b0401f23-6e84-11d7-932c-0050ba8480bd</SettlementAgreement>
<CompanyWarehouse>
317f1317-5a08-11d7-9324-0050ba8480bd</CompanyWarehouse>
<PriceType>317f1311-5a08-11d7-9324-0050ba8480bd</PriceType>
<PaymentDate>2008-04-15T00:00:00</PaymentDate>
<AutoReserve>false</AutoReserve>
<AutoPlacement>false</AutoPlacement>
<SettlementRate>33.4209</SettlementRate>
<DiscountExtraChargeType>
00000000-0000-0000-0000-000000000000</DiscountExtraChargeType>
<Organization>317f1308-5a08-11d7-9324-0050ba8480bd</Organization>
<ShipmentDate>2008-04-15T00:00:00</ShipmentDate>
<Responsible>
4ff40e0b-5ac5-11d7-9325-0050ba8480bd</Responsible>
Chapter 15. Data Exchange Mechanisms 2-755

<DocumentFrequency>1</DocumentFrequency>
<SettlementFrequency>1</SettlementFrequency>
<Goods>
<Row>
<Nomenclature>
297c6534-5a08-11d7-9324-0050ba8480bd</Nomenclature>
<UnitOfMeasure>
297c6535-5a08-11d7-9324-0050ba8480bd
</UnitOfMeasure>
<Price>4537.56</Price>
<Sum>13612.68</Sum>
<VATRate>VAT20</VATRate>
<VATSum>2722.54</VATSum>
<ITRate>1ac73736-5a08-11d7-9324-0050ba8480bd</ITRate>
<ITSum>0</ITSum>
<NomenclatureCharacteristic>
00000000-0000-0000-0000-000000000000
</NomenclatureCharacteristic>
<Placement xsi:nil="true"/>
<Factor>1</Factor>
<Count>3</Count>
<DiscountExtraChargePercent>0</DiscountExtraChargePercent>
</Row>
<Row>
<Nomenclature>
317f12d8-5a08-11d7-9324-0050ba8480bd</Nomenclature>
<UnitOfMeasure>
317f12d9-5a08-11d7-9324-0050ba8480bd
</UnitOfMeasure>
<Price>4915.55</Price>
<Sum>19662.2</Sum>
<VATRate>VAT20</VATRate>
<VATSum>3932.44</VATSum>
<ITRate>1ac73736-5a08-11d7-9324-0050ba8480bd</ITRate>
<ITSum>0</ITSum>
<NomenclatureCharacteristic>
00000000-0000-0000-0000-000000000000
</NomenclatureCharacteristic>
<Placement xsi:nil="true"/>
<Factor>1</Factor>
<Count>4</Count>
<DiscountExtraChargePercent>0</DiscountExtraChargePercent>
</Row>
</Goods>
<Returnables/>
</DocumentObject.CustomerOrder>

NOTE
This example and others given in this chapter use long strings (e.g.,
<UnitOfMeasure>317f12d9-5a08-11d7-9324-0050ba8480bd</UnitOfMeasure>). Due
to book format limitations, these strings are wrapped to the next line(s). In  prac-
tice, these strings are each written on a  single line.
2-756 1C:Enterprise 8.3. Developer Guide

Record Set
Description:
The XML representation of a  record set includes the filter used to retrieve the
record set and the records. Filter values represented in  the nested XML item
named Filter are not associated with any namespace. All records comprising
a  set of records are represented in  the nested Records item that is  also not
associated with any namespace. Records are represented by Record XML items
nested in  the Records item. The  name of the Record item is  also not associ-
ated with any namespace.
Example:
Below is  an XML representation for a  record set of the CompanyProductIn-
ventory accumulation register:
<AccumulationRegisterRecordSet.CompanyProductInventory>
<Filter>
<Recorder xsi:type="DocumentRef.Goodsales">
1725f36e-6f35-11d7-932d-0050ba8480bd</Recorder>
</Filter>
<Records>
<Record>
<Recorder xsi:type="DocumentRef.Goodsales">
1725f36e-6f35-11d7-932d-0050ba8480bd</Recorder>
<Period>2008-04-13T17:45:39</Period>
<MovementType>Expense</MovementType>
<Active>true</Active>
<Nomenclature>
297c6556-5a08-11d7-9324-0050ba8480bd</Nomenclature>
<CompanyWarehouse>
317f1317-5a08-11d7-9324-0050ba8480bd</CompanyWarehouse>
<Order xsi:nil="true"/>
<RetailPrice>0</RetailPrice>
<NomenclatureCharacteristic>
00000000-0000-0000-0000-000000000000
</NomenclatureCharacteristic>
<Count>2</Count>
<CompanySubdivision>
317f130d-5a08-11d7-9324-0050ba8480bd
</CompanySubdivision>
</Record>
<Record>
<Recorder xsi:type="DocumentRef.Goodsales">
1725f36e-6f35-11d7-932d-0050ba8480bd</Recorder>
<Period>2008-04-13T17:45:39</Period>
<MovementType>Expense</MovementType>
<Active>true</Active>
<Nomenclature>
297c6558-5a08-11d7-9324-0050ba8480bd</Nomenclature>
<CompanyWarehouse>
Chapter 15. Data Exchange Mechanisms 2-757

317f1317-5a08-11d7-9324-0050ba8480bd</CompanyWarehouse>
<Order xsi:nil="true"/>
<RetailPrice>0</RetailPrice>
<NomenclatureCharacteristic>
ac47d77e-5ec7-11d7-9329-0050ba8480bd
</NomenclatureCharacteristic>
<Count>2</Count>
<CompanySubdivision>
317f130d-5a08-11d7-9324-0050ba8480bd
</CompanySubdivision>
</Record>
</Records>
</AccumulationRegisterRecordSet.CompanyProductInventory>

ObjectDeletion
Description:
The XML ObjectDeletion data type from the http://v8.1c.ru/data namespace
corresponds to the ObjectDeletion type. The  root item of the XML-repre-
sentation for the ObjectDeletion type value contains a  nested Ref item from
the http://v8.1c.ru/data namespace which contains a  presentation of a  database
object reference.
Example:
Below is  an example of XML representation of an ObjectDeletion object:
<v8:ObjectDeletion xmlns="http://v8.1c.ru/data">
<v8:Ref xsi:type="CatalogRef.Banks">
60c5cec3-7f6f-4ec3-9620-e757fe3614ca</v8:Ref>
</v8:ObjectDeletion>

15.2.2.2. Access to XML-Serialization Tools From 1C:Enterprise Script

Two global methods are used for working with XML representations of simple type
values: XMLString() and XMLValue().
The XMLString() method has one parameter – the value for which XML represen-
tation is  needed. This  value must be a  simple type in  XML serialization terms.
Otherwise an exception is raised. If complete successfully, the function returns
a  string that can be used as XML item text representing simple type values.
The XMLValue() method performs the opposite task. This  method has two param-
eters:
„„ The value type to be received from the string
„„ The string itself
To convert a  1C:Enterprise data type into an XML data type and vice versa, use
XMLType() and FromXMLType() methods. The XMLType() method has one
parameter – the type for which the corresponding XML data type is needed.
2-758 1C:Enterprise 8.3. Developer Guide

If the corresponding XML data type is defined, then the method returns the
XMLDataType value. If there is  no corresponding XML data type, then the method
returns the Undefined value.
The FromXMLType() method has two call variants. In  the first variant, the method
has a single XMLDataType parameter. The second option has two parameters:
the XML type name and the namespace. In both cases, this method returns the
1C:Enterprise data type to the corresponding XML data type, if available; other-
wise it  returns the Undefined value.
Two global methods can be used to read and write various values to and from
XML: WriteXML() and ReadXML().
The WriteXML() method has two required parameters. The  first parameter is  the
XMLWriter type object used to write XML, while the second is  the value which
needs to be written in  XML. Optional parameters make up three different variants
for calling this method.
In the simplest case, there are three parameters and the third parameter specifies the
XMLTypeAssignment enumeration value and creates the need to specify the XML
data type explicitly in  the xsi:type attribute of the XML root item.
The next variant uses a  string value as the third parameter, indicating the name of
the XML root item. This  implies that the namespace is  not defined. The  fourth
parameter is a XMLTypeAssignment value that requires explicit setting of the
XML data type.
Finally, the last variant includes, after the parameter for the XML root item name,
an additional parameter – a  string value indicating the namespace associated with
the root item. The  last parameter still has the XMLTypeAssignment type.

...
Val = "A string";
WriteXML(Wr, Val);
WriteXML(Wr, Val, "Root", XMLTypeAssignment.Explicit);
WriteXML(Wr, Val, "Root", "urn:some-namespace");
...

The code above results in  the following XML fragment:

...
<string>A string</string>
<Root xsi:type="xsd:string">A string</Root>
<d1p1:Root xmlns:d1p1="urn:some-namespace">A string</d1p1:Root>
...

If a type value that cannot be represented in XML is passed as a value to be

placed in  XML, an exception is  raised.
The ReadXML() method can be used to read values from XML. This  method has
one required parameter, the XMLReader object, from which the value must be
Chapter 15. Data Exchange Mechanisms 2-759

read. A value type that needs to be read from XML can be specified as the second
parameter. If the value type is  explicitly assigned in  XML, then Undefined can
be used as the second parameter or it  can be omitted altogether. In  this case the
ReadXML() method attempts to define the type of value being read based on the
xsi:type attribute or, if the xsi:type attribute is  missing, based on the item name.
If you cannot successfully establish the type or the value of the specified type
cannot be read from XML, an exception is  raised. Upon successful completion the
ReadXML() method returns the value it  has read.
Please note how constant value managers, database objects and record sets are read.
A successful reading using the ReadXML() method returns the value read from
XML, but this value has not yet been recorded in  the database. If, for example,
a  catalog item has been read, then in  order to record the it  in  the database the
Write() method has to be used, just like when "standard" modified objects are
recorded. It  also applies to other database objects, constant record managers and
record sets.
When reading a  database object from XML, objects with the same reference value
are searched for. If such an object is  found, its reading from XML looks like it  has
been read from the database; then the values of its attributes, tabular sections, etc.
are replaced with values received from XML. If the object is  not found by refer-
ence, reading from XML looks like creating a new object, specifying reference
values and filling it  with values read from XML.
The CanReadXML() method defines whether it  is  possible to read a  value from
the XMLReader object located in the current position of the XML document.
The  XMLReader object is passed to this method as a parameter. If the method
returns True, reading is  possible; if False is  returned, the value cannot be read.
The GetXMLType() method can be used to retrieve the XML data type corre-
sponding to the current XML document position from the XMLReader object.
This  method also has one parameter – XMLReader.

15.2.3. Exchange Plans

Exchange plans constitute a center around which other data exchange tools are
grouped. Any number of exchange plans can be defined in  a single configuration.
Each exchange plan defines the set of data for which the exchange is planned.
With this data set, specific data presentation formats can also be defined.
Data formats are intended to be based on XML, but because of the flexibility of
the XML language and availability of different tools for working with XML
in  1C:Enterprise, you can be creative in  presenting data.
In exchange plans, two important components can be singled out:
„„ Message infrastructure
„„ Change registration service
2-760 1C:Enterprise 8.3. Developer Guide

Exchange plan data items are called exchange plan nodes. This is similar to
a  catalog structure where catalog data items are catalog items. Each exchange plan
node designates a  data transfer participant for a  particular exchange plan. One of
the nodes corresponds to the infobase and the rest correspond to other participants
with which this infobase can exchange.
Data are transferred between nodes through messages. The  tools for working with
messages constitute the message infrastructure. Each message is  associated with
a  specific exchange plan and has a  defined sender node and recipient node. A
message cannot be sent to or received from an unknown node. Each message has its
own (integer) number.
Change registration service is used to register data changes effected by
1C:Enterprise in  order to provide the opportunity of transferring just the changes
and not all the data during data exchange.
Therefore, exchange plans define the set of tools used to organize data exchange.
We will review these tools in  more detail.

15.2.3.1. Exchange Plan Nodes

When creating a  new exchange plan, one node is  automatically created – this is  a
node or an exchange plan node which corresponds to a  particular infobase. All the
other nodes that are available to the current node for data exchange are not auto-
matically created as part of an exchange plan.
A unique code must be defined for each node to identify it  during data exchange.
Node codes are specified for the exchanging parties to "recognize" each other.
NOTE
An exchange plan must contain the code and the name. In  other words, you can-
not set the length equal to 0 for the exchange plan’s standard attributes (Code and
Name).

Suppose it  is  necessary to organize data exchange between two infobases using
the RemoteWarehouses exchange plan. One of these infobases carries out the
functions of a  central office and the other acts as a  remote warehouse.
In this case you would need to enter Office in  the first infobase as the code value
for this node of the RemoteWarehouses exchange plan (if the code length permits,
of course) and Warehouse1 in  the second infobase. Thus, these nodes are assigned
names. But this is  not enough; data exchange destination nodes need to be entered. To
accomplish this, a  Warehouse1 node needs to be created in  the RemoteWarehouses
exchange plan in  the first infobase and an Office node – in  the second infobase.
Thus, the first infobase "knows" that it is named Office in the RemoteWare-
houses exchange plan and is  to exchange data with the Warehouse1 node; the
second infobase, on the other hand, knows that it  is  named Warehouse1 and is  to
exchange data with the Office node.
Chapter 15. Data Exchange Mechanisms 2-761

15.2.3.2. Message Infrastructure

The most important component of the message infrastructure is the message
itself. As was already noted, messages are sent from one node to another within an
exchange plan. Each message follows the exchange plan exactly and has one sender
and one recipient.
We will go over what this message entails. The  message is  laid out as an XML docu-
ment with a  defined structure. We will use the following message as an example:
<v8msg:Message xmlns:v8msg="http://v8.1c.ru/messages">
<v8msg:Header>
<v8msg:ExchangePlan>RemoteWarehouses</v8msg:ExchangePlan>
<v8msg:To>Warehouse1</v8msg:To>
<v8msg:From>Office</v8msg:From>
<v8msg:MessageNo>20</v8msg:MessageNo>
<v8msg:ReceivedNo>15</v8msg:ReceivedNo>
</v8msg:Header>
<v8msg:Body>
<!– Message body -->
</v8msg:Body>
</v8msg:Message>

The entire message is  located within the Message XML item that belongs to the
http://v8.1c.ru/messages namespace. The message is divided into a header and
a  body. Accordingly, the Message item contains two nested elements: Header and
Body. Both of them are associated with the "http://v8.1c.ru/messages" namespace.
The Header item contains the message header. The header's structure is hard-
coded. Header information is represented in several XML items nested
in the Header item. All items nested in the Header item are belong to the
http://v8.1c.ru/messages namespace.
„„ ExchangePlan contains the name of the exchange plan with which the message
is associated.
„„ To contains the code of the sender node.
„„ From contains the code of the destination node.
„„ MessageNo contains the number of the message. The message number is a
positive integer number assigned by the sender node. The number of each
subsequent message is  the number of the preceding message incremented by 1.
„„ ReceivedNo contains the highest message number that the sender node of the
message has received from the recipient node. This  value is  included in  the
message header to confirm receipt of the message.
The body of the message is  contained in  the Body XML item which is  associated
with the http://v8.1c.ru/messages namespace. The  item's content is  arbitrary and
depends on the application requirements. The message infrastructure does not
regulate the message body in  any way.
2-762 1C:Enterprise 8.3. Developer Guide

15.2.3.3. Change Registration Service

The purpose of change registration is compiling a list of modified data items.
These items are to be transferred to the data exchange destination node in  the next
message. With each data change, it  must be recorded that there are changes to be
transferred to all nodes that support the exchange of these data. After receipt of
the message containing the changes is  confirmed, change registration records are
deleted.
Change registration is  supported for the following data items:
„„ ConstantValueManager.<Constant name>
„„ Database objects:
○○ CatalogObject.<Catalog name>
○○ DocumentObject.<Document name>
○○ ChartOfAccountsObject.<Chart of Accounts name>
○○ ChartOfCharacteristicTypesObject.<Chart of characteristic
types name>
○○ ChartOfCalculationTypesObject.<Chart of calculation types
name>
○○ BusinessProcessObject.<Business process name>
○○ TaskObject.<Task name>
„„ Record sets:
○○ InformationRegisterRecordSet.<Information register name>
○○ AccountingRegisterRecordSet.<Accounting register name>
○○ AccumulationRegisterRecordSet.<Accumulation register name>
○○ SequenceRecordSet.<Sequence name>
○○ CalculationRegisterRecordSet.<Calculation register name>
○○ RecalculationRecordSet.<Recalculation name>
Each data item has its own change registration table. The tables have different
structures depending on which data items the changes are registered for, but all
table structures are similar. The  structure can be divided into three components:
„„ The key of the data item for which changes are registered.
„„ The reference to the node to which the change is  to be transferred.
„„ The number of the message in  which the change is  first transferred.
The structures of change registration tables for different data have different keys,
since keys for various data differ:
„„ A constant ID is  used as the key for constants.
„„ A reference to the object is  used as the key for database objects.
„„ A reference to the recorder object is used as the key for record sets with
a  defined recorder.
Chapter 15. Data Exchange Mechanisms 2-763

„„ If a recorder is not defined for an information register record set, then

a combination of dimensions from the main filter is used as the key. If the
information register is  periodical and the main filter by period is  enabled, then
the period is  also included in  the key.
When a data item is modified, this change must be registered for all nodes to
which it  is  to be transferred. Thus, a  data item change must result in  N records
in  the change registration table, where N is  the number of nodes for which changes
are registered. All records contain the same data item key value and different refer-
ences to nodes.
Immediately after change registration, the message number reads NULL. When the
change is  first sent, the number for this message is  entered into this field.
When configuring the exchange plan, you must define the content of the exchange
plan. Metadata objects are included in  the exchange plan content. Entering meta-
data objects into the exchange plan content shows that data changes corresponding
to the metadata object can be registered for the node of this exchange plan. If
a  metadata object is  not in  any of the exchange plans, then a  change registration
table is  not created for the object and data change registration does not take place.
The AutoRecord property specifies how metadata objects are entered into the
exchange plan. Auto-record can be enabled or disabled. If auto-record is  enabled,
data change registration is  automatic. If it  is  disabled, change registration can be
completed manually.

15.2.3.4. Access to Exchange Plan Mechanisms Using

1C:Enterprise Script
The 1C:Enterprise script offers a  set of objects for working with exchange plans.
The ExchangePlansManager object, besides its standard manager function-
alities, provides methods for working with the change registration service:
RecordChanges(), DeleteChangeRecords(), IsChangeRecorded() and
SelectChanges(), as well as methods for creating message reader and writer
objects: CreateMessageReader() and CreateMessageWriter().
The most important feature of the ExchangePlanManager.<Exchange plan
name> is  the ThisNode() method which returns a  reference to the node of this
exchange plan corresponding to a  particular infobase.
ExchangePlanManager.<Exchange plan name> corresponds to the exchange
plan node. The  SentNo and ReceivedNo properties are described in  more detail.
The  SentNo property contains the number of the last message sent from the
infobase to the node corresponding to the ExchangePlanManager.<Exchange
plan name> object. The ReceivedNo property contains the highest message
number of the messages received by the infobase from the node corresponding to
the ExchangePlanManager.<Exchange plan name> object.
2-764 1C:Enterprise 8.3. Developer Guide

Change Registration
As already noted, changes can be registered automatically when a data item
is  recorded or deleted. Let us review how it  is  accomplished. Each object whose
changes can be recorded by the exchange plan has the DataExchange property
with the DataExchangeParameters type. This property can be used only for
reading only; it  is  intended for managing different parameters in  data exchanges.
The DataExchangeParameters object has the Recipients property with the
NodeSet type. This  property stores a  list of nodes for which changes are recorded
upon data write or delete operations. The  list of recipients is  automatically filled
before either the BeforeWrite() handler (for data writing) or BeforeDelete()
handler (for deletion) is invoked. However, auto-fill only takes place if the
AutoFill property of the NodeSet object reads True (True is default for the
AutoFill property). Auto-filling includes references to all nodes of all exchange
plans with the corresponding metadata object in the recipient list provided that
the AutoRecord property is  set to Enable. It  goes without saying that the nodes
corresponding to the infobase are not placed on the recipient list. The  recipient list
is  cleared before auto-filling.
In the BeforeWrite() (and/or BeforeDelete()) handler, you can make changes
to the recipient list: add or remove node references. However, keep in  mind that
the recipient list can only contain references to nodes associated with the exchange
plans containing the corresponding metadata object.
In the example below, the BeforeWrite() handler excludes a  Special node of
the RemoteWarehouses exchange plan from the recipient list.
Procedure BeforeWrite()
Node = ExchangePlans.RemoteWarehouses.FindByCode("Special");
DataExchange.Recipients.Delete(Node);
EndProcedure

By assigning False to the AutoFill property, you can disable auto-filling for
the recipient list. In this case the recipient list can be managed both in the
BeforeWrite() handler and in  any code fragment, as shown in  the example:
Object = Ref.GetObject();
Node = ExchangePlans.RemoteWarehouses.FindByCode("Warehouse1");
Object.DataExchange.Recipients.AutoFill = False;
Object.DataExchange.Recipients.Add(Node);
Object.Write();

The ExchangePlansManager object contains a variety of tools for recording

changes. First of all, it  has the RecordChanges() method. This  method allows
you to record changes of single data items or entire groups for one or more nodes.
The  first parameter of this method is  a reference to the exchange plan node or an
array of references to nodes for which changes are recorded. If the first parameter
Chapter 15. Data Exchange Mechanisms 2-765

is  a single node reference, then the second parameter can be omitted. In  this case
change recording takes place for all data items currently existing in  the database
and supporting change registration for the node.
This can be useful for organizing initial data transmissions to newly created nodes.
Node = ExchangePlans.RemoteWarehouses.FindByCode("New");
ExchangePlans.RecordChanges(Node);

If the first parameter is  an array of references to nodes, then the second parameter
must be specified. However, the second parameter can still be used if the first param-
eter is a single node reference. Depending on how the second parameter is set,
changes can be recorded for one data item or all data related to one metadata object.
To record changes for a  single item, you can use the data item itself, a  reference to
the database object or an ObjectDeletion object as the second parameter.
If a  data item is  indicated, then its change is  recorded. If a  database object refer-
ence is  indicated, then the change to this object is  registered.
If the second parameter has the ObjectDeletion type, then changes are registered
for the database object referred to by ObjectDeletion.
Nodes = New Array(2);
Nodes[0] = ExchangePlans.RemoteWarehouses.FindByCode("Warehouse1");
Nodes[1] = ExchangePlans.RemoteWarehouses.FindByCode("Warehouse2");
Data = Catalogs.Nomenclature.FindByCode("KL00127");
ExchangePlans.RecordChanges(Nodes, Data);

To record changes for all data related to a metadata object, the corresponding
metadata object must be specified as the second parameter.
Nodes = New Array(2);
Nodes[0] = ExchangePlans.RemoteWarehouses.FindByCode("Warehouse1");
Nodes[1] = ExchangePlans.RemoteWarehouses.FindByCode("Warehouse2");
ExchangePlans.RecordChanges(Nodes, Metadata.Catalogs.Nomenclature);

To remove change registration records, ExchangePlansManager has the

DeleteChangeRecords() method. It can be used to delete change registration
records for all data registered for the node.
Node = ExchangePlans.RemoteWarehouses.FindByCode("Warehouse1");
ExchangePlans.DeleteChangeRecords(Node);

Change registration records can be deleted for a  specific data item for one or more
nodes.
Nodes = New Array(2);
Nodes[0] = ExchangePlans.RemoteWarehouses.FindByCode("Warehouse1");
Nodes[1] = ExchangePlans.RemoteWarehouses.FindByCode("Warehouse2");
Data = Catalogs.Nomenclature.FindByCode("KL00127");
ExchangePlans.DeleteChangeRecords(Nodes, Data);
2-766 1C:Enterprise 8.3. Developer Guide

Change registration records can also be deleted for all data related to a  metadata
object for one or more nodes.
Nodes = New Array(2);
Nodes[0] = ExchangePlans.RemoteWarehouses.FindByCode("Warehouse1");
Nodes[1] = ExchangePlans.RemoteWarehouses.FindByCode("Warehouse2");
ExchangePlans.DeleteChangeRecords(Nodes, Metadata.Catalogs.Nomenclature);

In addition, if a single node is used as the first parameter, then the message
number can be used as the second parameter. In this case the DeleteChang-
eRecords() method deletes all records associated with the indicated nodes from
the change registration table if their message number is  less than or equal to the
second parameter value (but not NULL). This  method is  used for deleting change
registration records for which change receipt has been confirmed by the node speci-
fied in  the first parameter.
To check whether a data item change for a node has been recorded, use the
IsChangeRecorded() method. The  first parameter of this method is  a reference
to the node and the second parameter is  the Data item, a  reference to the database
object or ObjectDeletion.
Writing Data Exchange Messages
The ExchangeMessageWriter object is  used for writing messages.
The ExchangeMessageWriter object is created using the CreateMessage-
Writer() method of the ExchangePlansManager object.
The ExchangeMessageWriter object has three methods:
„„ BeginWrite()
„„ EndWrite()
„„ CancelWrite()
The BeginWrite() method has two parameters: the XMLWriter object used to write
the message and a  reference to the message destination node. The  BeginWrite()
method calculates the message number by adding 1 to the previous message number
and writes the beginning of the XML item containing the entire message, the entire
message header and the beginning of the XML item containing the message body.
After this you can begin writing the content of the message body.
To successfully complete the message write operation, use the EndWrite()
method. This  method writes the end of the XML item containing the message body
and the end of the XML item containing the entire message. After the XML items
that complete the message are successfully recorded, the message is considered
submitted and its number is  saved as the number of the last message sent from this
node to recipient node.
If the message writing operation has to be aborted and the message must not be
considered submitted, use the CancelWrite() method.
Chapter 15. Data Exchange Mechanisms 2-767

Below is  a typical code fragment which writes a  data exchange message.
XMLWriter = New XMLWriter();
XMLWriter.OpenFile(MessageFileName);
Node = ExchangePlans.RemoteWarehouses.FindByCode(NodeCode);
MessageWriter = ExchangePlans.CreateMessageWriter();
MessageWriter.BeginWrite(XMLWriter, Node);
// Writing the message body
MessageWriter.EndWrite();

The message body can contain any data represented in  XML, depending on the
format used for a  particular exchange plan. Below is an example of a  message
containing data with changes registered by the change registration service. To
accomplish this, select the registered changes, tab through them and include the
XML representations of the data changes in  the message.
The SelectChanges() method of the ExchangePlansManager object is  used to
select changes. This  method has two parameters: a  reference to the node for which
the change is  selected and the number of the message into which the changes must
entered. The SelectChanges() method returns a ChoiceData object which
contains the keys of the data with changes registered for the node passed as the first
parameter. Additionally the SelectChanges() method enters the message number
passed as the second parameter into the corresponding fields of the selected change
registration table records if these fields contain the NULL value.
If the change was already selected in the last cycle, then the message number
in the corresponding record of the change registration table is not modified;
however, if the change has not yet been selected, the system saves the number of
the first message with the selected changes.
To tab through change selections, use Next() and Get() methods. When the
Next() method is  called, the next key in  the selection comes up. The  first time
the Next() method is called, the first key comes up. When the Get() method
is  invoked, a  data item corresponding to the current selection key is  selected from
the database. Here it is worth making a separate comment on deleted database
objects. If a  database object change was recorded as a  result of deletion, then the
Get() method does not return the database object, but rather an ObjectDeletion
type object.
XML data items can be placed into the message using the global context
WriteXML() method.
Below is a code fragment in which a message is generated and recorded data
changes are placed into its body.

XMLWriter = New XMLWriter();

XMLWriter.OpenFile(MessageFileName);
Node = ExchangePlans.RemoteWarehouses.FindByCode(NodeCode);
MessageWriter = ExchangePlans.CreateMessageWriter();
2-768 1C:Enterprise 8.3. Developer Guide

MessageWriter.BeginWrite(XMLWriter, Node);
Selection = ExchangePlans.SelectChanges(Node, MessageWriter.MessageNo);
While Selection.Next() Do
Data = Selection.Get();
WriteXML(XMLWriter, Data);
EndDo;
MessageWriter.EndWrite();

Reading Data Exchange Messages

The ExchangeMessageReader object is designed for reading data exchange
messages.
This object can be created by using the CreateMessageReader() method of the
ExchangePlansManager object.
The ExchangeMessageReader object has three methods:
„„ BeginRead()
„„ EndRead()
„„ CancelRead()
The BeginRead() method has two parameters: the XMLReader object that reads
messages and the AllowedMessageNo enumeration value.
The BeginRead() method reads the beginning of the XML item containing the
entire message, reads the message header and checks whether it  is  valid:
„„ If the exchange plan for this message is  defined;
„„ If the sender and recipient of the message are correct;
„„ If the message has a  valid number.
The message number validity is defined by the second parameter value. If the
second parameter has the AllowedMessageNo.Any value, then the message being
read can have any number. If the value of the second parameter is  AllowedMes-
sageNo.Next, then the message number must have the highest number of
all the previous messages incremented by 1. If the second parameter uses the
AllowedMessageNo.Greater value, then the message number must simply be
greater than the highest number of the previous messages. The  default value for the
second parameter is  AllowedMessageNo.Greater.
After this, the beginning of the XML item containing the message body is  read.
If the message is  not valid or a  reading error occurs, an exception is  raised. If no
issues arise, you can start reading the body of the message.
To complete message reading successfully, use the EndRead() method.
This  method reads the end of the XML element item the item body and the end
of the XML item containing the entire message. If everything is  okay, then the
message is  considered received and the message number is  saved as the highest
number of the received messages if it  is  greater than the previous highest number.
The CancelRead() method allows you to cancel message reading at any time.
Chapter 15. Data Exchange Mechanisms 2-769

Below is a typical code fragment showing the use of the ExchangeMes-
sageReader object.
XMLReader = New XMLReader();
XMLReader.OpenFile(MessageFileName);
MessageReader = ExchangePlans.CreateMessageReader();
MessageReader.BeginRead(XMLReader, AllowedMessageNo.Greater);
// Reading the message body
MessageReader.EndRead();

As was earlier noted, the body of the message can, in  principle, contain any infor-
mation, but in  this case the body of a  data change message is  read. Sample code
fragment for reading a  data change message is  provided below.
XMLReader = New XMLReader();
XMLReader.OpenFile(MessageFileName);
MessageReader = ExchangePlans.CreateMessageReader();
MessageReader.BeginRead(XMLReader);
ExchangePlans.DeleteChangeRecords(
MessageReader.Sender, MessageReader.MessageNo);
While CanReadXML(XMLReader) Do
Data = ReadXML(XMLReader);
Data.DataExchange.Sender = MessageReader.Sender;
Data.DataExchange.Load = True;
Data.Write();
EndDo;
MessageReader.EndRead();

The DeleteChangeRecords() method of the ExchangePlansManager object

is  designated for deleting registration records whose receipt has been confirmed.
After reading the body of the message, readable data are read using ReadXML().
Before writing the data in  the database, two properties of the DataExchangePa-
rameters object belonging to the object representing the data read from XML are
modified. In  the Sender property, the data sender node is  specified in  order to
avoid recording changes for communications with the node from which these data
have just been received. Assigning the True value to the Load property signifies
that the record is produced within data loading rather than a standard writing
operation. In  this case some checks are omitted when writing.
Guaranteed Message Delivery
In the above examples of reading and writing data exchange messages
it is expected that some sent messages may be lost for one reason or another.
Therefore, all recorded changes, including those that have been sent, but no receipt
confirmation has been received, are entered into the messages.
A received message is  valid if its number is  greater than the highest number of the
earlier received messages. Deletion of change records occurs only for the messages
with receipt confirmation.
2-770 1C:Enterprise 8.3. Developer Guide

MessageReader.BeginRead(XMLReader);
ExchangePlans.DeleteChangeRecords(
MessageReader.Sender, MessageReader.ReceivedNo);

This logic is typical for data exchange. However, it is possible for message
delivery to be guaranteed. In this case change registration deletion must occur
immediately after successfully writing the message in  order to avoid resending the
changes. A message can only be received if its number is  the maximum number of
the previously received messages incremented by 1.
In this case the code fragment that records the message will look like the following:
XMLWriter = New XMLWriter();
XMLWriter.OpenFile(MessageFileName);
Node = ExchangePlans.RemoteWarehouses.FindByCode(NodeCode);
MessageWriter = ExchangePlans.CreateMessageWriter();
MessageWriter.BeginWrite(XMLWriter, Node);
Selection = ExchangePlans.SelectChanges(Node, MessageWriter.MessageNo);
While Selection.Next() Do
Data = Selection.Get();
WriteXML(XMLWriter, Data);
EndDo;
MessageNo = MessageWriter.MessageNo;
MessageWriter.EndWrite();
ExchangePlans.DeleteChangeRecords(Node ,MessageNo);

The code fragment in  which the message is  received looks like the following:
XMLReader = New XMLReader();
XMLReader.OpenFile(MessageFileName);
MessageReader = ExchangePlans.CreateMessageReader();
MessageReader.BeginRead(XMLReader, AllowedMessageNo.Next);
While CanReadXML(XMLReader) Do
Data = ReadXML(XMLReader);
Data.DataExchange.Sender = MessageReader.Sender;
Data.DataExchange.Load = True;
Data.Write();
EndDo;
MessageReader.EndRead();

Please keep in  mind that the organization of guaranteed message delivery is  quite
complicated and in  most cases it  is  preferable to simply send changes repeatedly
until their receipt has been confirmed.
Collision Resolution
In the above examples of reading and writing messages, we did not take into
account that in  data exchange one item could be modified in  two data exchanging
nodes at the same time. In  this case it  is  impossible to tell which change should be
accepted in  the end. This  situation is  called a  collision.
Chapter 15. Data Exchange Mechanisms 2-771

One of the ways to resolve collisions is  by defining one of the nodes as a  master
and the other as a  slave. In  this situation the change made in  the master node must
be accepted and the change made in  the slave node – rejected.
To implement this, upon receiving the message and before recording the data find
out whether the change of these data has been recorded and, depending on the role
of the node in  this sender-recipient pair, make the decision as to whether data must
be written or not.
An example of using the "master-slave" strategy in  reading messages is  provided
below. Here, to save the role of the node in  the exchange plan, the Master attribute
with the Boolean type has been defined.
XMLReader = New XMLReader();
XMLReader.OpenFile(MessageFileName);
MessageReader = ExchangePlans.CreateMessageReader();
MessageReader.BeginRead(XMLReader);
ExchangePlans.DeleteChangeRecords(MessageReader.Sender, MessageReader.MessageNo);
Sender = MessageReader.Sender;
Master = Sender.Master;
While CanReadXML(XMLReader) Do
Data = ReadXML(XMLReader);
If Master Or
Not ExchangePlans.IsChangeRecorded(Sender, Data)
Then
Data.DataExchange.Sender = MessageReader.Sender;
Data.DataExchange.Load = True;
Data.Write();
EndIf;
EndDo;
MessageReader.EndRead();

Name Space Mapping

When a message is written using the BeginWrite() method of the
ExchangeMessageWriter object, no namespace mappings are defined. At the
same time, a  set of namespaces can be used multiple times for recording separate
data items. In  this case defined mappings of these namespaces occur multiple times
in the body of the message. Therefore, it is important to enter several lines of
code to define the mappings for the most commonly used namespaces after starting
to record the message, but before recording the message body.
An example is  provided in  the fragment below:
XMLWriter = New XMLWriter();
XMLWriter.OpenFile(MessageFileName);
Node = ExchangePlans.RemoteWarehouses.FindByCode(NodeCode);
MessageWriter = ExchangePlans.CreateMessageWriter();
MessageWriter.BeginWrite(XMLWriter, Node);
XMLWriter.WriteNamespaceMapping("xsd", "http://www.w3.org/2001/XMLSchema");
2-772 1C:Enterprise 8.3. Developer Guide

XMLWriter.WriteNamespaceMapping("xsi",
"http://www.w3.org/2001/XMLSchema-instance");
XMLWriter.WriteNamespaceMapping("v8",
"http://v8.1c.ru/data");
Selection = ExchangePlans.SelectChanges(
Node,
MessageWriter.MessageNo);
While Selection.Next() Do
Data = Selection.Get();
WriteXML(XMLWriter, Data);
EndDo;
MessageNo = MessageWriter.MessageNo;
MessageWriter.EndWrite();
ExchangePlans.DeleteChangeRecords(Node ,MessageNo);

In some cases this approach can help to significantly reduce the size of the XML
document containing the data exchange message.

15.3. DISTRIBUTED INFOBASES

15.3.1. General Principles
A distributed infobase is a set of 1C:Enterprise infobases (nodes of the distrib-
uted infobase) that support configuration and data synchronization. A distributed
infobase has a hierarchical structure. Each node of a distributed infobase can
have one master node and any number of slave nodes. The  main node or the
node which does not have a  master node is  called the root node of the distributed
infobase (see the Main database on fig. 305). Each node can only exchange data
with its "neighbors": its master and slave nodes.

Fig. 305.  Distributed Hierarchical Database

Chapter 15. Data Exchange Mechanisms 2-773

Any changes to the configuration are allowed only in  the root node. Subsequently,
they are distributed over the hierarchy, from the root node to its subordinates,
etc. In this manner, the distributed infobase management tool assures the same
configuration for all nodes of the distributed infobase.
Data change is  allowed in  each node of the distributed infobase. Data synchroni-
zation takes place through the distribution of data changes made in  one node to all
structures of the distributed infobase.
When configuring document sequence functions in a distributed infobase, note
that a document's membership in a document sequence makes sense only in a
single node of a  distributed infobase. It  can be a  node where the document was
created or some other node, but in  any case only one. Violating this rule may result
in various problems while you are working with the system, such as failure to
restore the document sequence.
If complete configuration duplication is supported in the framework of all the
distributed infobase, then complete data duplication is  not required. The  content of
data for which changes are transferred in  the framework of the distributed infobase
can be regulated "vertically" (by defining multiple metadata objects for which data
are exchanged) or "horizontally" (by assigning conditions for change transmission
and receipt at the level of individual data items).

15.3.2. Exchange Plans

Exchange plans play a central role in managing distributed infobases. To make
an exchange plan suitable for organizing distributed infobases, set its Distributed
Infobase property at the configuration stage.
The data in  the distributed infobase is  transferred by means of messages provided
by the message infrastructure. As opposed to universal data exchange mechanisms,
the contents of a message transferred between nodes of a distributed infobase
cannot be arbitrary, but rather are regulated by exchange protocols for distributed
infobases.
The data whose changes are exchanged in a distributed infobase is defined by
the exchange plan content. Occurrence of a metadata objects in the exchange
plan content shows that data changes corresponding to the metadata object can be
registered for nodes of this exchange plan. As opposed to universal data transfer
mechanisms, data that can be exchanged within a distributed infobase is highly
limited by the content of its corresponding exchange plan.
To record data changes in a distributed infobase, use the change registration
service. Data items are placed into the message using XML-serialization. In  addi-
tion to data exchange between nodes of the distributed infobase, configuration
changes and some additional auxiliary information can be transferred. Recording
configuration changes and their transfer in  the distributed infobase is  completely
automatic and is  not accessible for users and configuration developers.
2-774 1C:Enterprise 8.3. Developer Guide

As opposed to universal data exchange mechanisms, data exchange message gener-

ation and receipt in a distributed infobase takes place "in a single act", i.e. the
contents of the message are generated using a  single 1C:Enterprise script method.
Similarly, message content is  read using a  single method. In  order to manage the
composition of data entered into the message as well as data read from the message
and entered into the database, the following event handlers can be defined at the
level of individual data items in  the exchange plan module:
„„ OnSendDataToSlave
„„ OnSendDataToMaster
„„ OnReceiveDataFromSlave
„„ OnReceiveDataFromMaster
In this way, universal data exchange mechanisms are nearly completely applied
in  the distributed infobase; however, distributed infobases provide some additional
opportunities.

15.3.2.1. Master and Slave Nodes

As explained above, each node of the distributed infobase can have one master
node and any number of slave nodes (see fig. 306). A node is  considered a  slave
in  relation to its master node and, accordingly, a  node is  a master node in  relation
to its slave nodes. A node that does not have a  master node is  called the root node
of the distributed infobase.
IMPORTANT!
The root node of the distributed infobase is  the only place where you can make
changes to the infobase configuration.
A distributed infobase can be based on several exchange plans with the Distributed
Infobase property set. Interaction in  each "master-slave" node pair is  based on one
of the exchange plans defined in  the configuration. There are no restrictions set for
using a  given exchange plan in  a given infobase node.
Each distributed infobase node only "knows" its "neighbors" (its master and slave
nodes), just like in the universal data exchange mechanisms. In this way, the
complete distributed infobase schema has more than two levels unknown to any
node.

15.3.2.2. Collision Resolution

A typical procedure for handling collisions in distributed infobases is based on
the "master-slave" relationship. This  is  carried out automatically upon receiving
a message. Data item changes made in the master node have a higher priority
than changes made in  slave nodes. Therefore, if the message from the slave node
contains a  data item with modifications registered for that slave node, no action
Chapter 15. Data Exchange Mechanisms 2-775

is  perform – this item is  not entered into the database and the change registration
record is  not deleted.
If the message from the master node contains a  data item with changes that have
been registered for the master node, then this data item is  recorded in  the database
and the change registration record is  deleted.

15.3.2.3. Initial Image of Distributed Infobase Node

Usually in distributed infobases slave nodes originate from the master node.
In  other words, a  new infobase is  created on the basis of the configuration and
data contained in the master node and corresponding to the slave node defined
in  the exchange plan. This  infobase is  called an initial image of the distributed
infobase node.
The following activities occur when creating the initial image:
„„ The unchanged configuration is  transferred to the initial image from the master
node.
„„ Node objects are created in  the initial image's source exchange plan; they are
initialized in  a way that makes additional settings unnecessary before starting
data exchange between the master and slave nodes.
„„ Data are transferred from the master node to the initial image according to the
rules defined in  the exchange plan (the content of the exchange plan and the
OnSendDataToSlave event handler's results).
The procedure for creating an initial image for one node can be repeated over
and over. This is useful in cases when the infobase of a slave node is perma-
nently lost. When creating an initial image, all change registration records for the
corresponding node are deleted and the history of this slave node starts from the
beginning.

15.3.2.4. Data Exchange Messages in  Distributed Infobases

Data exchange messages provided by the message infrastructure are used to transfer
data and configuration changes in a distributed infobase. When using universal
data exchange mechanisms, the configuration developer specifies what and how
is  entered into the message body; for distributed infobases, however, the structure
and data content entered into the message body are specifically defined.
Let us go over the structure of a data exchange message used in a distributed
infobase. Below is  a sample message.
<v8msg:Message xmlns:v8msg="http://v8.1c.ru/messages">
<v8msg:Header>
<v8msg:ExchangePlan>RemoteWarehouses</v8msg:ExchangePlan>
<v8msg:To>Warehouse1</v8msg:To>
<v8msg:From>Office</v8msg:From>
2-776 1C:Enterprise 8.3. Developer Guide

<v8msg:MessageNo>20</v8msg:MessageNo>
<v8msg:ReceivedNo>15</v8msg:ReceivedNo>
</v8msg:Header>
<v8msg:Body>
<v8de:Changes xmlns:v8de="http://v8.1c.ru/dataexchange">
<v8de:Signature>
7b4d5320-f69c-4a7b-9273-ff56607fc8ab</v8de:Signature>
<v8de:Config xmlns:v8md="http://v8.1c.ru/metadata">
<!– Modified configuration objects -->
<v8de:Digest1>88d3f3a6ba3f4df03c7ec00f154837fc</v8de:Digest1>
<v8de:Digest2>00cf636b02a488103a64c7a2cf81069e</v8de:Digest2>
</v8de:Config>
<v8de:Nodes>
<v8de:Node>
<!– Master node data -->
</v8de:Node>
<v8de:Node>
<!– Slave node data -->
</v8de:Node>
</v8de:Nodes>
<v8de:Data>
<!– Modified data items -->
</v8de:Data>
</v8de:Changes>
</v8msg:Body>
</v8msg:Message>

As you can see from the example, all the differences in  the data exchange message
are concentrated in  the body of the message. The  body of the message (the Body
item, associated with the http://v8.1c.ru/messages namespace) contains a single
XML item – Changes belonging to the http://v8.1c.ru/dataexchange namespace.
All data transferred during data exchange in  the distributed infobase is  contained
within this element:
„„ The Changes item can contain four nested items associated with the same
namespace.
○○ The Signature item contains the "signature" of the exchange plan used to
receive the message.
○○ The Config item contains configuration changes as well as data that iden-
tify the status of the configuration.
○○ The optional Metadata items nested in  Config contain changes of indi-
vidual configuration objects. If configuration changes are not transferred
in the message, then the Metadata items are not used. These items can
only be included in  messages transferred from the master node to the slave
node. The  Digest1 and Digest2 items contain numerical signatures for
configuration changes transferred in  the message and for the entire configu-
ration except modifications. The  Digest1 and Digest2 items are included
in  all messages sent from the master node to the slave mode and vice versa.
Chapter 15. Data Exchange Mechanisms 2-777

„„ The Nodes item can only be included in  messages transferred from the master
node to the slave node. This item contains two nested Node items, the first
containing data for the master node (sender) and the second – for the slave
(recipient).
„„ Finally, the Data item contains data item changes transferred in  the message.
Data items are entered into the message using XML-serialization.

15.3.2.5. Exchange Plan Configuration

for Work with Distributed Infobase
As was mentioned above, in  order to use the exchange plan to organize distributed
infobases, its Distributed Infobase property must be set.
When configuring the exchange plan used for organizing the distributed infobase,
the content of the exchange plan must be defined in  order to define the data for
which changes are to be recorded and which can be transferred via data exchange
in  the distributed infobase.
Please note that if a metadata object is included in the exchange content of
a working distributed infobase configuration, it does not cause any automatic
change registration for data items corresponding to this metadata object. Thus, if
a  new object is  added to the content of an exchange plan and the already existing
data needs to be transferred to other nodes, this must be dealt with separately.

15.3.2.6. Exchange Plan Event Handlers

If necessary, the following event handlers can be assigned to the
ExchangePlansObject.<Exchange plan name> object: OnSendDataToSlave,
OnSendDataToMaster, OnReceiveDataFromSlave, OnReceiveDataFrom-
Master. These can manage entries in a message and read individual data items
from the message.
The OnSendDataToSlave event handler can be activated by entering the data
item into the message sent to the slave node of the distributed infobase. The  first
parameter contains the data item itself. The  value of the second parameter, upon
handler activation, is  DataItemSend.Auto, but this value can be modified by
the handler. If the value of the second parameter is still DataItemSend.Auto
after the handler has been executed, this refers to the default behavior (the data
item is entered into the message). If the DataItemSend.Delete value is used
for the second parameter, then an object corresponding to the deleted data item
is included in the message. For database objects, this is an ObjectDeletion
object initialized by the reference to the deleted database object; for record sets –
this is  an empty record set. The  constant record manager is  the only place where
DataItemSend.Delete behavior is  identical to DataItemSend.Auto. But if the
second parameter is  assigned the DataItemSend.Ignore value, then the message
includes nothing that corresponds to the data item transferred in  the first parameter.
2-778 1C:Enterprise 8.3. Developer Guide

The OnSendDataToMaster event handler differs from the previous one only in  that
it  is  used when entering a  data item into a  message sent to the master node.
The OnReceiveDataFromSlave handler is used after reading a data item from
the message and before recording it  in  the database. The  first parameter contains
the data item read from the message. The  second parameter, upon handler invoca-
tion, has the DataItemReceive.Auto value corresponding to the default behavior.
If no data item changes have been registered in this node for the sender node,
then the item is recorded in the database. If there have been recorded changes,
then the item is  not recorded in  the database. The  value of the second parameter
can be modified by the handler. If the second parameter is  assigned the DataIt-
emReceive.Accept value, then the data item is  recorded in  the database regard-
less of whether the changes have been registered for the sender node. If changes
have been registered, then the corresponding change registration record is  deleted.
If the second parameter is assigned the DataItemReceive.Ignore value, then
nothing happens (the item is not recorded in the database and no actions are
performed with the change registration records). The  third parameter manages data
item change recording for the sender node. When the handler is  invoked, this param-
eter is  False. If the handler does not modify this value, then no additional actions are
performed. If the True value is  assigned to the parameter in  the event handler and no
data item changes have been recorded for sender node, registration takes place.
The OnReceiveDataFromMaster event handler has the same set of param-
eters as the previous handler, but differs from it  in  that it  is  used when reading
messages received from the master node of the distributed infobase. Accord-
ingly, there are several different activities carried out when receiving data items.
The  DataItemReceive.Auto and DataItemReceive.Accept values of the
second parameter produce a  similar effect since with the accepted collision resolu-
tion strategy dictates that the slave node data item read from the message must be
recorded in  the database regardless of whether its changes have been registered.
All the other parameter values and activities are similar to those described above.

15.3.3. Working with Distributed Infobase

Working with a  distributed infobase comprises the following main activities:
„„ Creating an initial image for the distributed infobase slave node;
„„ Writing a  data exchange message to be sent to another node of the distributed
infobase;
„„ Reading a data exchange message sent from another node of the distributed
infobase.
Contrary to features provided by universal data exchange mechanisms that cannot
be accessed without the 1C:Enterprise script, the activities listed above can be
executed using the 1C:Enterprise script, the All actions menu of the exchange plan
list form or other tools defined at the configuration stage.
Chapter 15. Data Exchange Mechanisms 2-779

Additionally a  master node can be set and, therefore, retrieved for each node of the
distributed infobase. This  operation cannot be classified as the main operation in  a
distributed infobase, that is  why it  has no corresponding interactive action.

15.3.3.1. Working with Distributed Infobase from 1C:Enterprise Script

Creation of Initial Image for Distributed Infobase Slave Node
The ExchangePlansManager object containing the CreateInitialImage() method
can be used to create an initial image for a  slave node in  a distributed infobase.
The first parameter of this method must be either the value of the
ExchangePlansRef.<Exchange plan name> type representing a refer-
ence to the slave node of the distributed infobase or the value of the
ExchangePlansObject.<Exchange plan name> type representing the node itself.
The second parameter must contain a connection string identifying the infobase
where the slave node initial image is  placed . The  infobase used for creating the
initial image must be empty or non-existent.
As was noted above, the configuration of the infobase is applied to the initial
image without change. Data corresponding to metadata objects that are not in  the
exchange plan are not included in  the initial image. Additionally the OnSendData-
ToSlave event handler is  called for each data item transferred to the initial image.
Accordingly, only data that correspond to the exchange plan rules can be included
in  the initial image.
Two nodes (master node and "this" node) are created and initialized in  the infobase
of the initial image, in  the exchange plan associated with this initial image. There-
fore, immediately after creating the initial image, the slave node infobase is  ready
to exchange data with its master node.
All operations of data transfer to the initial image take place within a  single data-
base transaction of the master node. This  is  necessary for data agreement in  the
initial image. However, if other users use the master node infobase intensively to
modify data, conflicts can occur between the initial image creation transaction and
transactions of other users. In  this case an exclusive mode should be set for the
infobase of the master node before creating an initial image.
NOTE
Infobase operation in  the exclusive mode does not switch the MS SQL database
to the single user mode.

Writing Data Exchange Messages in  Distributed Infobase

As was shown, a data exchange message in a distributed infobase differs from
a  general data exchange message in  its specific body content. The  same differ-
ences can be seen between the procedure for writing data exchange messages in  a
distributed infobase and the general message writing procedure.
2-780 1C:Enterprise 8.3. Developer Guide

The exchange plan manager containing the WriteChanges() method can be

used to write the body of a  data exchange message in  a distributed infobase. Its
first parameter is the ExchangeMessageWriter object that is used to write
the message. This object must have its BeginWrite() method called and its
EndWrite() method still non-invoked.
The optional second parameter specifies the maximum number of data items to
be entered into the message within a  transaction. If 0 is  entered as the parameter
value (used by default), then the entire message is  generated in  one transaction.
This  mode provides the best compatibility for data entered into the message, but
conflicts with transactions of other users are possible. With fewer items processed
in  a transaction, the probability of transaction conflicts is  smaller, but there is  a
greater probability of data incompatibility. Therefore, we recommend that you only
use the default value for the second parameter.
The WriteChanges() method writes the XML Changes item in  the body of the
data exchange message, entering all the necessary information as described above.
Configuration objects and data items with changes registered for the message recip-
ient node are entered into the corresponding message fragments. The  data items
are actually entered into the message by the OnSendDataToMaster (OnSendData-
ToSlave) event handler called by the ExchangePlansObject.<Exchange plan
name> object representing the message recipient node.
A typical code fragment is  given below showing how a  data exchange message
is  written in  a distributed infobase.
XMLWriter = New XMLWriter();
XMLWriter.OpenFile(MessageFileName);
Node = ExchangePlans.RemoteWarehouses.FindByCode(NodeCode);
MessageWriter = ExchangePlans.CreateMessageWriter();
MessageWriter.BeginWrite(XMLWriter, Node);
ExchangePlans.WriteChanges(MessageWriter);
MessageWriter.EndWrite();

Reading Data Exchange Messages in  Distributed Infobase

The exchange plan manager containing the ReadChanges() method can be used to
read the body of data exchange messages in  a distributed infobase.
Its first parameter is an ExchangeMessageReader object used to read the
entire message. This object must have its BeginRead() method called and its
EndRead() method still non-invoked.
TIP
We strongly recommend that you either leave the second parameter blank or use
the default value (AllowedMessageNo.Greater) when using the BeginRead()
method of the ExchangeMessageReader object.
Chapter 15. Data Exchange Mechanisms 2-781

This is all based on the principles for distributed infobases where separate data
exchange messages can be lost, but the same message cannot be received more than
once.
The maximum number of data items read from the message and entered into
the database in one transaction can be used as the optional second parameter.
The  default parameter value is  0, it  signifies that all message reading takes place
in  a single transaction. If message reading occurs in  a single transaction and errors
occur, it  is  not possible for only part of the data items to be read from the message
and entered into the database. But it could be that there are too many database
changes that need to be completed in  one transaction. There is  also an increased
probability of conflicts between the message reading transaction and transactions
of other users. To avoid these problems, the number of data items processed in  a
single transaction can be limited. But if this is  not absolutely necessary, we recom-
mend using the default mode to read all data items in  one transaction.
The following could be a  sequence of activities carried out by the ReadChanges()
method:
„„ The exchange plan "signature" is  read and checked to ensure that the message
was received from the expected exchange plan with the expected configuration.
„„ Configuration changes are read from the message. The  numerical signature of
the configuration is  checked to avoid any possibility that incompatible configu-
rations are located in  the sender node and the current node of the distributed
infobase. For each changed configuration object that was read, the system
checks to see if this configuration object has been actually changed. As
a  reminder, modified configuration objects can only be contained in  messages
sent from the master node to its slave.
„„ Change registration records for messages with confirmed receipt are deleted.
As a  reminder, the maximum number of messages accepted by the sender node
is given in the message header and is accessible through the ReceivedNo
property of the ExchangeMessageReader object.
„„ If it can be established, through checking the numerical signature, that the
configuration in  the current node of the distributed infobase is  different than
the configuration of the sender node, then there are two possible actions:
○○ If the current node is  the master node in  relation to the sender node, then
it  is  not possible to receive this message in  the future under any circum-
stances.
○○ If the current node is  the slave node in  relation to the sender node, then
before continuing to receive the message, the configuration of the database
must be refreshed to the configuration of the sender node. In  updating the
configuration database, configuration objects previously received, saved and
changed are transferred. In  both cases an exception is  raised, with a  corre-
sponding error message. If the message cannot be read in  the first case, then
in  the second case the same message can be successfully read and received
2-782 1C:Enterprise 8.3. Developer Guide

after updating the database configuration which can be accomplished in  the
Designer mode.
„„ If a data exchange message sent from the master node of the distributed
infobase is  being received, then the current node data and the sender node data
are brought into compliance with the data about these nodes contained in  the
data exchange message. If the data exchange message has been received from
the slave node, then these data should not be there (for more information see
page 2-775).
„„ Data items are read from the message and recorded in the database.
The message can only contain data items corresponding to metadata objects
entered into the content of the exchange plan associated with this message.
For each of the data items read from the message, the OnReceiveData-
FromMaster (OnReceiveDataFromSlave) event handler is called for the
ExchangePlansObject.<Exchange plan name> type object. Future activi-
ties in  each of the data items are defined by the handler operation results (for
details see page 2-777).

Receiving and Setting the Master Node in  Distributed Infobase

The root node in  a distributed infobase does not have a  master node. All the other
nodes do, however. In a typical distributed database scenario, setting a master
node is  not mandatory. In  some cases, however, it  may be useful. For example,
the need may arise to assign one of the sub-trees of the distributed infobase to an
independent infobase or to reassign one of the nodes of the distributed infobase.
The SetMasterNode() method from the ExchangePlansManager object has
been designated for setting the master node in  a distributed infobase. This  method
has one parameter. If the ExchangePlansObject.<Exchange plan name> or
ExchangePlansRef.<Exchange plan name> type value is used as the first
parameter, then the Distributed Infobase property must be defined for the exchange
plan with the associated reference or object. In  this case the master node will be
set for the given infobase. If Undefined is  entered as the parameter value, then
master node setting is  cancelled.
To execute this method successfully, there must not be other active users in  the
infobase, including in  the Designer mode.
The MasterNode() method from the ExchangePlansManager object is  used for
receiving the master node. If the current infobase is  not a  distributed infobase node
or if the master node is  not defined (the infobase is  the root node), the method
returns Undefined. If the master node for the infobase is defined, the method
returns the ExchangePlansRef.<Exchange plan name> type value.
NOTE
Master node assignment for an infobase can be cancelled specifying the
/ResetMasterNode parameter in  the command bar in  the Designer startup batch
mode.
Chapter 15. Data Exchange Mechanisms 2-783

15.3.3.2. Interactive Work with Distributed Infobase

As noted above, many of the common actions in a distributed infobase can be
completed interactively using the More (All actions) menu in  the exchange plan list
form (or the icons of the list form command bar). The  corresponding commands
are inserted in  the menu through AutoFill.

Fig. 306.  List of Exchange Plans

To execute each of these commands, select the exchange plan node the command
is  to be applied to in  the list and click the corresponding More (All actions) menu
option.
The More  – Create initial image (All actions  – Create initial image…) command
can be used to create an initial image of the slave node in  a distributed infobase.
After using this menu point, a  dialog appears asking you to select the location type
of the infobase and its parameters (if the image is  to be created in  the client/server
mode). After clicking the Create initial image button, the initial image is  created.
The procedure for creating an initial image interactively is not different from
the procedure used by the CreateInitialImage() method of the Exchan-
gePlansManager object.
The More – Write changes… (All actions – Write changes…) command is  used to
write the data exchange message to a  file. After using this menu point, a  dialog
appears. It prompts the user to enter the number of data items to be processed
in  one transaction. After this, click Write and save to file. It  opens the exchange
file selection dialog box. Select the file and click Open to start data download.
The More – Read changes… (All actions – Read changes…) command is  used to
read data exchange messages from a  file. After using this menu point, a  dialog
box appears. It  prompts the user to enter the number of data items to be processed
in one transaction. After this, click Select file and read changes. It opens the
exchange file selection dialog box. Select the file and click Open to start data
upload.
All data download/upload operations (including creation of an infobase initial
image) are performed on the 1C:Enterprise server side.
2-784 1C:Enterprise 8.3. Developer Guide

15.3.4. Data Exchange Scenarios in  Distributed Infobase

The OnSendDataToSlave, OnSendDataToMaster, OnReceiveDataFromSlave
and OnReceiveDataFromMaster event handlers allow sufficient flexibility
in  managing data exchange in  a distributed infobase. A greater variety of scenarios
is  available when using these handlers. We will go over some of these scenarios
in  this section.

15.3.4.1. Default Behavior

The default behavior of a distributed infobase is the simplest scenario.
This  scenario is  characterized by the following:
„„ Each data item change made in  each of the nodes of the distributed infobase
is  distributed throughout all nodes.
„„ Collisions are resolved based on the "master – slave" node relationship.
For this scenario, all handlers must not modify the parameters transferred to them
or the handlers can be left undefined altogether.

15.3.4.2. Data Distribution in  Slave Nodes

This scenario implies that the following takes place for certain data items:
„„ The entire set of data items exists in  the master node.
„„ The presence of a data item in a slave node is determined by comparing
several data item attributes with attributes of the exchange plan slave node.
„„ Collisions are resolved based on the "master – slave" node relationship.
For this scenario, you must ensure that data items that must not exist in  the slave
node do not end up in  the data exchange message written in  the master node.
Furthermore, if the data item attribute values can be modified in  the slave node,
then you must ensure that change recording in  the master node takes place for those
objects which must not be in  the slave node according to their attribute values.
To get a  greater level of detail, assume an Invoice document is  used as a  data
item type this scenario is  applied to. This  document has a  Warehouse attribute
of the CatalogRef.Warehouses type. The  data exchange is  organized according
to the Warehouses exchange plan. This exchange plan also has a  Warehouse
attribute of the CatalogRef.Warehouses type. This exchange plan has been
used as a  basis for a  distributed infobase where the central office is  the root node
and the warehouses are the slave nodes. Each of the slave nodes in  the exchange
plan has the Warehouse attribute value set so as to indicate each warehouse
corresponding to that node. All of the Invoice documents must exist in  the root
node. They can also exist in  the slave nodes provided that the Warehouse attribute
values in  the document and the exchange plan node are equal.
Chapter 15. Data Exchange Mechanisms 2-785

In order for Invoice documents not to end up in the wrong slave nodes, the
OnSendDataToSlave event handler must look like the following:
Procedure OnSendDataToSlave(DataItem, ItemSend)

DataType = TypeOf(DataItem);
If ValueType = Type("DocumentObject.Invoice") Then

If DataItem.Warehouse <> Warehouse Then

ItemSend = DataItemSend.Delete;
EndIf;
EndIf;
EndProcedure

In the example above, the handler analyzes the data item type and if it  is  equal
to DocumentObject.Invoice, then the Warehouse attribute value of the docu-
ment is compared with the Warehouse attribute value of the exchange plan.
If the attribute values are equal, you do not have to modify the ItemSend parameter
value (upon invocation, this parameter has the DataItemSend.Auto value). In  this
case the document's XML-representation is  entered into the message. If, however,
the attribute values do not match, the ItemSend parameter is assigned the
DataItemSend.Delete value. In this case an XML representation of the
ObjectDeletion object is  placed in  the message and initialized with a  reference
to an appropriate Invoice document.
It may seem strange that when the Warehouse attributes are not equal, the
DataItemSend.Delete value is assigned to the ItemSend parameter instead
of the DataItemSend.Ignore value, as with the DataItemSend.Delete
value selected XML-representation of the ObjectDeletion object is placed
into messages sent to all slave nodes except the node the document is sent to.
Therefore, most of the time ObjectDeletion is  sent to the nodes where the docu-
ment to be deleted has never existed.
This is accurate, but this is the most ordinary case. If, for example, you know
that the Warehouse attribute value of the Invoice document can be set only
when creating the document and cannot be changed in the future, then the
DataItemSend.Ignore value could have been assigned to the ItemSend param-
eter in  this handler.
If the Warehouse attribute value of the Invoice document can be modified in  the
slave node, then the OnReceiveDataFromSlave event handler must be defined
in  the exchange plan as follows:
Procedure OnReceiveDataFromSlave(DataItem, ItemReceive, SendBack)

DataType = TypeOf(DataItem);
If ValueType = Type("DocumentObject.Invoice") Then
2-786 1C:Enterprise 8.3. Developer Guide

If DataItem.Warehouse <> Warehouse Then

SendBack = True;
EndIf;
EndIf;
EndProcedure

In the example above, the handler analyzes the data item type and if it  is  equal
to DocumentObject.Invoice, then the Warehouse attribute value of the docu-
ment is compared with the Warehouse attribute value of the exchange plan.
If the attribute values are equal, then the values of the ItemReceive and Send-
Back parameters do not have to be modified, assigning the default behavior upon
receiving the data item. If the attribute values are not equal, then the SendBack
parameter is assigned the True value. In this case registration of document
changes is  guaranteed and the ObjectDeletion object is  sent to the slave node
with the message if, of course, the Warehouse attribute is not modified in the
master node so that it is equal to the value of the Warehouse attribute corre-
sponding to the exchange plan node.
If the value of the Warehouse attribute in  the Invoice document cannot be modi-
fied after creating the document, then the OnReceiveDataFromSlave handler do
not have to be defined.

15.3.4.3. Non-Standard Collision Resolution

This scenario implies that the following takes place for certain data items:
„„ Each data item change made in  each of the nodes of the distributed infobase
is  distributed throughout all nodes.
„„ Collisions are resolved based on the "master – slave" relationship, with the
slave node having a  higher priority.
This situation is  explained in  the above examples with the Invoice document and
the Warehouses exchange plan.
In this case you must define the OnReceiveDataFromSlave and OnReceiveDa-
taFromMaster event handlers. The  OnReceiveDataFromSlave handler will look
like the following:
Procedure OnReceiveDataFromSlave(DataItem, ItemReceive, SendBack)

DataType = TypeOf(DataItem);
If ValueType = Type("DocumentObject.Invoice") Then

ItemReceive = DataItemReceive.Accept;
EndIf;
EndProcedure
Chapter 15. Data Exchange Mechanisms 2-787

This handler is  quite simple: the data item type is  checked and if the data item
is of the right type, then the DataItemReceive.Accept value is assigned to
the ItemReceive parameter to unconditionally receive data items regardless of
whether its changes have been registered.
The OnReceiveDataFromMaster event handler looks like the following:

Procedure OnReceiveDataFromMaster(DataItem, ItemReceive, SendBack)

DataType = TypeOf(DataItem);
If ValueType = Type("DocumentObject.Invoice") Then

If ExchangePlans.IsChangeRecorded(Ref,DataItem)
Then

ItemReceive = DataItemReceive.Ignore;
EndIf
EndIf;
EndProcedure

This handler is  slightly more complicated. If the data item belongs to the required
type, a  check is  run to see if the changes in  the data item have been registered
in the message sender node. If the changes are have been registered, then the
DataItemReceive.Ignore value is assigned to the ItemRecieve parameter.
As a result, the data item read is not recorded in the database, but the change
recording is  saved to allow you to enter the data item in  the message sent to the
master node.

15.3.4.4. Other Scenarios

The situations described above are only a  few of the possible scenarios for organ-
izing data exchange in  a distributed infobase. Many scenarios are available based
on handlers described above. Some of these can be combinations of methods
described in  this chapter, while others can be fundamentally different.
2-788 1C:Enterprise 8.3. Developer Guide
Chapter  16

XDTO MECHANISM

The XDTO mechanism is  a universal data presentation method that interacts with
various external data sources and software systems.
XDTO stands for XML Data Transfer Objects.
Use the XDTO mechanism to create a  data representation model (model of types
and values) that, on the one hand, provides easy and natural data manipulation
in  the 1C:Enterprise environment and, on the other hand, can be adapted for trans-
parent data conversion to other formats, mostly XML.

Fig. 307.  General XDTO Schema

There are several tasks for which the XDTO mechanism is  used:
„„ Data exchange between the 1C:Enterprise configurations and other consider-
ably different data schemas;
2-790 1C:Enterprise 8.3. Developer Guide

„„ Data exchange based on XML schemas that are not linked to any configuration
(e.g., data exchange with information systems that aren’t built on the basis of
1C:Enterprise);
„„ Organization of work with Web services. Use the XDTO mechanism to describe
the types of parameters and return values of Web services and to manipulate
transferred and returned data.
The XDTO mechanism has the following key properties:
„„ Supports work with XML;
„„ Provides a  typical model of working with data.
At present, data exchange with various software platforms and systems is  imple-
mented using XML: XML documents are used to represent data, whilst an XML
schema is  used to describe formats and data structure. Use the XDTO mechanism
to create XML schemas that are required for data exchange and generate XML
documents for these schemas.
At the same time, you can use the XDTO mechanism to execute these actions
in  the manner which is  usual for most 1C:Enterprise developers.
Developers deal with data objects and types; data objects contain properties for
which values are set, etc. When manipulating data using XDTO, the developer
is to a greater extent isolated from the details connected with how these data
are presented in XML. Of course, it is impossible to eliminate these details
completely, but an important point is that they manifest only where it is really
necessary.

16.1. XDTO FACTORY

The key notion of the XDTO mechanism is  XDTO factory. The  XDTO factory
contains a  description of all the types that a  certain system operates. In  particular,
for any 1C:Enterprise configuration, a  global XDTO factory exists which describes
all the types used in the configuration in XDTO terms (this XDTO factory
is  available through the global context XDTOFactory property).
All descriptions of the types that XDTO factory contains are grouped in  one or
several XDTO packages. To draw an analogy between XDTO and XML, one can
say that the XDTO package corresponds to an XML schema. Therefore, the XDTO
factory can correspond to several XML schemas.
The XDTO factory is  completely self-contained. In  other words, any of the types
registered in  the XDTO factory can only reference the types from the same XDTO
factory.
Generally, the XDTO factory is  created once, on the basis of the descriptions of
all the types that must be registered in  the factory. To create an XDTO factory
with the help of 1C:Enterprise script tools, use the XDTOFactory object wizard
which receives a set of XML schemas contained in the XMLSchemaSet object.
Chapter 16. XDTO Mechanism 2-791

The  scenario of adding XDTO types to the factory one by one or in  groups is  not
supported.
Below is  an example of creating the XDTO factory based on the XML schema
contained in the XML file. Since the XDTO mechanism is an abstraction built
"above" XML, it is necessary to "go through" several levels of work with the
XML data in  sequence to obtain an XML schema from an XML file:
„„ First, low-level reading/writing of XML files;
„„ Then, the XML object model from which you can obtain the 1C:Enterprise
script XMLSchema object that contains the XML schema data.

Fig. 308.  Creation of XDTO Factory

Example:
// Create the XDTO factory based on the XML schema
// contained in  the XML file

// Create a  default XML reader object

NewXMLReader = New XMLReader;

// Open the XML file

NewXMLReader.OpenFile("D:/MySchema.xsd");

// Create the default DOM document builder

NewDOMBuilder = New DOMBuilder;

// Read the XML file to the DOM document

NewDOMDocument = NewDOMBuilder.Read(NewXMLReader);

// Create a  default XML schema builder

NewXMLSchemaBuilder = New XMLSchemaBuilder;

// Get the XML schema from the DOM document

2-792 1C:Enterprise 8.3. Developer Guide

NewXMLSchema = NewXMLSchemaBuilder.CreateXMLSchema(NewDOMDocument);

// Create a  default set of XML schemas

NewXMLSchemaSet = New XMLSchemaSet;

// Add an XML schema to the XML schema set

NewXMLSchemaSet.Add(NewXMLSchema);

// Create the XDTO factory based on the XML schema set

NewXDTOFactory = New XDTOFactory(NewXMLSchemaSet);

In the above example, the XMLReader object is created first and the XML file
located in  the disk is  opened. After that, use the DOM document builder to create
a  DOMDocument object containing the XML file data. Then use the XML schema
builder to create a  new XMLSchema object containing XML schema data on the
basis of the DOM document. Finally, create an empty set of XML schemas, add the
existing XML schema to it  and use the set to create the XDTO factory.

16.1.1. XDTO Factory Retrieval from XSD Schema File

Schemas = New Array;
Schemas.Add("path1");
Schemas.Add("path2");
Packages = New Array;
Packages.Add(XDTOFactory.Packages.Get("Namespace URI for the package from configuration 1"));
Packages.Add(XDTOFactory.Packages.Get("Namespace URI for the package from configuration 2"));
MyFactory = CreateXDTOFactory(Schemas, Packages);

Unlike an arbitrary XDTO factory that a  developer can create, the global XDTO
factory is created automatically by the system when a new infobase is created;
you can add one or several XDTO types to such a  factory. Use the visual construc-
tion tools to add XDTO packages to the Common – XDTO packages metadata tree
branch. All packages in  the global XDTO factory can be divided into three types:
„„ An XDTO package containing the description of the platform types. It  is  iden-
tical for all the configuration in  the 1C:Enterprise system;
„„ An XDTO package containing a  description of the configuration types created
as a  result of metadata editing (creation and modification of properties of cata-
logs, documents, etc.);
„„ A single or multiple XDTO packages described directly in  the configuration
tree, in  the Common – XDTO packages branch.
An XDTO package contains a  description of a  set of types belonging to a  single
namespace, i.e., a package namespace. In addition to the type descriptions, the
XDTO package can contain references to the packages used by this package and
a  list of global package property definitions.
References to other packages are contained in the Dependencies property
of the XDTO package and represent the XDTOPackageCollection object. Pack-
Chapter 16. XDTO Mechanism 2-793

ages from this collection include types from the namespace referenced in this
package.
A package can contain references to global properties from other packages.

16.2. XDTO DATA TYPES

Each of the XDTO data types is  either an XDTO value type or an XDTO object
type. Therefore, the XDTOValueType object is  used to describe the value type and
the XDTOObjectType object is  used to describe the object type.
The XDTOValueType object is used to describe the types of simple indivisible
values in  which no separate constituents can be singled out. Examples of simple
values can be various strings, numbers, dates, etc.
The XDTOObjectType object is  used to describe the types of data instances that
have a certain state presented as a set of property values of this data instance.
Property types of this data instance can be either XDTO value types or XDTO
object types.
Both XDTOValueType and XDTOObjectType have two properties:
„„ Name – the type name;
„„ NamespaceURI – URI of the namespace in  which this type is  defined.
Values of these properties match similar parameters that define this type in the
XML schema. The  type name and namespace URI form a  unique type identifier.
The type name must be defined. The NamespaceURI property can contain an
empty string, though it  is  not recommended.

16.2.1. XDTO Value Type

You can use three methods to define the XDTO value type in  accordance with the
rules for the simple type from the XML schema:
„„ restriction, when a  base type (the BaseType property) and a  set of restrictions
for multiple possible values (the Facets property) is  specified;
„„ merging, when the type is  obtained as a  result of merging several value types
(merged types are enumerated in  the MemberTypes property);
„„ list, when the value is  a list of values (the type of item values making up a  list
of values is  specified in  the ListItemType property).
In addition to the Name and NamespaceURI properties, the XDTO value type
contains the following properties:
„„ BaseType – a base type for this type of XDTO value. The base types can
be inherited from other types of XDTO values. A valid set of inherited type
values is  a subset of possible values of the base type. The  upper level in  the
simple type hierarchy is the predefined anySimpleType type from the
http://www.w3.org/2001/XMLSchema namespace. All the value types are
2-794 1C:Enterprise 8.3. Developer Guide

directly or indirectly inherited from this type. The  types generated by mergers
or lists are always directly inherited from anySimpleType;
„„ Facets – is  a list of facets restricting a  set of valid values towards the base
type. A list of facets is  specified only for the XDTO value types defined by the
restriction of the base type. Every facet is  a pair, a  facet name and a  value.
A list of names for valid facets is  defined. There are certain limits as to how
valid facets can be applied to any type. The  list of facets and their applicability
to a  certain type comply with the rules of the XML Schema (http://www.w3.org/
TR/xmlschema-2/);
„„ MemberTypes is  a list of types that form a  merger. Only XDTO value types
can become unions. If a type is  formed by a merger, the MemberTypes list
contains at least one type. The  Facets list must be empty and the ListItem-
Type property must return an undefined value;
„„ ListItemType – if the XDTO value type is defined by the list, then this
property shows the list item type. Facets and the MemberTypes lists must be
empty.
„„ A list of valid facets (that is  defined by the XDTOFacetType system enumera-
tion):
○○ Length – the length facet. It contains a number of units of length, with
a  unit of length having a  different meaning for different types. For string
and anyURI types, the length contains a  number of characters. For hexBi-
nary and base64Binary types, the length contains a  number of binary data
bytes. For types defined by the list, the length contains a  number of list items;
○○ MaxInclusive – a facet of the maximum including the boundary.
It  restricts the space of the values of this type with the maximum value. Any
value of this type is  either less or equal to the specified value;
○○ MaxLength – maximum length facet. It contains a maximum number
of units of length, with a unit of length having a different meaning for
different types. For the string type, the maximum length contains the
maximum number of characters. For hexBinary and base64Binary types,
the maximum length contains the maximum number of binary data bytes.
For types defined by the list, the maximum length contains the maximum
number of list items;
○○ MaxExclusive – a facet of maximum, not including the boundary.
It  restricts the space of the values of this type with the maximum value. Any
value of this type is  less than the specified value;
○○ MinInclusive – facet of the minimum including the boundary. It  restricts
the space of the values of this type with the minimum value. Any value of
this type is  either more or equal to the specified value;
○○ MinLength – minimum length facet. It contains the minimum number
of units of length, with a unit of length having a different meaning for
different types. For the string type, the minimum length contains the
Chapter 16. XDTO Mechanism 2-795

minimum number of characters. For hexBinary and base64Binary types,

the minimum length contains the minimum number of binary data bytes.
For the types defined by the list, the minimum length contains the minimum
count of list items;
○○ MinExclusive – facet of the minimum, not including the boundary.
It  restricts the space of the values of this type with the minimum value. Any
value of this type is  more than the specified value;
○○ Pattern – the pattern facet. It  contains a  regular expression defining the
space of the values of this type;
○○ Enum – the enumeration facet. It  defines a  set of valid values of this type;
○○ White space – the white space facet. It  can have one of three values:
□□ Preserve – the string can contain any white spaces;
□□ Replace – the string should not contain #x9 (tab), #xA (line feed) and
#xD (carriage return). If they exist, they must be replaced by #x20 (space)
character;
□□ Collapse  – in  addition to the requirements specified for the replace
value, the string should not contain paired #x20 characters (space) or
opening and closing #x20 characters (space);
○○ DigitsTotal – the facet for the total number of digits. It  contains the total
number of digits (integers plus the fractional parts);
○○ FractionPartDigits – the facet for the number of fractional digits.
It  contains the number of digit positions of the fractional amount.
The XDTO infrastructure defines a  set of predefined types for the XDTO values.
This  set matches the set of primitive types as defined in  "XML Schema Part 2:
Datatypes". The predefined types form a hierarchy in accordance with "XML
Schema Part 2: Datatypes". The  type names match the type names of the XML
Schema and belong to the URI of the http://www.w3.org/2001/XMLSchema names-
pace. The  predefined types are automatically registered in  any XDTO factory.

16.2.2. XDTO Object Type

In addition to the Name and NamespaceURI properties, the XDTO object type
contains the following properties:
„„ BaseType – a  base type for this type. It  can only be an XDTO object type.
The  base type of the XDTO object type hierarchy is  the predefined anyType
type from the http://www.w3.org/2001/XMLSchema namespace. All the XDTO
object types are directly or indirectly inherited from this type;
„„ Open – this flag specifies if the XDTO object type is open. This property
shows if the XDTO object instance can contain additional properties that are not
defined in  its type, i.e. it  implements the open content model. It  corresponds
to the use of the following descriptions for this type in the XML schema:
<anyAttribute>, <any>;
2-796 1C:Enterprise 8.3. Developer Guide

„„ Abstract – this flag specifies if the XDTO object type is  abstract. It  corre-
sponds to the use of abstract="true" attribute for this item in  the schema;
„„ Ordered – this flag specifies if the order of items that represent property
values strictly corresponds to the order of properties in  the XDTO object type.
If the xsd:all content model is  set, the order of XML items can be arbitrary.
The  order corresponding to the order of properties in  the type is  also valid, i.e.
if the Ordered property is  False, on input the order of the XML items is  not
controlled, whilst on output it  is  defined by the order of the properties, unless
the Sequenced flag is  True;
„„ Sequenced – this property shows if an instance of the relevant XDTO object
contains an XDTO sequence. This  flag is  True when the order of nested XML
items cannot be uniquely defined by the order of the properties in  the type (e.g.,
the content is  set as <sequence … maxOccurs=10 … > in  the XML schema)
or the mixed="true" attribute is  defined for the corresponding XML type in  the
schema. Use the XDTO sequence to expressly set the order of items in the
XML document. The order of the nested items corresponds to the order of
properties for objects of the types for which the Sequenced property has the
False value;
„„ Mixed – this property shows if mixed content is  defined for this type in  the
XML schema. If the Mixed property setting is  True, then the Sequenced value
is always True, because mixed content cannot be modeled without using an
XDTO sequence;
„„ Properties is  a list of properties defined for this XDTO object type. Each
of the properties is  presented as the XDTOProperty object instance. The  list
contains a  full list of properties including those defined in  the base type.
There is  a predefined XDTO object type with the anyType name and URI of the
http://www.w3.org/2001/XMLSchema namespace. This type is the base type for
any XDTO object type, but it  has no base type of its own. It  is  open, not abstract,
implies a  sequence and has an empty list of properties.
This XDTO object type corresponds to anyType defined in  "XML Schema Part 2:
Datatypes".

16.2.3. XDTO Property

An individual property of an individual XDTO object type is  described using the
XDTOProperty object instance. It  means that one and the same XDTOProperty
object instance cannot be used to describe the properties in  various XDTO object
types and two different properties of one XDTO object type.
The XDTOProperty object contains the following properties:
„„ Name – a property name. The property names should be unique within one
XDTO object type.
Chapter 16. XDTO Mechanism 2-797

When an XDTO data model is  created on the basis of the XSD schema, XDTO
property names are formed on the basis of the names of attributes and elements
described in  that schema. A model type is  built sequentially: an attribute based
list of properties is  created first, then an item based list of properties, in  the
order of the schema declaration. The  name complies with the naming conven-
tions of the script. Characters that are accepted in  an XML-name (".", "-", for
instance) but that are not accepted from the point of view of script names are
replaced with "_". If attribute and item names are copied, a  copy is  assigned
a  name extended with a  numerical suffix (starting from 1).
„„ Type – a property type. It can be either XDTOValueType object instance or
XDTOObjectType object instance;
„„ UpperBound – this property of an XDTO object type can be defined as
containing one or multiple values. The  property is  considered to contain one
value if set to 1. If the UpperBound property is  greater than 1, it  is  considered
to be able to contain multiple values. This  property is  modeled as a  list in  the
object structure (be sure not to confused it  with the list in  the description of
the XDTO value type). The UpperBound property shows the maximum
number of property values. Its value can be greater than 1 only if the property
is  represented as an XML item. The  UpperBound property corresponds to the
xsd:maxOccurs attribute in the XML Schema. A value of -1 corresponds to
unbounded;
„„ LowerBound – the minimum number of property values. The minimum
number of property values can take values of >= 0. Of course, the LowerBound
value must be less than or equal to the UpperBound value (unless
the UpperBound value is  -1);
„„ Nillable – shows if the property can take an undefined value. An unde-
fined property value is represented in XML as the following item:
<elem xsi:nil="true" />. Therefore, the Nillable property set to True can only
be defined for properties with the Item presentation form. The Nillable
property corresponds to the xsd:nillable attribute in the XML Schema.
If UpperBound is  greater than 1, property value list items can have an unde-
fined value;
„„ DefaultValue – default property value. The  default property value can only be
XDTODataValue. This  value must be of the same type as the property type or
of the inherited type. When the XDTO object is  created, the property allowing
the only value takes the default value (the IsSet() method of the XDTO object
returns False for this property). For properties with multiple values, a  list of
values is  initially empty, irrespective of whether the default value is  defined;
„„ Fixed – specifies if the property value is  fixed. If it  is  set to True, the fixed
value can be obtained through the DefaultValue property;
„„ Form is  the form of property presentation in  XML. It  can be Text, Item or
Attribute. If the presentation form is  Attribute or Text, the value of the
2-798 1C:Enterprise 8.3. Developer Guide

UpperBound property cannot exceed 1. If the property has the Text value, then
the value of the LowerBound property is  also equal to 1. Only one property of
an individual type can have its presentation form set to Text, while all the other
properties must have their presentation form set to Attribute;
„„ LocalName is  the local name of an attribute or item used for property presenta-
tion. For properties with the Text presentation form, it  is  an empty string;
„„ NamespaceURI – the URI of the namespace for an attribute or item used for
property presentation. It  is  an empty string if there is  no namespace.

16.3. XDTO DATA INSTANCES

The XDTO data instances can be the XDTO values (XDTOValue) or XDTO objects
(XDTODataObject).

16.3.1. XDTO Value

The XDTO value is  a simple indivisible value in  which no separate constituents
can be singled out. Examples of such simple values can be various strings, numbers,
dates, etc. Instances of simple values are non-mutable.
Use the Create() method of the XDTO factory to create a  new XDTO value:
„„ on the basis of the XDTO value type and value;
„„ on the basis of the XDTO value type and lexical value presentation.
Below are examples of creating an XDTO value.
Example:
GlobalXDTOFactory = XDTOFactory;

// Create an XDTO value from a  reference

CatalogItemRef = Catalogs.Nomenclature.FindByCode("0000001");
CreatedValueXDTOValueType = GlobalXDTOFactory.Type("urn:schemas-v8-1c-ru:config-data", "CatalogRef.Nomenclature");
NewXDTOValue = GlobalXDTOFactory.Create(CreatedValueXDTOValueType,CatalogItemRef);

// Create an XDTO value from a  lexical value presentation
CreatedValueXDTOValueType = GlobalXDTOFactory.Type("http://www.w3.org/2001/XMLSchema","dateTime");
NewXDTOValue = GlobalXDTOFactory.Create(CreatedValueXDTOValueType, "2006-04-20T12:00:30");

You can also obtain a  new XDTO value by reading the XML file.
Example:
GlobalXDTOFactory = XDTOFactory;,

// Read XDTO value data from XML file

NewXMLReader = New XMLReader;
NewXMLReader.OpenFile("D:/Exchange.xml");
…
Chapter 16. XDTO Mechanism 2-799

NewXDTOValue = GlobalXDTOFactory.ReadXML(NewXMLReader);
You can write an XDTO value to the XML file.
GlobalXDTOFactory = XDTOFactory;

// Write XDTO value data to the XML file

NewXMLWriter = New XMLWriter;
NewXMLWriter.OpenFile("D:/Exchange.xml");
…

GlobalXDTOFactory.WriteXML(NewXMLWriter, NewXDTOValue);

16.3.2. XDTO Object

Unlike a  simple value, an XDTO object state is  presented as a  set of values of its
properties. XDTO object instances are mutable, i.e. the state of an XDTO object
can be modified by changing its property values during its lifetime. Any XDTO
data instances (both an XDTO value and an XDTO object) can be used as property
values. When an XDTO object is  a property value, reference to the object is  said
to be a  property value.
Use the Create() method of the XDTO factory to create a  new XDTO object on
the basis of an XDTO object type. After that, assign corresponding values to the
XDTO object properties. Below is  an example of creating an XDTO object and
filling in  its properties.
Example:
GlobalXDTOFactory = XDTOFactory;

// Create an empty XDTO object

CreatedObjectXDTOObjectType =
GlobalXDTOFactory.Type("http://www.1c.ru/demos/goods", "Nomenclature");
NewХDTOObject = GlobalXDTOFactory.Create(CreatedObjectXDTOObjectType);

// Fill in  the XDTO object's property values
CatalogObject = CatalogItemRef.GetObject();

NewХDTOObject.Description = CatalogObject.Description;
NewХDTOObject.FullDescr = CatalogObject.FullDescr;
NewХDTOObject.PurchasePrice = CatalogObject.PurchasePrice;
NewХDTOObject.Barcode = CatalogObject.Barcode;

You can also read the XDTO object data from the XML file or write in  the XML
file, the way it  is  done with the XDTO value.
Example:
GlobalXDTOFactory = XDTOFactory;

// Read XDTO object data from XML file

NewXMLReader = New XMLReader;
2-800 1C:Enterprise 8.3. Developer Guide

NewXMLReader.OpenFile("D:/Exchange.xml");
…

NewХDTOObject = GlobalXDTOFactory.ReadXML(NewXMLReader);
…

// Write XDTO object data to the XML file

NewXMLWriter = New XMLWriter;
NewXMLWriter.OpenFile("D:/Exchange.xml");
…

GlobalXDTOFactory.WriteXML(NewXMLWriter, NewХDTOObject);

When non type-safe data is read, the element is read into XDTOObject of the
xsd:anyType type if there are attributes or child elements. This  is  an open type
with mixed content, so the text in  the element is  interpreted as text and inserted
into the object’s sequence, not as a  value of property __content.
For instance, if an element of type <element attr="attr_value">element value</
element> is  read, text element value can be obtained the following way: XDTOOb-
ject.Sequence().GetText(0).
XDTODataObject contains the following methods:
„„ Type() – returns the type of this XDTO object (XDTOObjectType);
„„ Set(<Expression>), Set(<Property>, <Value>) – use these methods to
specify the property value:
○○ Expression – the Xpath expression specifying the property;
○○ Property – the property name;
○○ Value – the specified property value.
If Expression is  set incorrectly or Value cannot be assigned to the property
(e.g., the type is  incompatible with the property type), an exception is  raised.
If an undefined value is  assigned to the property, whilst the Nillable property
is  False, an exception is  raised. If a  reference to an XDTO object is  assigned
to the property and the reference to this XDTO object is  already a  value of any
other property, this reference stops being the value of the other property.
Chains of references to XDTO objects contained in  the object properties cannot
form cycles. Therefore, when a  reference to an XDTO object is  assigned and
a cycle is formed, an exception is raised. If the property can have multiple
values, you cannot use the Set() method for it as it raises an exception.
When a value is assigned to the property, it is checked to see if this value
type is  allowed for the property. The  value can be assigned if its type matches
the property type, is inherited from the property type or is one of the types
included in a merger. When assigning, if the property presentation form
in  XML is  Text or Attribute, the value is  converted to the property type.
If the presentation form is  Item, the value is  assigned as is.
„„ Get(<Property>), Get(<Expression>) – obtains the property value:
○○ Property – the property name;
Chapter 16. XDTO Mechanism 2-801

○○ Expression – the Xpath expression specifying the property. For proper-

ties with multiple values, this method returns a list of property values:
XDTOList. All operations of property value modification must be executed
through this list.
„„ Reset(<Property>), Reset(<Expression>) – resets the property value:
○○ Property – the property name;
○○ Expression – the Xpath expression specifying the property.
The Reset() method works differently for various properties. For properties
with multiple values (UpperBound > 1), the Reset() method clears up the list
of values.
„„ Set() – checks if the property is  set. Immediately after the object has been
created, all properties have a  False value as a result of the Set() method
execution.
„„ Sequence() – returns a sequence object (XDTOSequence) belonging to this
XDTO object. You can also use the XDTO sequence to modify the object state.
This method returns the XDTO sequence only if the Sequenced property
is  set for the object type.
„„ Validate() – use this method to check if the XDTO object property values
are filled in  correctly. It  also validates the objects referenced in  the property
values. The following issues are checked: whether the number of property
values corresponds to the LowerBound and UpperBound properties; if the order
of the property values in  the XDTO sequence is  correct; and if the Ordered
property has the True value. The check stops when the first error is found.
In  this case an exception is  raised.

16.3.3. XDTO Sequence

Use the XDTOSequence object to model the order of items and text fragments
the way they look in the XML object presentation. The sequence consists of
property-value pairs. Only properties with the Item presentation form can be used
as properties as the order of the attributes is not important. The property in a
property-value pair can also have an undefined value. In  this case this sequence
item is  considered a  text fragment. Sequence items representing text fragments are
only allowed for object types that have a  True value of the Mixed property.
When content of an XDTO object is  formed by means of assigning values to the
properties, the order of assignment is  shown in  the XDTO sequence.
The XDTO sequence contains he following methods:
„„ Count() – returns the number of sequence items;
„„ GetProperty(<IndexOf>) – returns the property that matches the value
located at the IndexOf index. If IndexOf is  beyond the allowed values, an
exception is  raised. The  method can return an undefined value if a  text frag-
ment from the mixed content (text and items) corresponds to the sequence item;
2-802 1C:Enterprise 8.3. Developer Guide

„„ GetValue(<IndexOf>) – returns the value located at the IndexOf index.

If IndexOf is  beyond the allowed values, an exception is  raised;
„„ SetValue(<IndexOf>, <Item>) – sets the Item value at the IndexOf index.
The  IndexOf value must be in  the range of allowed indices. The  item must
have a  valid value for the property it  is  set for or for the text;
„„ Add(<Property>, <Item>) – adds a property-value pair to the sequence.
The  value must be valid for the property;
„„ Add(<Text>) – adds a  text fragment to the sequence. If the Mixed property of
the object type has a  False value, an exception is  raised;
„„ Insert(<IndexOf>, <Property>, <Item>) – inserts a  property-value pair
in the IndexOf position of the sequence. The  IndexOf value must be within
the range of indices. An item in  the IndexOf position and all items with large
index values are shifted one position to the right;
„„ Insert(<IndexOf>, <Text>) – inserts Text in  the IndexOf position of the
sequence. The  IndexOf value must be within the range of indices. An item
in the IndexOf position and all items with large index values are shifted one
position to the right;
„„ Delete(<IndexOf>) – deletes the sequence item in the IndexOf position.
The  IndexOf value must be within the allowed range.

16.3.4. XDTO List

Use the XDTOList object to model a list of values for properties with multiple
values (UpperBound > 1). The  list is  an ordered set of objects that can be both
XDTO values and XDTO objects. If the Nillable property is  True, they can also
include undefined values. However, the IsSet notion is  not defined for list items.
The XDTOList object contains the following methods:
„„ Count() – returns the list size;
„„ Get(<IndexOf>) – obtains the value located at the IndexOf index. IndexOf
must be within the allowed range. Otherwise an exception is  raised;
„„ Set(<IndexOf>, <Item>) – specifies the Item value in  the IndexOf posi-
tion. The  specified value replaces the previous one. IndexOf must be within
the allowed range, whilst Item must be valid for the property. Otherwise an
exception is  raised;
„„ Add(<Item>) – adds the value to the end of the list. Item must be valid for the
property. Otherwise an exception is  raised;
„„ Insert(<IndexOf>, <Item>) – includes the Item value in the IndexOf
position. IndexOf must be within the allowed range, whilst Item must be valid
for the property. Otherwise an exception is  raised. The  value in  the IndexOf
position and all values with large indices are shifted one position to the right;
„„ Delete(<IndexOf>) – deletes the value in the IndexOf position. IndexOf
must be within the allowed range. Any values with large positions are shifted to
the free position.
Chapter 16. XDTO Mechanism 2-803

16.3.5. XРath
Use XPath expressions to navigate the object tree. It is not exactly XPath, but
a  slightly modified XPath subset.
The main construct of this language is  a value path which consists of certain steps.
The path steps are separated by the / (slash) character. The property name or
predefined period (.) and two-period (..) constructs are used as path steps.
An expression shown below means a PropertyName property of the current
object, i.e. the object for which Get() or Set() method has been called.
PropertyName

An expression shown below means that the PropertyName1 property value has
been obtained for the current object and the PropertyName2 property value has
been obtained for the object referenced by the PropertyName1 property value.
PropertyName1/PropertyName2

Therefore, the step marked by a period represents the current object, while two
periods stand for its owner object.
If a  search path starts with the slash character, it  means that the search begins at
the object tree root. If any property is  not found in  the path, an exception is  raised.
If the path includes a  property with multiple values, the result is  the entire list of
values for this property.
For example, if the path below contains the List property with multiple values, the
result of this expression is  the list of values (XDTOList) for this property.
Property/List

To obtain a certain value from this list, specify a 0-based value index over the
period from the property name in  the list as shown below.
Property/List.0

The index must be specified as an integer falling in  the range of allowed indices.
Otherwise an exception is  raised.
A certain list value can be obtained using a  1-based index. The  following construct
can be used:
Property/List[1]

Index values can range from 1 up to the number of list items.

The search functionality is  also available for lists (only for objects). The  search
expression looks like the following:
Property/List[PropertyName='SearchString']

Here List is the property with multiple values. List values are objects having
a  PropertyName property. The  result is  the first object in  the list with the Prop-
2-804 1C:Enterprise 8.3. Developer Guide

erty property value equal to 'SearchString'. If no object is  found, the result
is  an undefined value. Not all list objects can have the PropertyName property.
Sometimes there are no objects with such a  property. The  value with which the
property value is  compared can be specified as a  number, a  logical value (True or
False) or a  string literal.
Property/List[PropertyName!='SearchString']

The above expression is  similar to the previous example, with the exception that
the result is the first object in the list with its PropertyName property value
different from 'SearchString'.
Below is  the definition of the described XPath subset.
<Path>
[/] <Step List>

< Step List >

<Step> [/<Step List>] |

<Step>
<Property Name> [<Qualifier>] | .. | . |

<Property Name>
[<Letter> | _]<Name balance>

<Name Remain>
{<Letter> | <Digit> | _} <Name remain > |

<Qualifier>
.<0-based index> |
[<Property Name>=<Value>] |
[<Property Name>!=<Value>] |
[<1-based index>]

<0-based index>
<Integer without sign>

<1-based index>
<Integer without sign>

<Integer without sign>

<Digit> <Digits>
Chapter 16. XDTO Mechanism 2-805

<Digit>
0|1|2|3|4|5|6|7|8|9

<Digits>
<Digit> <Digits> |

<Value>
<Number> | <String> | <Boolean>

<Number>
[+|-]<Integer without sign>[.<Integer without sign>]

<String>
"<Characters>" | '<Characters>'

<Boolean>
true | false

NOTE
In a  string with double quotation marks (") used as delimiters, double quotation
marks cannot be used among other characters. Similarly, in  a string with single
quotation marks (') as delimiters, single quotation marks cannot be used among
other characters.
When the property value is compared with the value specified as a literal, the
latter is  converted into the property type according to the conversion rules and then
comparison is  performed.

16.4. XDTO-BASED XML SERIALIZATION

Type values of 1C:Enterprise configurations can be serialized directly in/from an
XML file on the basis of XDTO.
Use the XDTOSerializer object that can be obtained using the wizard on the
basis of the existing XDTO factory. Working with XDTOSerializer is  similar to
working with global procedures and functions within XML.
For example, a  reference to the Nomenclature catalog can be serialized into XML
file using software code.
Example:
// Get a  reference to Nomenclature catalog item
CatalogItemRef = Catalogs.Nomenclature.FindByCode("0000001");

// Create XDTO serializer for global XDTO factory
NewXDTOSerializer = New XDTOSerializer(XDTOFactory);

// Create XML writer and open the file

2-806 1C:Enterprise 8.3. Developer Guide

NewXMLWriter = New XMLWriter;

NewXMLWriter.OpenFile("D:/Exchange.xml");

// ...

// Serialize the reference into XML
NewXDTOSerializer.WriteXML(NewXMLWriter, CatalogItemRef, XMLTypeAssignment.Explicit);

Below is  an example of how a  Nomenclature catalog reference can be serialized

from XML file.
Example:
// Create XDTO serializer for global XDTO factory
NewXDTOSerializer = New XDTOSerializer(XDTOFactory);

// Read XDTO object data from XML file
NewXMLReader = New XMLReader;
NewXMLReader.OpenFile("D:/Exchange.xml");
…
// Serialize reference from XML
NewCatalogReg = NewXDTOSerializer.ReadXML(NewXMLReader);

16.5. XML SCHEMA LAYOUT RECOMMENDATIONS

XMLSchemaSet → XDTOFactory → XMLSchemaSet conversion does not gener-
ally result in a set of XML schemas which is equivalent to the source set. Follow
a set of recommendations on the XML schema layout to obtain the resulting set of
schemas which is equivalent to the source set:
„„ Maintain the equivalence between the resulting and the source set of schemas
for XMLSchemaSet → XDTOFactory → XMLSchemaSet conversion.
„„ Use the Validate() method to check if XDTODataObject properties have
been filled in  correctly and ensure that the object representation in  XML corre-
sponds to the XML schema.
„„ Use polymorphism for maximum flexibility and prevention of distortions.
XML schema obtained on the basis of the XDTO factory whose types have
unchanged default values for the parameters responsible for XML data presentation
complies with the above recommendations.
The following list of recommendations is  a set of best practices; follow them to
obtain the best results from different points of view.
XML schema must not contain anonymous types
The following constructs are invalid:
<element name="Person">
<complexType>
<sequence>
<element name="FirstName" type="string" />
<element name="FamilyName" type="string" />
Chapter 16. XDTO Mechanism 2-807

</sequence>
</complexType>
</element>

This fragment should be arranged in  the following way:

<element name="Person" type="tns:PersonType">
<complexType name="PersonType">
<sequence>
<element name="FirstName" type="string" />
<element name="FamilyName" type="string" />
</sequence>
</complexType>

Only sequence model must be used for complex type content

To model the complexType content, use the only sequence block without rede-
fining the default values for minOccurs and maxOccurs attributes.
<complexType name="PersonType">
<sequence>
<element name="FirstName" type="string" />
<element name="FamilyName" type="string" />
</sequence>
</complexType>

The all model does not violate the identity of the source and resulting schemas
during XMLSchemaSet → XDTOFactory → XMLSchemaSet conversion. However,
it has some limitations. Specifically, the maxOccurs attribute in the all model
cannot be greater than 1.
The selection model violates the identity of the source and resulting schemas and
does not make it possible to check whether the object data meets the XML schema
requirements using the Validate() method.
For the same reasons it is not recommended to use multiple content models within
a single complex type or define non-default minOccurs and maxOccurs attribute
values for sequence.
We recommend you present object properties as XML elements
Representation of properties as XML attributes has no influence on the identity of
the source and resulting schemas. However, there are some limitations:
„„ an attribute cannot contain object type values, it  can only contain value types;
„„ an attribute cannot contain properties with multiple values;
„„ value type can get distorted if the property represented as an XML attribute has
polymorph types, i.e. when a  value is  assigned to the property, the value type
is  cast to the property type as the XML item permits specifying the xsi:type
attribute (that specifies the exact property value type) only for property values.
Therefore, it is not necessary to use simpleContent for complexType, as this
model implies use of XML item attributes and text to store values.
We recommend that you do not use similar names to declare an attribute and an
element. For XDTO property naming rules, please see page 2-796.
2-808 1C:Enterprise 8.3. Developer Guide

Mixed content model should be avoided

Using the following construct in a XML schema means that XML item corre-
sponding to the described type can contain text mixed with XML items.
<complexType name="FormLetter" mixed="true">
</complexType>

Information content of this type for the relevant XDTOObjectType is  supported by
setting Sequenced and Mixed properties to True and obtaining XDTO sequence
(XDTOSequence object) for each instance of the corresponding XDTODataObject
object. It  is  much harder to manage the information content of such objects than
that of the objects with the state represented by a  property value set.
Fortunately, in  most cases it  is  not necessary to use mixed content.
The ElementFormDefault property for XML schema must be set to Qualified.
This recommendation is  an element of good style and XDTO follows this style.
16.6. XDTO FACTORY CHECK RULES
A general schema of coding identifiers for XDTO factory check error messages
looks like the following:
xdto-<area>-<section>[-<rule>]: <error description>

„„ <area> is  the check area (XDTO factory, XDTO package, XDTO value type,
XDTO facet or XDTO object type);
„„ <section> is  the number of the section which resulted in  failure after the check;
„„ <rule> is  a section rule;
„„ <error description> is  an error description.

16.6.1. Check Rules for XDTO Factory Proper

When XDTO factory is  checked, error codes are prefixed with model. A general
prefix looks like the following:
xdto-model-<section>[-<rule>]: <error description>

Packages within the model should have unique namespace URIs – duplicate pack-
ages are not allowed in  the model.
Import directives should determine non-empty namespace URIs of imported packages.
Package import directives should define the existing type packages.
Type packages defined in  the model should meet the package check rules.
16.6.2. XDTO Package Check Rules
When XDTO packages are checked for correctness, error codes are prefixed with
package. A general prefix looks like the following:
xdto-package-<section>[-<rule>]: <error description>
Chapter 16. XDTO Mechanism 2-809

XDTO package should have the NamespaceURI property set.

Types defined in  the XDTO package can have references only to the types speci-
fied in  the list of imported types (Dependencies property).
Import directives should meet the following criteria:
„„ Import directives should determine XDTO packages which cannot contain any
import directives pointing to this XDTO package – loops are not allowed for
imported directives.
„„ Import directives should determine the non-empty NamespaceURI property of
the imported XDTO package.
„„ Import directives should define the existing XDTO packages.
Package properties should meet the following criteria:
„„ names of package properties should be set and non-empty;
„„ names of package properties should be unique within the XDTO package;
„„ package property type should be set and defined;
„„ package property types should be defined in  the package or its dependencies;
„„ setting a  name and an anonymous definition for the global property type is  not
allowed;
„„ package property cannot reference definition of another package property;
„„ package property cannot define limits for the number of property values;
„„ package property can have only Attribute or Item presentation form.

16.6.3. XDTO Value Type Check Rules

When XDTO value types are checked for correctness, error codes are prefixed with
valueType. A general prefix looks like the following:
xdto-valueType-<section>[-<rule>]: <error description>

General rules for checking the XDTO value type:

„„ If the type is  defined within a  type package, the following requirements should
be met:
○○ XDTO value type should have the set Name property containing a non-
empty name.
○○ XDTO value type name should be unique within the XDTO package (among
all the XDTO package types).
„„ If the type is  defined within another value type definition or within object type
property definition, the following requirements should be met:
○○ Name property of type definition should not be set.
○○ XDTO value type cannot contain self-references in  the base type, list item
type or any of the union types in  the entire hierarchy.
2-810 1C:Enterprise 8.3. Developer Guide

Rules for checking the base type – BaseType property:

„„ If the BaseType property is  not set:
○○ If the Variant property is  not set and the MemberTypes property is  not set
or the Variant property is  set to Atomic:
□□ If the TypeDefinition property contains a single value, this type
definition is  used for the atomic base type.
□□ Otherwise anySimpleType of the XML schema namespace
(http://www.w3.org/2001/XMLSchema) is  considered the base type.
„„ If the BaseType property is  set, the following requirements should be met:
○○ Base type should comply with the second rule of XDTO package check.
○○ Base type should be the XDTO value type.
„„ Base type cannot be this XDTO value type.
Rules for checking the list item type – the ListItemType property:
„„ If the ListItemType property is set in the type definition, the following
requirements should be met:
○○ List item type should comply with the second rule of XDTO package check.
○○ List item type should be the XDTO value type.
○○ List item type cannot be this XDTO value type.
○○ XDTO value type that represents an item list should be either atomic or
XDTO value type union consisting only of atomic XDTO value types.
„„ If the Variant property is not set and the BaseType property is set or the
Variant property is  set to List:
○○ If the TypeDefinition property contains a  single value, this type defini-
tion is  used for the anonymous list item type.
○○ Otherwise the ListItemType property value is determined based on the
corresponding property of the base XDTO value type.
Rules for checking the union type – MemberTypes property:
„„ If the MemberTypes property is  set in  the XDTO type definition, the following
requirements should be met:
○○ Union type should comply with the second rule of XDTO package check.
○○ Union type should be the XDTO value type.
○○ Union type should not be this XDTO value type.
○○ XDTO value union type should be either an atomic type or a  list.
„„ If the Variant property is not set and the BaseType property is set or the
Variant property is  set to Union:
○○ The TypeDefinition property contains values that are anonymous defini-
tions of union types.
○○ Otherwise the MemberTypes property value is  determined on the basis of
the MemberTypes property value of the base XDTO value type.
Chapter 16. XDTO Mechanism 2-811

Inheritance of XDTO value types is  considered correct if the following require-
ments are met:
„„ The following conditions should be met for atomic types of XDTO values
(ListItemType and MemberTypes properties are not set after execution of the
rules for checking the list item type and the union type):
○○ Base XDTO value type should be atomic, i.e. its ListItemType and
MemberTypes properties should not be set.
○○ Ancestor of the XDTO value type should be one of primitive types of the
XML schema namespace (http://www.w3.org/2001/XMLSchema).
○○ Content of the facets specified in  the XDTO value type description should
match the list of valid facets for the primitive type which is  the ancestor of
this XDTO type.
○○ Value of each facet specified in  the XDTO value type should comply with
the limitation rules for effective values of similar facets of the XDTO base
types.
For the list item types (the ListItemType property is  set after execution of
the rules for checking the list item type and the union type):
□□ Base XDTO type cannot be a  union type, i.e. its MemberTypes property
should not be set.
□□ If the ListItemType property of the XDTO base type is  set, its value
should determine the base type for the list item type defined in  the
ListItemType property of this XDTO value type.
□□ If anySimpleType is the base type of the XML schema namespace
(http://www.w3.org/2001/XMLSchema), it is allowed to use only the
Whitespace facet out of the facet list.
□□ Otherwise only the following facets can be defined: Pattern, Enum,
Length, MinLength, MaxLength and Whitespace.
□□ Value of each facet in  the type should comply with the limitation rules for
the effective value of similar base-type facets.
○○ For union types (the MemberTypes property is  set after execution of rules
for checking the list item type and the union type):
□□ anySimpleType of the XML schema namespace (http://www.w3.org/2001/
XMLSchema) or a  union type can be the base type, i.e. the base type
should have the MemberTypes property set.
□□ If the base type is  a union type, the following requirements should be
met:
 The number of union types for the base type should not be greater
than the number of union types for this type.
 Union types should be descendants of their corresponding base type
union types, in  accordance with the union type list order.
2-812 1C:Enterprise 8.3. Developer Guide

 If anySimpleType of the XML schema namespace

(http://www.w3.org/2001/XMLSchema) is  the base type, facet defini-
tion is  not allowed.
□□ Otherwise it  is  possible to define only Pattern and Enum facets.
„„ Value of each facet in  the type should comply with the limitation rules for the
effective value of similar base-type facets.
„„ If the Variant property (contents model) for the type definition is  set, it  must
not conflict with the type definition:
○○ If the property is  set to Atomic, the type has an atomic contents model and
should comply with xdto-valueType-5.1 rules.
○○ If the property is set to List, the type has a List contents model and
should comply with xdto-valueType-5.2 rules.
○○ If the property is  set to Union, the type has a  Union contents model and
should comply with xdto-valueType-5.3 rules.

16.6.4. XDTO Object Type Check Rules

When XDTO object types are checked for correctness, error codes are prefixed
with objectType. A general prefix looks like the following:
xdto-objectType-<section>[-<rule>]: <error description>

General rules for checking the XDTO object type:

„„ If the type is  defined within a  type package, the following requirements should
be met:
○○ XDTO object type should have the set Name property containing a non-
empty name.
○○ The name of the XDTO object type should be unique within the package
(among all the package types).
„„ If the type is defined within an object-type property, the following require-
ments should be met:
○○ Name property of type definition should not be set.
Rules for checking the base type – BaseType property:
„„ If the BaseType property is  not set, anyType of the XML schema namespace
(http://www.w3.org/2001/XMLSchema) is  considered the base type.
„„ If the BaseType property of the XDTO object type is  set, it  should meet the
following conditions:
○○ Base type should comply with the second rule of XDTO package check.
○○ Base type should be the XDTO object type.
○○ Base type cannot be this XDTO object type.
Chapter 16. XDTO Mechanism 2-813

Each property of the XDTO object type should meet the following conditions:
„„ Property name should be defined.
„„ Property name cannot be empty.
„„ Property name should be unique for the XDTO object type.
„„ If the Type property is  set, it  should meet the following conditions:
○○ Type name should define the existing XDTO object type or XDTO value
type.
○○ Property type should comply with the second rule of XDTO package check.
„„ Property cannot contain an anonymous type definition.
„„ If the Type property is  not set, it  should meet the following conditions:
○○ If the property has an anonymous type definition, the property type is  the
type corresponding to this definition.
○○ Otherwise anyType of the XML schema namespace (http://www.
w3.org/2001/XMLSchema) is  considered the property type.
„„ If a default value is specified for the property, the following requirements
should be met:
○○ DefaultValue property type should be the XDTO property type.
○○ Lexical representation of the default value should match the space of values
for the XDTO property type.
„„ The following requirements should be met:
○○ If the LocalName property of the XDTO property is not set, the Name
property of the XDTO property is  used as the local name of the XML repre-
sentation for the XDTO property.
○○ If the NamespaceURI property of the XDTO property is  not set, URI of
the XML namespace for XDTO property representation is determined as
follows:
□□ If the XML representation form of XDTO property (Form property)
is  Item, it uses URI of the namespace for the type containing this
property.
□□ Otherwise URI of namespace for the XDTO property XML representation
is  considered non-existent.
○○ XDTO property should be unique for the XML representation within the
XDTO object type.
○○ If the XDTO property has the Text XML representation form, the following
conditions should be met:
□□ Name and URI of the namespace should be undefined or empty.
□□ XDTO object type properties can include XDTO properties with the
Attribute XML representation form.
□□ If XDTO property has the Item XML representation form, it is not
allowed to use XDTO properties with the Text XML representation form
for this XDTO object type.
2-814 1C:Enterprise 8.3. Developer Guide

○○ Value of the lower boundary for the number of LowerBound property values
can be a  non-negative integer. LowerBound value should be less than or
equal to the value of the upper boundary for the number of UpperBound
property values if it  does not equal -1.
○○ UpperBound value can be a  non-negative integer or -1. If it  is  -1, it  means
the number of property values is  unlimited.
○○ If the Fixed property value is  set, DefaultValue must be set by default
and correspond to the XDTO property type value space.
○○ If a  reference to the global property definition is  set, the following require-
ments should be met:
□□ The property definition cannot override values of the global definition
properties.
□□ The global property referenced by the property definition should be
defined within the current package or its dependency packages.
„„ If XDTO object type properties include an XDTO property with the same name
or XML representation as the base type property, the inheritance type is  deter-
mined as limitation inheritance. The following conditions should be met for
this inheritance type:
○○ The following conditions should be met for each XDTO property:
□□ Base type should define the XDTO property with the same name – the
overridden property.
□□ If the base type determines the order of properties (Ordered property),
position of the overridden property should be identical to the position of
the property in  the inheriting type.
□□ XML representation form of the overridden property and property of this
type should be the same.
□□ XML representation local name of the overridden property and property
of this type should be the same.
□□ XML representation namespace URI of the overridden property and
property of this type should be the same.
○○ If the overridden property determines a  fixed value:
□□ The fixed value cannot be removed from the inheriting type.
□□ The fixed value in  the base type and the inheriting type should be the
same.
□□ The lower limit for the number of property values should be less than or
equal to the lower limit for the number of overridden property values.
□□ The upper limit for the number of property values should be greater than
or equal to the upper limit for the number of overridden property values.
□□ The property type should be a descendant of the overridden property
type.
Chapter 16. XDTO Mechanism 2-815

□□ If the base type does not have mixed content (Mixed property), it  is  not
possible to set the mixed model for the inheriting type.
□□ If the base type has a  fixed order of properties (Ordered property),
it  is  not possible to change the order in  the inheriting type.
□□ If the base type does not specify a sequence (Sequenced property),
it  is  not possible to specify it  in  the inheriting type.
□□ If the base type does not have an open content model (Open property),
it  is  not possible to set the open content model for the inheriting type.
Otherwise (see rule 4) the inheriting type is  determined as enhancement inherit-
ance. The  following conditions should be met for this inheritance type:
„„ If the base type content model is  mixed (Mixed property), it  is  not possible to
change the mixed model in  the inheriting type.
„„ If the base type property order is not fixed (Ordered property), it is not
possible to change the order in  the inheriting type.
„„ If the base type specifies a  sequence (Sequenced property), it  is  not possible
to disable the sequence in  the inheriting type.
„„ If the base type has an open content model (Open property), it  is  not possible
to change the content model for the inheriting type.
The following conditions should be met for any inheritance type:
„„ If the content model is  mixed (Mixed property), it  is  not possible to disable
sequences (Sequenced property).
„„ If the content model is open (Open property), it is not possible to disable
sequences (Sequenced property).

16.6.5. Facet Limitation Rules

When XDTO facets are checked for correctness, error codes are prefixed with
facet. A general prefix looks like the following:
xdto-facet-<section>[-<rule>]: <error description>

Rules for the Length facet:

„„ Facet value should be the same as the efficient value of the base type facet.
„„ If the MinLength facet value is  set, it  should meet the following conditions:
○○ MinLength facet value should be less than or equal to the Length facet
value.
○○ In the base type, Length facet values should not be set or the MinLength
facet value should be the same as the effective value of the base type
MinLength facet.
„„ If the MaxLength facet value is  set, it  should meet the following conditions:
○○ MaxLength facet value should be less than or equal to the Length facet value.
2-816 1C:Enterprise 8.3. Developer Guide

○○ In the base type, Length facet values should not be set or the MaxLength
facet value should be the same as the effective value of the base type
MaxLength facet.
Rules for the MinLength facet:
„„ Facet value should be greater than or equal to the effective facet value in  the
base class.
„„ Facet value should be less than or equal to the MaxLength facet effective value.
Rules for the MaxLength facet:
„„ Facet value should be less than or equal to the effective facet value in  the base
class.
„„ Facet value should be greater than or equal to the MinLength facet effective
value.
Rules for the Whitespace facet:
„„ If the base type facet effective value is  Сollapse, the facet cannot have any
other value.
„„ If the base type facet effective value is  Preserve, the facet cannot have Replace
value.
Rules for the MinInclusive facet:
„„ Facet value should be less than the MaxExclusive facet effective value of this
type.
„„ Facet value should be greater than or equal to the base-type facet effective
value.
„„ If MaxInclusive facet value is  set, it  should be less than or equal to the base
type MaxInclusive facet effective value.
„„ If MinInclusive facet value is set, it should be greater than the base-type
MinInclusive facet effective value.
„„ If MaxExclusive facet value is set, it should be less than the base-type
MaxExclusive facet effective value.
Rules for the MinExclusive facet:
„„ It is  not permitted to set the MinExclusive and MinInclusive facet values
in  the type definition.
„„ If the MaxInclusive facet value is  set, the MinExclusive facet value should
be less than the MaxInclusive facet value for this type.
„„ Facet value should be greater than or equal to the base-type facet effective
value.
„„ If the MaxInclusive facet value is  set, it  should be less than or equal to the
base-type MaxInclusive facet effective value.
„„ If the MinInclusive facet value is  set, it  should be greater than or equal to the
base-type MinInclusive facet effective value.
Chapter 16. XDTO Mechanism 2-817

„„ If the MaxExclusive facet value is set, it should be less than the effective
MinInclusive base-type facet value.
Rules for the MaxInclusive facet:
„„ Facet value should be greater than or equal to the MinInclusive facet value for
this type.
„„ If the MaxExclusive facet value is set, it should be less than the effective
value for the base type.
„„ If the MinInclusive facet value is  set, it  should be greater than or equal to the
effective value for the base type.
„„ If the MinExclusive facet value is  set, it  should be greater than the effective
value for the base type.
Rules for the MaxExclusive facet:
„„ It is  not permitted to set the MaxExclusive and MaxInclusive facet values
in  the type definition.
„„ If the MinExclusive facet value is  set, the MaxExclusive facet value should
be greater than the MinExclusive facet value for this type.
„„ Facet value should be less than or equal to the effective base-type facet value.
„„ If the MaxInclusive facet value is  set, it  should be less than or equal to the
effective value for the base type.
„„ If the MinExclusive facet value is  set, it  should be greater than the effective
value for the base type.
„„ If the MinInclusive facet value is  set, it  should be greater than the effective
value for the base type.
Rules for the DigitsTotal facet:
„„ Facet value should be less than or equal to the effective base-type facet value.
Rules for the FractionPartDigits facet:
„„ Facet value should be less than or equal to the effective DigitsTotal facet
value.
„„ Facet value should be less than or equal to the effective base-type facet value.
2-818 1C:Enterprise 8.3. Developer Guide
Chapter  17

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 inde-
pendent 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 distrib-
uted 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 refer-
ences 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 corre-
sponding service.
2-820 1C:Enterprise 8.3. Developer Guide

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. Adminis-
trator Guide".
Creation of a  Web service involves:
„„ adding the Web service configuration object to the Metadata Tree;
„„ describing operations provided by the Web service;
Chapter 17. Web Service Mechanism 2-821

„„ 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 opera-
tions 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 SessionParam-
etersSetting() 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 SessionPa-
rametersSetting event handler.

SessionParametersSetting event of the session module is  called in  the privi-
leged 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 param-
eters 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/XMLS-
chema 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.
2-822 1C:Enterprise 8.3. Developer Guide

„„ 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 names-
pace;
○○ 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 names-
pace;
„„ 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();
Chapter 17. Web Service Mechanism 2-823

// 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.
2-824 1C:Enterprise 8.3. Developer Guide

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 refer-
ring 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
Chapter 17. Web Service Mechanism 2-825

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 unde-
fined value.
2-826 1C:Enterprise 8.3. Developer Guide

„„ 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 transac-
tion 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 opera-
tions.
„„ Publishing file name – name of the Web service description file located on the
Web server.
The Module button opens the Web service module editor.
Chapter  18

JOB MECHANISM

The job mechanism is  designed to run application functionalities as scheduled or

asynchronously.
The job mechanism has the following tasks:
„„ defining scheduled procedures at the stage of system configuration
„„ performing specified actions as scheduled
„„ calling a  specified procedure or function asynchronously, i.e. without waiting
for its completion
„„ tracking progress for a  job and getting its completion status (a value that indi-
cates successful or unsuccessful completion)
„„ obtaining a  list of current jobs
„„ waiting for completion of a  single or multiple jobs
„„ managing jobs (cancelling, locking execution, etc.)
The job mechanism includes the following components:
„„ scheduled job metadata
„„ scheduled jobs
„„ background jobs
„„ Job Scheduler
Scheduled jobs are used to perform application tasks as scheduled. These jobs are
stored in  the infobase and based on metadata defined in  the configuration. Sched-
uled job metadata contain such data as description, method, use, etc.
A scheduled job has a  schedule that defines when the job-related method is  to be
executed. As a  rule, schedules are set up in  the infobase, though they can also be
created at the configuration stage (e.g., for predefined scheduled jobs).
Background jobs are used to perform application tasks asynchronously and are
implemented through the 1C:Enterprise script.
2-828 1C:Enterprise 8.3. Developer Guide

Job Scheduler is used to plan execution of scheduled jobs. The Job Scheduler

runs periodic checks for each scheduled job to see if the current date and time
matches the job schedule. If it  does, the Scheduler assigns this job to be executed.
For this purpose the Scheduler creates a  background job that is  actually respon-
sible for processing.
18.1. BACKGROUND JOBS
Background jobs are useful for complex calculations that might take a  long time
to obtain the result. Using the job mechanism tools these calculations can be done
asynchronously.
Background jobs have an associated method invoked when a  job runs. Background
job method can be any procedure or function of a  non-global common module that
can be called at the server. Background job parameters can take any values that
can be passed to the server. Background job parameters must match parameters of
the called procedure or function exactly. If a  function is  used as a  background job
method, its return value is  ignored.
A background job can have a key – any application value. The key applies
constraints to background job startup – only one background job with a  specific
key value and method name (comprising module name and procedure/function
name) can run at one time. The  key allows the user to group background jobs with
identical methods based on an application characteristic. Thus, only one back-
ground job can be executed within a  certain group.
Background jobs can be created and managed programmatically within any connec-
tion. Any user can create background jobs. In  this case the job is  performed under
the account of the user that created it. A user with administrative permissions or
the user that created the jobs can get them and wait for their completion within any
connection.
Background jobs are purely session objects; they do not belong to any user sessions.
For each job, a  special system session is  created under the account of the calling
user. Background jobs have no saved state.
They can generate other background jobs. This  feature can be used in  the client/
server mode to run concurrent cluster working processes for complex calculations,
thus accelerating the overall calculation process. Concurrency is implemented
through generating multiple child background jobs and waiting for their completion
in  the parent background job.
Background jobs can place data in  temporary storages of calling sessions (see page
2-849). This  functionality can be used, for example, to transfer a  generated report
or data to be processed to the calling session. Data transfer from a  calling session
to a  background task session is  not supported.
Successfully completed or failed background jobs are stored for 24 hours and then
are deleted. If the number of completed jobs is  over 1000, the oldest jobs are also
deleted. This  quantity relates to one base for a  file-based variant of an infobase,
and to one cluster for a  client/server variant.
Chapter 18. Job Mechanism 2-829

18.2. SCHEDULED JOBS

Scheduled jobs are used to perform periodic or one-time actions in compliance
with a  schedule.
These jobs are stored in  the infobase and based on scheduled job metadata defined
in  the configuration. Metadata specify such scheduled job parameters as invoked
method, description, key, availability for use, predefined flag, etc. When a  sched-
uled job is  created, the user can additionally specify its schedule (in the metadata),
method parameter values, user name to be used to run the job, etc.
Scheduled jobs can be created and managed programmatically within any connec-
tion. They are available only to users with administrative permissions.
NOTE
In the file-mode scheduled jobs can be created and edited without launching the
Job Scheduler.
Scheduled jobs have an associated method invoked when a  job runs. Scheduled job
method can be any procedure or function of a  non-global common module that can
be called at the server. Scheduled job parameters can take any values that can be
passed to the server. Scheduled job parameters must match parameters of the called
procedure or function exactly. If a  function is  used as a  scheduled job method, its
return value is  ignored.
A scheduled job can have a key – any application value. The key applies
constraints to scheduled job startup as out of all the scheduled jobs associated with
the same metadata object only one job with a  specific key value can run at one
time. The  key allows the user to group scheduled jobs associated with the same
metadata object based on an application characteristic. Thus, only one scheduled
job can be executed within a  certain group.
Predefined scheduled jobs can be created at the configuration stage. Predefined
scheduled jobs are no different from ordinary scheduled jobs, except that they
cannot be explicitly created and deleted. If scheduled job metadata have the prede-
fined flag, the predefined scheduled job is auto-generated in the infobase when
the configuration is  updated. If the predefined flag is  unchecked, the predefined
scheduled job is  automatically removed from the infobase when the configuration
is  updated. Initial values for predefined scheduled job properties (e.g., schedule)
are set in  metadata. The  user can modify these values when working in  the appli-
cation. Predefined scheduled jobs have no parameters.
Schedule for a  scheduled job defines when the job is  to be launched. Schedules
can specify:
„„ start and end date and time for a  job;
„„ execution period;
„„ week days and months to run a scheduled job etc. (see the "1C:Enterprise
Script Description").
2-830 1C:Enterprise 8.3. Developer Guide

Sample Schedules for Scheduled Jobs

Schedule Parameter values
Every hour, only one day DaysRepeatPeriod = 0
RepeatPeriodInDay = 3600
Each day once a  day DaysRepeatPeriod = 1
RepeatPeriodInDay = 0
One day, one time DaysRepeatPeriod = 0
Once in  two days, once a  day DaysRepeatPeriod = 2
Each day, every hour from 01.00 to 07.00 DaysRepeatPeriod = 1
RepeatPeriodInDay = 3600
BeginTime = 01.00
EndTime = 07.00
Each Saturday and Sunday at 09.00 DaysRepeatPeriod = 1
WeekDays = 6, 7
BeginTime = 09.00
Each day for a  week, skip a  week DaysRepeatPeriod = 1
WeeksPeriod = 2
At 01.00 once BeginTime = 01.00
Last date of each month at 09.00 DaysRepeatPeriod = 1
DayInMonth = -1
BeginTime = 09.00
Fifth day of each month at 09.00 DaysRepeatPeriod = 1
DayInMonth = 5
BeginTime = 09.00
Second Wednesday of each month at 09:00 DaysRepeatPeriod = 1
WeekDayInMonth = 2
WeekDays = 3
BeginTime = 09.00

It can be checked whether a  job is  executed for the specified date (ExecutionRe-
quired() method of JobSchedule object). Scheduled jobs are always performed
under a specific user account. If a scheduled job user is not specified, the job
is  executed with the default role rights assigned for the configuration. If the default
role is  not assigned for the configuration, the job is  executed with no access rights
restriction.
Scheduled jobs are performed using background jobs. When the Scheduler deter-
mines that a scheduled job should be performed, it creates a background job
based on this scheduled job that performs the further processing. If the scheduled
job is  already running, it  is  not launched again regardless of its schedule.
Scheduled jobs can be re-launched. It is particularly important when execution
of the scheduled job method needs to be guaranteed. A scheduled job needs to
be re-launched if it fails or if a working process (client/server mode) or client
process (file-mode version) used to execute the scheduled job fails. A scheduled
job can specify the number of times that job needs to be restarted (Restart count
on failure property), and an interval between restarts (Restart interval on failure).
When a  scheduled number of restarts has been completed, start attempts stop until
the time for starting that scheduled job comes around once again (as per schedule).
Chapter 18. Job Mechanism 2-831

A restart counter resets, and in case of failure of a scheduled job, the restart
process starts again.
When implementing the re-launched scheduled job method, please bear in  mind
that re-launching the job executes it  from the beginning rather than the point of
failure.

18.3. RUNNING BACKGROUND JOBS IN  FILE MODE

AND CLIENT/SERVER MODE
Background job mechanisms are different for file mode and client/server mode.

18.3.1. File Mode

Background and scheduled tasks are performed by client applications or web server
extensions. Background tasks are performed in  the client application that initiated
the launch of a background task. Background tasks are executed sequentially,
i.e. only one background task can run in  one client application. If a  web server
is  used, the sequential execution of background and scheduled jobs is  supported
for each infobase accessed via this web server.
The behavior of background and scheduled jobs in  a file-based variant is  distin-
guished by the following:
„„ Information on background tasks called with the help of script methods or
executing reports is  only available in  the client application that executed the
tasks. Information is  not stored after a  client application completes its work.
„„ Information on background tasks initiated by scheduled jobs is  available to all
client applications. It  is  saved between launches.
„„ Scheduled jobs are executed by one client application. You can disable
launching scheduled tasks by a  certain client application or enforce a  certain
client application to function as a  scheduled job executor. This  can be done
through the following:
○○ /AllowExecuteScheduledJobs command line parameter for thick and
thin client applications.
○○ allowexecutescheduledjobs attribute of element point of default.vrd
publication file (see book "1С:Enterprise 8.3. Administrator Guide") if the
infobase is  published on a  web server.
„„ Scheduled jobs are the first ones to be executed (in the launching order) by
the client application that is not prohibited from performing scheduled jobs.
When a client application session is over, the execution is handed over to
a  client application that is  still running. If a  client application is  launched and
the requirement to execute scheduled jobs is  explicitly set, scheduled jobs are
executed by this client application regardless of whether there are other client
applications (including web server extensions).
2-832 1C:Enterprise 8.3. Developer Guide

„„ Scheduled jobs are executed by a  web server extension until it  serves at least
one client session.
„„ Scheduled jobs are processed once every 60 seconds.

18.3.2. Client/Server Mode

The client/server mode runs background jobs using the Job Scheduler that is  phys-
ically located in  the cluster manager. The  Scheduler gets the least busy working
process for all the queued background jobs and uses it  to run the appropriate job.
The  working process executed the job and notifies the Scheduler of the results.
In the client/server mode, execution of scheduled jobs can be locked. Locks are
used in  the following cases:
„„ An explicit lock of scheduled jobs is  applied to the infobase. The  lock can be
set in  the cluster console.
„„ A connection lock is  applied to the infobase. The  lock can be set in  the cluster
console.
„„ SetExclusiveMode() method with True parameter has been called from the
1C:Enterprise script.
„„ In some other cases (e.g., when the database configuration is  updated).

18.4. CREATION OF SCHEDULED JOB METADATA

Before a  scheduled job can be programmatically created in  the infobase, it  has to
have a  metadata object created.
To create a  metadata object for a  scheduled job, select Add in  the configuration
tree Common branch for the Scheduled jobs branch.
Scheduled jobs have a  set of properties described below.
Method name – name of the scheduled job method.
Key – a  random string value to be used as the scheduled job key.
Schedule – scheduled of a  scheduled job. To generate a  schedule click Open and
select the required values in  the schedule form that opens.
On the General tab, specify job start and end dates and repeat mode (see fig. 310).
The Daily tab contains job schedule for a  day (see fig. 311).
The following can be included in  the schedule:
„„ job start and end time
„„ job end time that forces the job to complete
„„ job repetition period
„„ duration of pause between repetitions
„„ duration of execution
Chapter 18. Job Mechanism 2-833

Fig. 310.  Common Schedule

Fig. 311.  Schedule for a  Day

You can combine these conditions at will.

The Weekly tab contains job schedule for a  week.

Fig. 312.  Schedule for a  Week

2-834 1C:Enterprise 8.3. Developer Guide

Check the days of week when the job has to be executed. If it is necessary
to execute the job repeatedly, specify repetition interval in  weeks. For example,
if a  job is  executed once in  two weeks, repetition value is  2.
The Monthly tab contains job schedule for a  month.

Fig. 313.  Schedule for a  Month

Check the months when the job has to be executed. If necessary, you can define
specific day of week or month for execution. You set it  as a  value from the begin-
ning or end of week or month.
Use – if it  is  set, the job is  performed according to the schedule.
Predefined – if it  is  set, the job is  predefined.
Restart count on failure – number of attempts to restart at abortion.
Repeat interval on failure – interval between attempts to restart at abortion.
Creation of Sample Background Job "Update Full Text Search Index":
BackgroundJobs.Execute("UpdateFullTextSearchIndex");

Creation of Sample Scheduled Job "Restore Sequences":

Schedule = New JobSchedule;
Schedule.DaysRepeatPeriod = 1;
Schedule.RepeatPeriodInDay = 0;
Job = ScheduledJobs.CreateScheduledJob("RestoreSequences");
Job.Schedule = Schedule;
Job.Write();
Chapter  19

FULL-TEXT DATA SEARCH

MECHANISM

1C:Enterprise mechanism of full-text data search allows the user to search the data-
base using search operators (AND, OR, NOT, NEAR, etc.).
The full-text search mechanism is  based on using two components:
„„ full-text index created in  the database and periodically updated as necessary;
„„ full-text search tools.

19.1. GENERAL INFORMATION ON FULL-TEXT INDEXING

Data of the following configuration objects can serve as full-text search objects:
„„ exchange plans
„„ catalogs
„„ documents
„„ charts of characteristic types
„„ charts of accounts
„„ charts of calculation types
„„ information registers
„„ accumulation registers
„„ accounting registers
„„ calculation registers
„„ business processes
„„ tasks
Each of the listed configuration objects has the Full Text Search property that
enables or disables full-text indexing for the object data.
2-836 1C:Enterprise 8.3. Developer Guide

Changes of full-text search objects are registered by 1C:Enterprise in  a change log.
The  log is  written when objects are recorded in  the database. Only objects set up
for full-text indexing are included in  change files. If transaction rollback cancels
object recording to the database, entry in  the change log remains unchanged.
Full-text indexing is performed in the privileged mode (in the server context)
and does not require exclusive lock of the database. During full-text indexing
change registration files are read and changed objects are obtained from the data-
base, words are transliterated and Latin letters in  words are replaced by Cyrillic
characters (however, the index stores both forms of the word). Only the following
attribute types can be indexed:
„„ string
„„ date
„„ number
„„ reference types
„„ value storage
The following items are added to the full-text index for each object and attribute:
„„ name of metadata objects or its attribute
„„ synonym of metadata objects or its attribute (in all configuration languages)
„„ presentation of metadata object (in all configuration languages)
Standard and user attributes are indexed in all languages allowing to perform
searches in  all configuration languages (e.g., in  Russian and in  English).
NOTE
The Cyrillic letter "ё" in  all words is  replaced by the Cyrillic letter "е" for full-
text indexing and search purposes.
For information about file location for the full-text search index see
"1C:Enterprise 8.3. Administrator Guide".
Full-text indexing generates the main index; subsequent database changes create an
additional index that contains information about data modified after the last update
of the main index.
Search in  the main index is  very efficient, while search in  the additional index
takes more time. This is why the indexing process features an index merge
functionality that adds the last data change results to the main index. Please note,
however, that this operation might take a long time (if the main index if big);
therefore, it  is  recommended to run it  when the load on the system is  minimal (at
night time or week-ends).
Full-text search is  user-initiated in  the client application context and is  executed
in  the server context. It  means search is  performed at the client machine in  the
file-mode version and at the 1C:Enterprise server cluster – in the client/server
mode.
Chapter 19. Full-Text Data Search Mechanism 2-837

Full-text data search is  based on user rights (including access right restrictions at
the level of database records and fields). Search results can include misspelt words:
for example, if a  word contains Cyrillic "ь" instead of Latin "m" or is  spelt as
"systeь" instead of "system" due to indeliberate language change, these words are
also added to the search results.
Search results are returned in  chunks of the size defined when executing the full-
text search command.
Results are ranked on the basis of the following priorities:
„„ metadata object "weight": the more object attributes reference this object, the
bigger is  its "weight";
„„ date of the object (newer objects are displayed at the beginning).

19.2. USE OF FULL-TEXT SEARCH MECHANISMS

Full-text data search is  performed using the 1C:Enterprise script tools.
FullTextSearch global context property returns the full-text search manager –
FullTextSearchManager object.
Methods of the full-text search manager can be used to:
„„ obtain information about full-text index state
„„ run full-text indexing
„„ initiate the full-text data search process
The following methods are used to obtain information about full-text index state:
„„ GetFullTextMode() – returns True if full-text search is allowed or False
otherwise;
„„ UpdateDate() – date of the last time when all data were indexed and there was
no information about new objects for indexing;
„„ IndexTrue() – returns True if the full-text search index entirely corresponds to
the infobase current state;
„„ IndexUpdateComplete() – returns True if full-text index merge is not
required.
The following methods are used for full-text indexing:
„„ SetFullTextMode() – sets full-text search mode (Allow or Deny). If search
is  disabled, calling this method with the True parameter automatically clears
the existing full-text index.
„„ UpdateIndex() – updates the full-text search index. If there are no indices,
this method re-indices the entire database. Indexing conditions are passed as
method parameters:
○○ AllowMerge – if the True value is  passed, main and additional indices are
merged;
2-838 1C:Enterprise 8.3. Developer Guide

○○ InPortions – the True value indicates that indexing is  to be performed

in  portions of 10 thousand objects. After indexing data of a  single portion
the process is  completed. Indexing time per portion is  strongly dependent
on data. For example, the process lasts 3 to 5 min. in  the standard configu-
ration "Manufacturing Enterprise Management".
„„ ClearIndex() – removes all full-text index files. This method is recom-
mended when data have been updated in  their entirety or close to that (e.g.,
when the infobase has been loaded). After the index is  cleared, indexing should
be performed (if required).
To start full-text data search process, the CreateList() method is used. Two
parameters are passed to this method:
„„ SearchString – a  string with the search expression;
„„ PortionSize – a  number specifying the count of objects to be returned in  a
single portion of full-text search.
For a  description of search expression syntax see page 2-1207.
The CreateList() method returns FullTextSearchList object that can
be used to perform full-text search and obtain its results. This object can be
used many times to perform search with various criteria. The SearchString
and PortionSize object properties allow the user to change used search expres-
sion and size of received data portion.
To perform a full-text search and obtain the first results, use the FirstPart()
method that fills the list with the first found items according to the portion size.
To obtain subsequent full-text search results, use the NextPart() and Pre-
viousPart() methods that can receive the current start position as their parameter
and fill the full-text search list with search results. If CurrentStartPosition
is not specified, the start position value of the FullTextSearchList object
is  used instead; this value can be retrieved using the StartPosition() method.
Using parameters is  better as it  accelerates full-text search.
The Count() method contains the number of items in  the current part (for the last
part it  can be less than equal to the portion size) and the TotalCount() method
contains total count of found items.
The NextPart() method fills the list with subsequent items according to
the portion size. The current position increases by the number of data items
in  the received part. If there are no data to receive the next portion (end of data
is  reached), it  raises an exception that can be processed by the Try … Except …
EntTry clause.
The PreviousPart() method fills the list with previously found items according
to the portion size. If there are no data to receive the next portion (beginning of data
is  reached), it  raises an exception that can be processed by the Try … Except …
EntTry clause.
The TooManyResults() method returns True if quantity of search results was
truncated in  order to improve performance. This  can impact search exactness (not
Chapter 19. Full-Text Data Search Mechanism 2-839

all objects are found). It is recommended to analyze the value returned by this
method when receiving the last portion of found data in  order to inform the user
that not all results have been received from the database.
The GetDescription property contains a  flag used to get search results descrip-
tion. If it  is  set to True, the Description value is  filled for each search result
providing context for found words. However, if this property is set to False,
search is  performed faster.
Full-text search list is  a collection of full-text search list items that can be tabbed
through using the operator For Each … From … Do.
Each full-text search list item is  represented by FullTextSearchListItem object
and has the following properties:
„„ Value – identifies data (object or set of records) containing the search expres-
sion;
„„ Metadata – metadata object describing data containing the search expression;
„„ Presentation – text presentation of found object;
„„ Description – contains pairs <attribute>:<value> (beginning on a new
line) where:
○○ <attribute> is  object attribute whose value contains the search expression;
○○ <value> is  value of this attribute.
Using the GetRepresentation() method you can obtain search results as
XMLReader object or a  string with HTML-text where found words are highlighted
by HTML means (bold font and background color).

19.3. USE OF ADDITIONAL DICTIONARIES

Additional morphological and synonym dictionaries for full-text search extend
system dictionaries and can contain special terms and words used when working
with the configuration.
Binary data templates, text templates and string-type or ValueStorage type constants
can be used as additional dictionaries. You can specify additional dictionaries in  the
Additional full-text search dictionaries property of the root metadata object.
Content of dictionaries should like the following:
<?xml version="1.0"?>
<Dictionary>
<Words>
<lemma>mouse</lemma><forms>mice mouse's</forms>
<lemma>ox</lemma><forms>oxen</forms>
</Words>
<Synonyms>
<item>error bug failure</item>
<item>stream thread</item>
</Synonyms>
</Dictionary>
2-840 1C:Enterprise 8.3. Developer Guide

Dictionary Item
It is  used to store dictionary. A dictionary can have two sections:
„„ additional words (lemmas) and their forms
„„ sets of synonyms
Words Item
It contains words in  the following format:
„„ lemma item stores the main form of the word (nominative case);
„„ forms item contains other case-forms of the word.
Fuzzy search is  not used by default. To run a  fuzzy search use the * operator.
Example: searching for mous* finds mouse, mouse and mice.
Synonyms Item
It stores sets of synonyms. Each set is  enclosed in  item tags.
To include synonyms in  full-text search, use the ! operator. Searching for !error
finds error, bug and failure. For a  description of search expression syntax see
page 2-1207.
Synonyms and Words items can be ordered randomly.
The system loads dictionaries when search is first called or indexing
is  performed. If errors are found in  the template, filling dictionaries is  stopped
at the error position.
If the dictionary has been modified, re-start the client for the system to use the
updated dictionary. However, index is  not auto-updated and has to be rebuilt
manually, although searches use new dictionaries.
Chapter  20

TEMPORARY STORAGE
MECHANISM, WORKING
WITH FILES AND PICTURES

1C:Enterprise features a  temporary storage mechanism that can store data bound
to sessions. Another mechanism is used to work with files; it supports file
exchange between the infobase and client application. This  mechanism is  specifi-
cally designed for thin and web clients and accounts for Web browser-specific
constraints applied to working with files.
The temporary storage mechanism combined with the file use mechanism provides
a set that can be used to place locally stored data to the infobase temporary
storage, transfer this information from the temporary storage to the database and
retrieve it to the user machine. The most common application tasks solved by
these mechanisms are storing extra information, such as product pictures, contract-
related documents, etc. Temporary storage and file use mechanisms are often used
together, though they can also be used individually.

20.1. TEMPORARY STORAGE

Temporary storage is a specialized information storage where a value can be
placed. Its main purpose is  storing information temporarily before it  is  transferred
to the database during client/server interaction.
Temporary storage might be required, for example, if Web browser operation
model dictates the need to transfer user-selected file directly to the server without
storing it at the client. During transmission the file is placed in the temporary
storage and can later be used to write an object to the database.
2-842 1C:Enterprise 8.3. Developer Guide

Temporary storage can be used as a  universal storage with controlled data lifetime:
„„ If data placed in the temporary storage are bound to a form, their lifetime
depends on the form lifetime. When the form object is  removed, the storage
is  cleared of all related information.
„„ If data placed in  the temporary storage are not bound to a  form, the storage
is  cleared in  the following cases:
○○ the next form request;
○○ the next server call from client common module;
○○ context and out-of-context client calls from the form;
○○ server call from command module. If the server is  called to place a  value
in  the temporary storage, clearing is  not performed. The  storage is  cleared
after the call has completed.
It means one or more values can be placed in the temporary storage and used
in  the next call. After the value is  used, but before the server call has completed,
the value is  automatically deleted.
The most typical application task solved by temporary storage is  providing access
to files or pictures before object is  recorded in  the infobase, e.g., in  an item form.
Data placed in  the storage are identified by a  unique address that can later be used
in  write, read or delete operations. This  address is  returned by methods that write
values to the temporary storage. A separate method of the 1C:Enterprise script
can be used to determine if the passed address points to the data in  the temporary
storage.

20.2. WORKING WITH FILES AND TEMPORARY STORAGE

This section describes the most common applications of temporary storage and file
use mechanisms.

20.2.1. Saving Data from File in  Temporary Storage

20.2.1.1. Single File Placement
PutFile() method places a  file from a  local file system to the temporary storage.
This  method can receive a  temporary storage address to be used for the file. If the
address is  undefined or is  an empty string, a  new address is  created and returned
by the method through a  special parameter.
If interactive work mode parameter is  True, the method displays a  standard file
selection dialog box where the user can select a  file to be placed in  the storage.
In  this case the method also returns address for the selected file.
The method returns False if the user cancels operation in  the file selection dialog
box in  the interactive mode.
Chapter 20. Temporary Storage Mechanism, Working with Files and Pictures 2-843

20.2.1.2. File Set Placement

PutFiles() method places multiple files to the temporary storage within a  single
call. This  method can be used in  different ways:
„„ by generating a  list of files to be added, e.g., when files to be placed in  the
infobase are preliminarily selected;
„„ by passing file search mask to the method, e.g., when all files of a  certain type
(e.g., all pictures) need to be placed in  the infobase;
„„ by passing a predefined FileDialog object to the method in the open file
mode.
Upon completion this method can return a  list of added files.
// FileList – attribute of ValueList type form
// Containing a  list of files to be added

FileArray = New Array;

For each ListItem From FileList Do

FileArray.Add(NewTransferableFileDescription(ListItem, ));

EndDo;

PlacedFiles = New Array;
Result = PutFiles(FileArray, PlacedFiles, ,False,UUID);

NOTE
To use the PutFiles() method enable an extension for working with files in  the
web client (see page 2-851).

20.2.2. Data Placement in  Temporary Storage

PutToTempStorage() method is similar to PutFile(), except that data to be
written in  the temporary storage are represented as values rather than a  file system
path. Similarly, if no existing temporary storage address is specified, a new
address is created. The address is returned as function result. Like files, data
always belong to a  form and are automatically deleted after form removal.

20.2.3. Data Retrieval from Temporary Storage

When writing an object to the infobase, the user might want to retrieve data from
the temporary storage and place them, for example, in  infobase object attribute.
A special GetFromTempStorage() method can be used for this purpose.
This method extracts data from the temporary storage and returns them in its
execution result. To retrieve data the user needs to specify their address in the
temporary storage. This address is returned by successfully completed methods
that place data in  the temporary storage (see previous sections).
2-844 1C:Enterprise 8.3. Developer Guide

NOTE
When you retrieve values from a temporary storage to the server, note that
they are obtained via references. In  fact, this reference points to a  value stored
in  cache. The  value will be stored in  cache and then written to disc and removed
from cache within 20 minutes of it  being placed in  the storage or after it  is  last
called. The  next time you call the value, it  will be downloaded from disc and put
into cache again.

20.2.4. Data Deletion from Temporary Storage

After data are saved in  an infobase object attribute, they can be removed from the
temporary storage. DeleteFromTempStorage() method can be used for deletion
purposes. This  method receives a  temporary storage address as its parameter.

20.2.5. Address Check for Temporary Storage Membership

An address can point to either the temporary storage or an infobase attribute. Use
IsTempStorageURL() method to check the address type.
It checks if the passed address points to the temporary storage. It  returns True if
the address belongs to the storage.

20.2.6. Attribute Address Retrieval

After data are placed in  an infobase object attribute, the user might want to access
them using file methods.
However, before retrieving data, for example, from the attribute, it  is  necessary to
obtain the attribute address. A special GetURL() method can be used for this purpose.
It can use source parameters to return value address in  the infobase. To achieve
this pass an object key (it can be a  reference to the object or an information register
record key) and attribute name to the method. If address for a  value stored in  a
tabular section attribute is  required, add the tabular section name and a  period (.)
to the attribute name parameter.
Example:
Goods.Image

20.2.7. File Retrieval from Infobase

20.2.7.1. Single File Retrieval
GetFile() method gets an infobase file and saves it in the user's local file
system. The  first parameter defines file address in  the infobase object attribute or
temporary file storage. Data is  not saved if the user on behalf of whom the oper-
ation is  performed lacks View rights to an infobase object attribute. The  second
Chapter 20. Temporary Storage Mechanism, Working with Files and Pictures 2-845

parameter specifies where the file is  to be saved. A path is  required in  the non-in-
teractive mode. This  parameter is  optional in  the interactive mode.
By default this method runs in  the interactive mode. In  other words, it  generates
a  dialog box where the user selects an action for the retrieved file: execute it  or
save in  the user-selected file system location. If the interactive mode is  selected,
but File Name parameter is  not specified, the open file operation is  unavailable.
This method returns a  Boolean value. False means the user has cancelled the
operation in  the save file dialog box in  the interactive mode.

20.2.7.2. File Set Retrieval

GetFiles() method can be used to get and save multiple files stored in the
infobase in  the user's local file system. A list of downloaded files is  passed as the
method parameter.

// FileList – a  list of values with references to items

// of catalog with files to be downloaded
// Value list presentation is  the loaded file name

FileArray = New Array;

For each ListItem From FileList Do

File = New File(String(ListItem.Value));

ReceivedFile = New TransferableFileDescription;
ReceivedFile.Name = ListItem.Presentation;
ReceivedFile.Location = GetURL(ListItem.Value, "Data");
FileArray.Add(ReceivedFile);
EndDo;

ReceivedFiles = New Array;

Result = GetFiles(FileArray,ReceivedFiles,DownloadedFilesPath,False);

If NOT Result Then

Message = New UserMessage;

Message.Text = "Error getting files!";
Message.Message();
EndIf;

Upon completion this method can return a  list of downloaded files with their full
names.
NOTE
To use the GetFiles() method enable an extension for working with files in  the
web client (see page 2-851).
If the Name property of the TransferableFileDescription object contains
an absolute path to a file, the file is saved in this path with no regard to the
FileLocation parameter.
2-846 1C:Enterprise 8.3. Developer Guide

The local file system path or a FileDialog object can be used as the
FileLocation parameter in directory selection mode or file selection mode.
If a  FileDialog object is  set as the FileLocation parameter in  file save mode:
„„ The dialog will be called for every sent file, except files for which the Name prop-
erty of the TransferableFileDescription object contains an absolute path.
„„ The value of the Name property of the TransferableFileDescription object
will be used as the initial file name in  the dialog.
„„ If saving is cancelled for any file, the Name property of the Transferab-
leFileDescription object will contain an empty string.
„„ The GetFiles() method returns True if at least one file is successfully
received.
„„ Note that files are actually received after the user responds to prompts to specify
the name and path of all received files.
„„ If the user on behalf of whom the GetFiles()method is executed lacks
View rights to at least one object attribute of an infobase from which files are
received, the entire operation fails.
Example:
TranserredFiles = New Array;
Details = New TransferableFileDescription("Details", AddressFile);
TranserredFiles.Add(Details);

FileChoice = New FileDialog(FileDialogMode.Save);

FileChoice.Title = "Save Archive";
FileChoice.Extension = "zip";
FileChoice.Filter = "Archive(*.zip)|*.zip|All files|*.*";
FileChoice.FilterIndex = 0;

GetFiles(TranserredFiles, , FileChoice, False);

If interactive mode is selected for file directory selection, the web client also
prompts the user to confirm that files with absolute paths are to be saved. If files are
saved non-interactively (directory path is  specified in  the appropriate parameter),
the query is  executed for the entire list of files to be saved.

20.2.8. Example of File Method Use

// Obtain file from disk in  interactive mode
// and place it  in  temporary storage.
&AtClient
Procedure SelectFileFromDiskAndWrite()

Var SelectedName;
Var TempStorageURL;

NewObject = Object.Ref.IsEmpty();
Chapter 20. Temporary Storage Mechanism, Working with Files and Pictures 2-847

If PutFile(TempStorageURL, "", SelectedName, True) Then

Object.FileName = SelectedName;
PutObjectFile(TempStorageURL);

EndIf;

EndProcedure

// Copy file from temporary storage to attribute

// of catalog, write object, delete file from temporary
// storage.
&AtServer
Procedure PutObjectFile(TempStorageURL)

CatalogItem = FormAttributeToValue("Object");
BinaryData = GetFromTempStorage(TempStorageURL);
CatalogItem.FileData = New ValueStorage(BinaryData, New Deflation());

File = New File(CatalogItem.FileName);

CatalogItem.FileName = File.Name;
CatalogItem.Write();

Modified = False;
DeleteFromTempStorage(TempStorageURL);
ValueToFormAttribute(CatalogItem, "Object");

EndProcedure

// Read file from attribute and store it

// in  local disk in  interactive mode.
&AtClient
Procedure ReadFileAndSaveToDisk()

Address =GetURL(Object.Ref,"FileData");
GetFile(Address, Object.FileName, True);

EndProcedure

20.2.9. Enabling Bulk File Operations

When certain operations are executed in the web client, you might need to get
permission for some file operations. For example, should you need to receive
a  document from an infobase and then open the saved document using the associ-
ated application.
To do this, you have to answer the question about document saving and starting the
application. More operations will cause more prompts to the user.
You can use the RequestUserPermission() method to reduce the number
of prompts. When this method is used, a list of all operations to be executed
is  shown to the user, and the system requests permission to perform a  group of
operations. If the user allows it, the requested operations will be executed without
2-848 1C:Enterprise 8.3. Developer Guide

additional user prompts. If the permission is  denied, operations will be executed
normally: one prompt per request.
NOTE
To use the RequestUserPermission() method in  the web client, you need to
connect the files operations extension (see page 2-851).
Let's take a  look at an example of the code:
If AttachFileSystemExtension() Then
Ref = GetURL(Object.Ref, "FileData");

// Generate description of the passed files (in this case one file)
UploadingFiles = New Array;
Details = New TransferableFileDescription(Object.FileName, Ref);
UploadingFiles.Add(Details);

// Prepare object for receiving information about received files
UploadedFiles = New Array;

// Define other parameters of methods
StorageDirectory = "c:\temp";
Interactively = False;
UploadedFileName = StorageDirectory + "\" + Object.FileName;

// Prepare description of methods for receipt of permissions
Methods = New Array;
Methods.Add(New Array);
Methods[0].Add("GetFiles");
Methods[0].Add(UploadingFiles);
Methods[0].Add(UploadedFiles);
Methods[0].Add(StorageDirectory);
Methods[0].Add(Interactively);
Methods.Add(New Array);
Methods[1].Add("RunApp");
Methods[1].Add(UploadedFileName);

If Not RequestUserPermission(Methods) Then

DoMessageBox("User declined the permission request.");

Return;

EndIf;

GetFiles(UploadingFiles, UploadedFiles, StorageDirectory, Interactively);
RunApp(UploadedFileName);

Else

DoMessageBox("The operation is  not supported. The  File Operations extension is  not installed.");

EndIf;
Chapter 20. Temporary Storage Mechanism, Working with Files and Pictures 2-849

We should note some of the specifics of using the RequestUserPermission()

method:
„„ Permission is  requested only for the following methods:
○○ GetFiles()
○○ PutFiles()
○○ FindFiles()
○○ RunApp()
○○ FileCopy()
○○ MoveFile()
○○ DeleteFiles()
„„ Permission is  requested for a  specific set of method parameters. When the file
method is  actually executed, the parameter values will be different from those
that were permitted. This  permission will not be valid and the user will receive
a  separate prompt to confirm the operation.
„„ If you need to perform two or more similar operations with a  file (even with the
same set of parameters), you should specify the corresponding number of items
in the RequestUserPermission() method parameter array. For example, if
you need to get the same file from an infobase twice and place it  in  a fixed file
system location, request two operations.
„„ If permission is  requested for an operation that is  related to execution of an
interactive operation (such as the GetFiles() function receiving a  FileDi-
alog object as the parameter), such an operation is  excluded from the request.
Received permissions are saved until the allowed call is  executed or 1C:Enterprise
script execution has been completed.
NOTE
In a  thin and a  thick client, the RequestUserPermission() method always
returns True without user interaction.

20.2.10. Working with Temporary Storage in  Background Job

Temporary storage mechanism allows passing data from background job to the
initiating session. To do this, use the PutToTempStorage() method to place an
empty value in  the temporary storage in  the parent session. Then pass the resulting
address to the procedure through background job parameters. If the retrieved
address is  passed to the PutToTempStorage() method in  the background job, the
value is  copied to the parent session with this address.

20.2.11. Address Support in  Picture Box

Field form element of Image field type supports display of picture set by value
address (value can be a  picture or binary data) in  the temporary storage or data-
base.
2-850 1C:Enterprise 8.3. Developer Guide

For this purpose the Data property of the form element should be assigned a  string-
type attribute. The  value of this attribute is  interpreted as picture address.

Fig. 314.  Display of Picture in  Form

// Example 1
// Bind picture box to picture address in  temporary
// storage. PictureAddress – string-type form attribute
PutFile(PictureAddress, SourceName, SelectedName, True, UUID);

// Example 2
// Get picture address from attribute of
// infobase object
PictureFile = Object.PictureFile;
If Not PictureFile.IsEmpty() Then
PictureAddress = GetURL(PictureFile, "FileData")
Else
PictureAddress = "";
EndIf;
Chapter 20. Temporary Storage Mechanism, Working with Files and Pictures 2-851

20.2.12. Access to standard directories

When the system is  used, there should be some location in  the file system to store
different file data that, on the one hand, are temporal data, but, on the other hand,
must be kept for a  long time. These files include drafts for document management
systems, external components being run on the client computer side, etc.
To store these files, a  special directory linked to a  particular user of a  particular
database is  designated. One user working with two infobases will have access to
two different directories where user data is  stored. The  location of the directory
is  defined by applying the UserDataWorkDir() method. If the directory does not
exist, it  is  created when you call it  for the first time. If it  is  not possible to create
it, the system calls the exception.
NOTE
The UserDataWorkDir() method cannot be accessed on the server side.
The operating system has a special directory designated to ensure permanent
storage of user data. These can include any reports, printing forms of documents,
etc. Data that can be passed to external consumers in  the future is  stored in  this
directory. The directory can be accessed via the DocumentsDir() method.
The  physical location of the directory depends on the operating system that runs
the application.
„„ In Windows, it  is  the OS current user’s documents directory.
„„ In Linux, it  is  the OS current user’s home directory.
„„ In MacOS, it  is  a system directory of documents.
„„ In MacOS X, it  is  the current user’s documents directory.

20.3. SPECIFIC FEATURES OF USING IN  WEB CLIENT

Certain constraints are applied to the described mechanism in  the web client. These
are related to the Web browser security model. Thus, the client cannot save files
in  the local file system, i.e. interactive mode is  the only option for PutFile() and
GetFile() methods. An attempt to use non-interactive mode generates an excep-
tion. Dialog boxes displayed in  the interactive mode are browser-specific.
However, functionalities of working with files in  the web client can be extended,
if necessary. Use the extension for working with files for this purpose. After the
extension is enabled, the following objects and methods for working with files
become available in  the web client:
„„ Methods:
○○ GetFiles()
○○ PutFiles()
○○ FindFiles()
○○ RunApp()
2-852 1C:Enterprise 8.3. Developer Guide

○○ CreateDirectory()
○○ FileCopy()
○○ MoveFile()
○○ DeleteFiles()
„„ Objects:
○○ File
○○ FileDialog
NOTE 1
For the file operations extension to work correctly, it  is  recommended to use
Microsoft Core XML Services (MSXML) version 4.0 or 6.0 in  Microsoft Internet
Explorer.
NOTE 2
The file operations extension for Microsoft Internet Explorer is  installed
in  %APPDATA%\1C\1СEWebExt\FileSystemExtIE.
Do the following before using these components:
„„ Customize the web browser as necessary (for details see "1C:Enterprise 8.3.
Administrator Guide").
„„ Install the extension for working with files. Use the global context
InstallFileSystemExtension() method for this purpose. This activity
is  interactive and has to be executed once for each local machine user working
with the extension.
„„ Enable the extension for working with files. Use the AttachFileSystemEx-
tension() method for this purpose.
Chapter  21

THE EVENT LOG

Administrative tasks often require you to find out what events have occurred at
a  particular time or what actions various users have executed.
The event log is  used for this purpose. Various events are recorded in  this log. An
administrator can use it  to obtain a  history of users' interactions with the system.
The event log is not stored in the database and is not saved when an infobase
is restored/dumped.
When users work in  1С:Enterprise, the software registers major user actions
involving infobase data modifications, data access granting/denying scheduled
operations, connection and disconnection, etc.
Besides interactive tools to work with the log provided in  the designer, you can
also work with the log programmatically.
This chapter describes the software tools available for working with the event log.

21.1. DETAILS MANAGEMENT

It is possible to manage message detail level for messages in the event log.
The  GetEventLogUsing() and SetEventLogUsing() methods are used for this
purpose.
// set registration of all events of the log
Levels = New Array;
Levels.Add(EventLogLevel.Error);
Levels.Add(EventLogLevel.Information);
Levels.Add(EventLogLevel.DoMessageBox);
Levels.Add(EventLogLevel.Comment);

SetEventLogUsing(Levels);
2-854 1C:Enterprise 8.3. Developer Guide

21.2. WRITING EVENTS

When different operations are executed, you need to register actions for further
analysis. You can use the event log to do this. Events are written to the log using
the WriteLogEvent() method.
NOTE
You can't use this method to write system events to the log.
User event names can contain a  period, thus forming user event groups.

21.3. EVENT LOGGING MANAGEMENT

You can enable/disable any event logging. The  GetEventLogEventUsing() and
SetEventLogEventUsing() methods and the EventLogEventUsing object are
used for this purprose. The example below shows how to disable Performance
error event logging (_$PerformError$_):

EventUse = New EventLogEventUse();

EventUse.Use = False;

SetEventLogEventUse("_$PerformError$_", EventUse);

Note that there are two events that have additional abilities for event logging
configuration. These are the Access (_$Access$_.Access) and Access denied
(_$Access$_.AccessDenied) events. Let's discuss these events in  more detail.
NOTE
Transaction related events (_$Transaction$_.Begin, _$Transaction$_.Com-
mit, _$Transaction$_.Rollback) cannot be disabled via SetEventLogEven-
tUse method.

21.3.1. The Access Event Parameters Configuration

The Access event is  used to log facts of user access to certain data. You should set
the following to configure the Access event:
„„ the necessity of logging this event
„„ a list of metadata objects, access to which should be logged
„„ a list of metadata object fields, reading of which should be logged (access
fields)
„„ a list of metadata object fields, values of which should be logged (logging
fields)
The general mechanism looks as follows (if the event is  logged): if in  the process
of data (selected metadata object) handling one of the set access fields was read,
logging fields are written to the event log according to the set rules.
Chapter 21. The  Event Log 2-855

The amount of data written to the event log depends on the event logging configu-
ration:
Use Access fields Logging fields Result
Not set Event is  not logged
Set Not set Not set Event is  not logged
Set Set Not set Event is  logged without details
Set Set Set Event is  logged with the logging fields specified

An event is  generated only if data are successfully read.

Let's look at an example of parameters configuration:
SetupCatalog = New EventLogAccessEventUseDescription();

// Set object, access to which will be registered

SetupCatalog.Object = "Catalog.Individuals";

// Set access fields

SetupCatalog.AccessFields.Add("PassportData");
SetupCatalog.AccessFields.Add("Kids.BirthCertificate");

// Set registration fields

SetupCatalog.LoggedFields.Add("PassportData");
SetupCatalog.LoggedFields.Add("Kids.KidName");
FieldAlternatives = New Array();
FieldAlternatives.Add("LastName");
FieldAlternatives.Add("Name");
SetupCatalog.LoggedFields.Add(FieldAlternatives);

SetupMetadataObjects = New Array();

SetupMetadataObjects.Add(SetupCatalog);

This example registers access to Persons catalog items.

Event log events are automatically generated if a  request to Persons catalog data
includes:
„„ The PassportData field.
„„ The BirthCertificate field of the Children tabular section.
If a  data request lacks these fields, the data access event will not be written to the
event log.
When the system determines access to the controlled fields, the following informa-
tion about the Persons catalog will be written to the event log:
„„ The PassportData field.
„„ The ChildName field of the Children tabular section.
„„ The LastName or Name fields. The field that is written to the event log
is  determined by the presence of this data in  the data request. If all specified
fields are used, the field with the least index is  written to the event log (this
2-856 1C:Enterprise 8.3. Developer Guide

is  LastName in the example). If only one field of the two is used in the
request, this field goes to the event log.
Let's look at another example of Access event configuration:
SetupInformationRegister = New EventLogAccessEventUseDescription();

// Set object, access to which will be registers

SetupInformationRegister.Object = "InformationRegister.EmployeeSalaries";

// Set access fields

SetupInformationRegister.AccessFields.Add("Salary");

// Set registration fields

SetupInformationRegister.LoggedFields.Add("Employee");

SetupMetadataObjects.Add(SetupInformationRegister);

In this example, when the InformationRegister.EmployeeSalary.Salary field

is  accessed, the Access event will be logged with the following Data.Data field:
„„ If the request results in receiving the InformationRegister.EmployeeSa-
lary.Employee (and the Reference field is  set in  the logging fields configu-
ration of the Persons catalog to which the Employee field is referencing),
the event log will include:
○○ A value table with the CatalogPersonsReference column with reference
values for Persons catalog objects will be written in  the Data field.
○○ An array with the InformationRegister.EmployeeSalary row, i.e., the
name of the object that triggered logging this access event, will be written to
the Metadata field.
○○ The MetadataRepresentation field will contain an array with the Infor-
mationRegister row. Employee salaries is  a metadata object representation.
„„ If the Reference field is not included in Persons catalog logging fields,
it  will not be registered in  the information register request.
„„ If the request gets data using a  Catalog.Persons-type reference stored in  the
information register, only fields received via a  reference in  the Person catalog
field will be logged:
○○ For example, if the Name, LastName and PassportData fields are the
result of the request (all received via a reference in the Person catalog
field), the event log will include the PassportData and LastName fields
(see the description for the Employees catalog in  the previous example).
Chapter 21. The  Event Log 2-857

21.3.2. Access Denied Event Parameters Configuration

The Access denied event is  used to log user access denied events for certain data.
You should set the following to configure the Access denied event:
„„ the necessity for logging this event
„„ a list of metadata objects, for which logging events should be logged in  case of
denied access (for all other objects denied access will be logged without details)
„„ a list of metadata object fields, values of which should be logged (logging
fields) when access is  denied.
The general mechanism looks as follows (if the event is  logged): if in  the process
of data (selected metadata object) handling access was denied, logging fields are
written to the event log according to the set rules.
The amount of data written to the event log depends on event logging configura-
tion:
Use Logging fields Result
Not set Event is  not logged
Set Not set Event is  logged without details (the Data field is  not populated)
Set Set Event is  logged with specifying logging fields in  the Data field

The event is  generated in  the following cases:

„„ When access to the whole data object is  checked:
○○ If access rights are violated when accessing application object methods or
properties in 1C:Enterprise script or standard interface functions (forms,
commands).
○○ If access is  denied when configuration access rights are checked.
○○ If an event is triggered, the Data field of the log record will contain
a  structure with the Right property containing the action for which access
was denied.
„„ When data access restrictions are checked:
○○ If data access restrictions are breached.
○○ If an event is  triggered, the Data field of the log record will contain a  struc-
ture with two following properties:
□□ Action – the action for which access was denied.
□□ Data – contains information about logging fields (if configured).
NOTE
When data are read to a  temporary table, the Data.Data field of the event log
is  not populated.
2-858 1C:Enterprise 8.3. Developer Guide

Let's see an example of parameters configuration:

SetupCatalog = New EventLogAccessDeniedEventUseDescription();

// Set object, access to which will be registered

SetupCatalog.Object = "Catalog.Individuals";

// Set registration fields

SetupCatalog.LoggedFields.Add("PassportData");
SetupCatalog.LoggedFields.Add("Kids.KidName");
FieldAlternatives = New Array();
FieldAlternatives.Add("LastName");
FieldAlternatives.Add("Name");
SetupCatalog.LoggedFields.Add(FieldAlternatives);

If access to data are violated in  a Reading operation, the Access denied event will
be logged and the logging field will be written according to the rules for Access
event logging fields. For other actions (Change, Delete, Add) an event is trig-
gered, but no data are written.

21.4. GETTING EVENT LOG RECORDS

When an application is  used, a  situation may arise that requires you to program-
matically analyze the event log, such as get event log events per some criteria
(filters). You should use the UnloadEventLog()global context method to get event
log records programmatically. Programmatically, you can obtain the event log
records of an infobase where the script code is  executed or another infobase (even
if other 1C:Enterprise instances use this base) if the UnloadEventLog() method
has the InputFileName parameter set. Please note that this reading operation
is  only recommended if the event log files of another infobase are available locally
for the 1C:Enterprise instance that reads the log. If such access is  not granted, you
need to think of other ways of accessing the event log.
To set selection criteria, use the Filter parameter of the UnloadEventLog()
method. This  parameter can contain a  single filter value set with the Structure
object of a special format (this format is described in the Syntax Assistant:
Global context – Procedures and functions for working with the event log – Unload-
EventLog) or an array of such structures.
If the filter is set by one Structure-type item, all records will be put into the
result selection that fulfills all conditions set in  the structure (conditions are joined
with the "OR" operator). If the filter is  set by an array, the result selection will
include records that fulfill at least one condition listed in  the array items (condi-
tions are joined with the "OR" operator).
We should emphasize that you can set a  filter based on the Data field of an event
log record. String, Count, Data, Reference, Structure types of values can be
used as a  filter for this field (for Access, Access denied, Authentication, Authenti-
cation error, Add user, Update user and Delete user), as well as a  structure array.
Chapter 21. The  Event Log 2-859

The value of a  structure item passed in  the Filter parameter can be a  specific
value, Structure or Array. Event log data are checked for consistence with filter
parameters as follows:
„„ If a  specific value is  passed, record data and filter values are compared.
„„ If a  value array is  passed, event log record data values and all values of the
array passed as the filter value are compared. The condition is considered
fulfilled if the value set in the log record matches at least one value in the
passed array.
„„ If a structure is passed as the value, the condition is considered fulfilled if
event log record data are matched for all items of the passed structure.
Let's discuss it  in  more detail.
1. If the Data field of the event log record contains a  structure, the filter Data
field also contains a  structure. In  this case the record satisfies the condition if
the log Data field includes all keys from the filter field with the same name and
the values of these keys match.
2. If the Data field of the event log record contains a  value table, the filter Data
field contains a  structure. In  this case the record satisfies the condition if the
value table contains all the columns with names equal to filter structure key
names and rows where the corresponding column values match filter structure
values.
3. If the Data field of the event log record contains a  Structure, Array or
ValueTable type of value, the filter Data field contains an array. In  this case
the record satisfies the condition if at least one value from the passed array
is  found in  the log record data.
4. If the Data field of the event log record contains any value (not a  structure,
array or a  value table), the filter Data field contains an array. In  this case the
record satisfies the condition if the log record value is  equal to any value from
the passed array.
5. The log record Data field contains a  ValueTable-type value item, the filter
Data field contains an Array-type item and item keys match. In  this case the
record satisfies the condition if at least one table cell is  equal to any value from
the passed array.
6. If the Data field of the event log record contains a  Structure, Array or
ValueTable type of value, the filter Data field contains the Structure or
Array type. The  log record will satisfy the condition if a  record in  the nested
data fulfills p. 1 and p. 5 conditions. But if a structure is set in the filter,
a search for items in the structure or event log value table columns corre-
sponding to structure items will be performed only for a  specified nesting level
that corresponds to the filter nesting level. Thus, separate values and values
from arrays in  the filter are searched in  full depth, and filter structure items are
searched only at the specified level.
2-860 1C:Enterprise 8.3. Developer Guide

When a value table in the event log Data field is generated and it contains
columns with the same name, these columns are merged into a single column.
The  number of rows in  this table is  increased, so the result column includes all
unique values from the columns with the same name. Values in  other columns are
duplicated in  rows generated.
Let’s illustrate this using an example. Suppose an application contains a  query that
returns a  table with the following columns:
„„ CatalogRef.Products
„„ CatalogRef.Products
„„ Row
When an event log record is  generated, the following transformation is  performed:
„„ The first two columns will be merged into a  single column.
„„ For every row where Products.Reference and Nomenclature.Reference
values are not equal, another row will be generated.
„„ Rows will have a  different value of the merged column with reference values.
Other column values will be the same.
Source table:
Reference Reference Article
Sausages Pepper 16-АВ-1675

Result table:
Reference Article
Sausages 16-АВ-1675
Pepper 16-АВ-1675

Let's show some examples showing how filters work when event log records are
received.
Example 1:
„„ Event log Data field value for the Authentication event:
○○ type: Structure
□□ key: OSUser, value: Johnson
„„ Filter Data field value of the UnloadEventLog() method:
○○ type: Structure
□□ key: OSUser, value: Johnson
„„ Result: record matches
Example 2:
„„ Event log Data field value for the Access event:
○○ type: Structure
□□ key: Data, value: ValueTable
Chapter 21. The  Event Log 2-861

Last Name City Phone

Peterson Philadelphia 111-22-33
Johnson Washington 222-33-44

„„ Filter the Data field value of the UnloadEventLog() method:

○○ type: array.
□□ item 1: Structure type
 key: OSUser, value: Johnson
□□ item 2: Structure type
 key: Data, value: Structure
 key: LastName, value: Johnson
 key: City, value: Washington
„„ Result: record matches the filter, since when array item 2 was compared
a match with record data was found (row 2). The  event log record contains
a  value table with the Name and City columns in  which both values are equal
to corresponding values in  the filter structure.
Example 3:
„„ Event log Data field value for the Add user event:
○○ type: Structure
□□ key: Roles, value: Array
 value 1: Roles.Administrator
 value 2: Roles.Storekeeper
 value 3: Roles. SalesManager
„„ Filter Data field value of the UnloadEventLog() method:
○○ type: Structure
□□ key: Roles, value: Roles.Storekeeper
„„ Result: record matches the filter, since the Data field contains an Roles item
that has a  Roles.Storekeeper value.
Example 4:
„„ Event log Data field value for the Add user event:
○○ type: Structure
□□ key: Roles, value: Array
 value 1: Roles.Administrator
 value 2: Roles.Storekeeper
 value 3: Roles.SalesManager
„„ Filter Data field value of the UnloadEventLog() method:
○○ type: Structure
2-862 1C:Enterprise 8.3. Developer Guide

□□ key: Roles, value: Array

 value 1: Roles.SalesManager
 value 2: Roles.Accountant
„„ Result: record matches the filter, since the Data field contains a  Roles item
that has a  value listed in  the filter array (Roles.SalesManager value).
Example 5:
„„ Event log Data field value for the Access event:
○○ type: Structure
□□ key: Data, value: ValueTable
Last Name City
Peterson Philadelphia
Johnson Washington

„„ Filter the Data field value of the UnloadEventLog() method:

○○ type: array
□□ type: Structure
 key: Data, value: Philadelphia
„„ Result: record matches the filter, since the target value (Philadelphia) is  found
in  one of the value table cells in  the Data field of the event log record Data
field.
When the event log record Metadata field contains metadata array, the record
matches the filter if at least one array item from the filter Metadata field is  equal
to any log record array item.

21.5. ADDITIONAL METHODS

To simplify interactive event log filtering you can use the GetEventLogFil-
terValues() method. With this method you can get available filter values for
the following filter parameters: User, Computer, AppName, Event, Metadata,
ServerName, Port, SyncPort. Thus, if you need to set a  filter for an event log
event, you can get a list of events that are actually present in the log and then
select items from the list.
The EventLogEventRepresentation() method is used to generate event log
event representations.
Chapter  22

THE CRYPTOGRAPHIC
MECHANISM

When 1C:Enterprise is  used in  automation systems, you might need to check that
a  document stored in  the system wasn't modified (for example, a  document with
a text of the agreement is attached to the Agreement database object). There
also could be a  need to transfer some signed information or implement approval
of a  document within the system. Some scenarios are possible when you need to
transfer information via public channels so that it  would be impossible to read the
information if it  is  intercepted (data encryption).
For that purpose, 1C:Enterprise implements a  cryptographic mechanism based on
asymmetric encryption (a couple of keys are used, public and private).
IMPORTANT!
The 1C:Enterprise cryptographic mechanism does not actually implement crypto-
graphic algorithms. It  provides a  set of objects that can be used to communicate
with third parties’ external cryptographic modules.

22.1. GENERAL MECHANISM DESCRIPTION

The public key is  used to transfer data via public channels, and the private key
is  not distributed and should be protected to a  maximum degree.
The receiver public keys should be known to encrypt data. A private key coupled
with the public key used for encryption is  needed to decrypt data. A private key
is  required to generate a  digital signature, and the signer's public key is  required
to validate the signature (most often, a  public key is  included in  a signature).
To confirm that a  public key really belongs to a  subject, a  certificate authority
is  used that ensures this fact with a  signature.
2-864 1C:Enterprise 8.3. Developer Guide

A certificate is  a public key signed by a  certificate authority. Since a  private key
should be protected, it  exists in  a container. Key container can include an open
key in  addition to a  private key (e.g., as a  certificate).
Cryptographic extension should be installed for the web client to work. The  web
client specifies that the user permission query is  executed for some operations (file
system access and private key access).

22.2. MAIN CONCEPTS

Some terms will be used to describe the mechanisms covered in  this section.
Digital signature – a  series of data generated as a  result of cryptographic trans-
formation of source information using a digital signature private key. It can be
used to confirm integrity and invariability of this information and its authenticity,
if a  digital signature public key and its certificate are used.
Digital signature authenticity confirmation center (hereinafter referred to as
Certification authority) – a legal entity or a dedicated legal entity department
with privileges to confirm the authenticity of the digital signature public key owner.
Key certificate owner – a  person for which a  public key certificate is  generated
by a  certification authority and who owns a  corresponding private (secret) key.
Certificate – a  digital document including a  public key and information about the
key owner certified by a  certification authority using a  digital signature.
Cryptographic module – a  library of functions that directly implements crypto-
graphic algorithms or provides access to encryption mechanisms.

22.3. GENERAL PRINCIPLES

OF USING CRYPTOGRAPHIC MECHANISMS
Two main usage options can be identified when cryptographic mechanisms are
used:
„„ data encryption/decryption
„„ data signing/signature validation
General encryption/decryption principles can be described as follows:
„„ A necessary object for access to cryptographic functionality is created (the
CryptoManager object).
„„ A necessary certificate is  selected that is  a public key of the receiver side (the
CryptoCertificate object). This  certificate is  used to encrypt data.
„„ Required files or binary data are encrypted using the Encrypt() methods of the
CryptoManager object created.
„„ Encrypted data are ready for transfer via public channels.
„„ When encrypted data are received, reverse operation is  executed.
Chapter 22. The  Cryptographic Mechanism 2-865

„„ A necessary object for access to cryptographic functionality is created that

should match the object used for data encryption.
„„ Received data are decrypted using the Decrypt() method of the created cryp-
tographic functionality object.
General signing/signature validation principles can be described as follows:
„„ A necessary object for access to cryptographic functionality is created (the
CryptoManager object).
„„ A necessary certificate is  selected that is  a private key of the signing side (the
CryptoCertificate object). This  key is  used to generate a  digital signa-
ture.
„„ A digital signature for the required file or binary data is  generated using the
Sign() method of the CryptoManager object created.
„„ Signed data with the digital signature are sent to the receiver side.
„„ When signed data and the digital signature are received, reverse operation
is executed.
„„ A necessary object for access to cryptographic functionality is created that
should match the object used to generate a  digital signature.
„„ The digital signature is  validated using the VerifySignature() method of the
cryptographic functionality object created.
Certificates necessary for cryptographic operations are received from a corre-
sponding certification authority.
It is  not recommended to get several certificate storages with similar characteris-
tics when you are working with the CryptoManager object, since changing one
storage will lead to a different behavior of the other storage depending on the
cryptographic modules being used.

22.4. WORKING WITH CRYPTOGRAPHIC MODULES

Microsoft CryptoAPI is  used to interact with cryptographic modules in  Windows.
Direct interaction with the installed components is used to interact with crypto-
graphic modules in  Linux.
The following components are supported:
„„ CryptoPro cryptographic information protection tool. To use this tool, specify
75 as the CryptographicModuleType parameter of the CryptoManager
object.
2-866 1C:Enterprise 8.3. Developer Guide

22.5. USAGE EXAMPLES

This section provides examples of some typical tasks executed using cryptographic
mechanisms.
Creating an object to access cryptographic functionality
Creating an object to access cryptographic functionality is a basic operation,
without which further operations with the cryptographic mechanism are not avail-
able.
CryptoManager = New CryptoManager("", "", 75);

This example creates a  module to work with Russian cryptographic modules (the
CryptographicModuleType parameter value is  75).

Getting a  list of certificates

A list of certificates from selected certificate storages is  generated that will be used
in  further operations.
&AtClient
Function GetCertificateList(CryptographyManagerType, TypesArray, CheckExpirationDate)

// List of certificates
CertificateList = New Array;

CryptoManager = New CryptoManager("", "", CryptographyManagerType);

For Each StorageType In  TypesArray Do

// Get certificates for each type of certificates storage
Storage = CryptoManager.GetCertificateStore(StorageType);

// Select all certificates
StorageCertificates = Storage.GetAll();
CurrentDate = CurrentDate();

For Each Certificate In  StorageCertificates Do

If CheckExpirationDate And Certificate.EndDate < CurrentDate Then

// Skip expired certificates, if needed
Continue;

EndIf;

CertificateList.Add(Certificate);

EndDo;

EndDo;

Chapter 22. The  Cryptographic Mechanism 2-867

Return CertificateList;

EndFunction

&AtClient
Procedure ObtainCertificateList()

StorageTypes = New Array;
StorageTypes.Add(CryptoCertificateStoreType.PersonalCertificates);
StorageTypes.Add(CryptoCertificateStoreType.RecipientCertificates);
List = GetCertificateList(75, StorageTypes, True);

// ...

EndProcedure

File encryption
A file selected interactively is encrypted and then written to a disk of a client
computer.
For demonstration, encryption operation always uses the first certificate in  the list
of all of certificates installed on the computer.
&AtServer
Function EncryptAtServer(DataAddress, CertificatesData)

// Create certificates on the basis of binary data certificates // from the client
Certificates = New Array();
For Each CertificateData In  CertificatesData Do

Certificates.Add(New CryptoCertificate(CertificateData));

EndDo;

CryptoManager = New CryptoManager("", "", 75);

// Get file for encryption from the temporary storage
Data = GetFromTempStorage(DataAddress);
If TypeOf(Data) <> Type("BinaryData") Then

Return False;

EndIf;

// Encrypt binary data
EncryptedBinaryData = CryptoManager.Encrypt(Data, Certificates);

// Save to temporary storage

DataAddress = PutToTempStorage(EncryptedBinaryData);

Return True;

EndFunction
2-868 1C:Enterprise 8.3. Developer Guide

&AtClient
Procedure FileEncryption()

Address = "";
Result = PutFile(Address, , , True);
If Not Result Then

Return;

EndIf;

CertificateTypes = New Array;
CertificateTypes.Add(CryptoCertificateStoreType.PersonalCertificates);
List = GetCertificateList(75, CertificateTypes, True);

// In  this example we always encrypt using the first by order certificate
Certificates = New Array;
Certificates.Add(List[0].Unload());

// Encrypt file
Result = EncryptAtServer(Address, Certificates);
If Not Result Then

Return;

EndIf;

// Interactively save encrypted file to disk
GetFile(Address, , True);

EndProcedure

File decryption
An attempt to decrypt the selected file is  executed. It  is  necessary to implement
the GetAccessPassword() function that returns the password to access the
private key.
NOTE
When the Decrypt() method is  used, an exception is  called only when decryp-
tion attempts using all available certificates have failed, not just after the first
error.

&AtClient
Procedure FileDecryption()

// Choose encrypted file
Address = "";
Result = PutFile(Address, , , True);
If Not Result Then

Return;

EndIf;

Data = GetFromTempStorage(Address);
Chapter 22. The  Cryptographic Mechanism 2-869

// Decrypt file
CryptoManager = New CryptoManager("", "", 75);
CryptoManager.PrivateKeyAccessPassword = GetAccessPassword();
DecryptedData = CryptoManager.Decrypt(Data);

Address = PutToTempStorage(DecryptedData);
GetFile(Address, , True);

EndProcedure

Digital signature generation

A file with a  digital signature is  generated. In  this example the digital signature
is always saved in the signature.sign file. It is necessary to implement the
GetAccessPassword() function that returns the password to access the private
key.

&AtClient
Procedure SignFile()

Address = "";
Result = PutFile(Address, , , True);
If Not Result Then

Return;

EndIf;

CertificateTypes = New Array;
CertificateTypes.Add(CryptoCertificateStoreType.PersonalCertificates);
List = GetCertificateList(75, CertificateTypes, True);

Certificate = List[0];
Data = GetFromTempStorage(Address);
CryptoManager = New CryptoManager("", "", 75);
CryptoManager.PrivateKeyAccessPassword = GetAccessPassword();
CryptoManager.Sign(Data, "signature.sign", Certificate);

EndProcedure

Digital signature validation

This function validates digital signature authenticity for the original file  – digital
signature file combination.
&AtClient
Function CheckFileSignature(SignedFileName, SignatureFileName)

Certificate = Undefined;
CryptoManager = New CryptoManager("", "", 75);
2-870 1C:Enterprise 8.3. Developer Guide

Try

CryptoManager.VerifySignature(SignedFileName, SignatureFileName, Certificate);

Except

Return False;

EndTry
Return True;

EndFunction
Chapter  23

EXTERNAL DATA SOURCES

When an infobase based on 1C:Enterprise is used, you may want to get infor-
mation from external data bases (both relational and analytical) and use this
information in  1C:Enterprise in  a number of ways (for reports, calculations etc).
An ExternalDataSources configuration object is used to solve these tasks
in 1C:Enterprise. An external data source may include tables from a relational
data source and cubes from an analytical data source. An application may contain
any number of connected external data sources. Below, we take a  closer look at
working with all types of external data sources.

23.1. WORKING WITH RELATIONAL EXTERNAL DATA SOURCES

23.1.1. Overview
An object that describes an external data source connected to a  relational database
consists of tables, and each table consists of fields. Table data may reference other
tables: for instance, a value in a table field may identify records from another
table. The  object that describes an external data source may be used as follows:
„„ as a  query data source;
„„ as a  data source in  the data composition system;
„„ as a  data source for dynamic lists;
„„ they can be parts of common attributes (see page 1-204);
„„ table records can be displayed in  1C:Enterprise managed forms (use of ordi-
nary forms for external data source objects is  not supported);
„„ external data source tables can act as infobase attribute types;
„„ access rights and access restrictions can be applied to external data source tables
(and fields);
„„ access to tables and fields is  available in  1C:Enterprise script;
2-872 1C:Enterprise 8.3. Developer Guide

„„ an external data source table can be included in  subsystems (see page 1-173);
„„ an external data source table can be included in functional options (page
1-211);
„„ characteristics can be created for an external data source table (see page 1-309).
The ODBC engine is used to get access to external data sources. Data from
external data sources are read only.
IMPORTANT!
The external data source mechanism should not be used to access 1C:Enterprise
databases, since the 1C:Enterprise data model is  not designed to work with data
at DBMS storage physical structure level.
1C:Enterprise abilities are thoroughly considered when the following DBMS
systems are used as an external data source:
„„ Microsoft SQL Server
„„ IBM DB2
„„ PostgreSQL
„„ Oracle Database
NOTE
When working with an external data source, errors may occur if the Database
management system type property of the external data source connection param-
eters contain a  value that does not match the system that is  actually used.
When other DBMS are used, external data source functions depend on a  specific
DBMS. The following query language expressions and functions for such data
sources are transformed into a DBMS query with the help of ODBC Escape
Sequences (http://msdn.microsoft.com/en-us/library/windows/desktop/ms715364(v=vs.85).aspx):
SUBSTRING, YEAR, QUARTER, MONTH, DAYOFYEAR, DAY, WEEK, WEEKDAY, HOUR,
MINUTE, SECOND, DATEDIFF, ISNULL, CAST, ESCAPE, JOIN, LEFT JOIN, RIGHT
JOIN, and FULL JOIN.
To connect to an external data source you need to generate a  connection string that
can contain either all the connection parameters required for the selected ODBC
driver or a  reference to a  generated DSN (Data Source Name) data source descrip-
tion. For more about connection string see page 2-879.
String connection examples are provided below.
String connection with a  login and a  password:
DRIVER={SQL Server};SERVER=(local);UID=user;PWD=password;DATABASE=AdventureWorksLT2008

Login and password should also be specified:

DRIVER={SQL Server};SERVER=CASH-SERVER;DATABASE=CasheReceipts
Chapter 23. External Data Sources 2-873

Specifying a  pre-configured data source:

DSN=MyDB

Also, you should remember that connection to an external data source should be
specified in  both the Designer (if the table structure is  imported for the external
data source) as well as 1C:Enterprise mode to receive data.

23.1.2. General Usage Principles

To use information from external data sources in a 1C:Enterprise-based system
you need to follow these general principles:
„„ Analyze the external data source structure and understand which information
(tables and fields) is  required for algorithms and reports in  1C:Enterprise.
„„ create an External data source object in  the Designer and create subordinate
Tables and fields for this object. This  can be done using a  special wizard.
„„ Implement usage of the created objects in  the application.
„„ Configure parameters for connection to an external data source in  the network
where the application will be used. These parameters can be different from the
parameters used to load the external data source structure.
NOTE
Exernal data source access parameters that were set in  the Designer, will not be
used by the system in  1C:Enterprise mode.

23.1.3. Editing External Data Source Structure

A branch with a  name of the corresponding external data source of the External
data source – Tables configuration tree branch is  used to work with external data
source tables. External data source definition is  implemented in  three steps:
„„ Define the data source itself.
„„ Define data source tables.
„„ Define tables for every external data source table.
Configuration can describe fewer tables and fields than in  a real database, but you
can't define a  table or a  field that does not exist in  a real database.
You can create external data source structure manually or you can load this struc-
ture using a  special designer.

23.1.3.1. External Data Sources

You should specify a name for an external data source when it is created.
This  object is  used to identify table groups when you are accessing data in  the
object. A data source consists of one or more tables which in  turn are made up of
fields.
2-874 1C:Enterprise 8.3. Developer Guide

23.1.3.2. External Data Source Tables

When you create a  new table, the object editing window opens (see page 1-59).
The Name table property is  used to identify a  table within the application. You
should fill in the Name in  the data source property so the system will know
which external data source physical table corresponds to the configuration object.
This  property value should exactly match the table name from the external data
source. Adding data to one application table from multiple physical tables of an
external data source is  not supported.
The Table data type property determines which type of entities are stored in  the
table: object or non-object. If one field that unambiguously defines a  record can
be selected in  the table, the table can store object data. A catalog can be the closest
analogue of such tables. If a  table record is  identified by several key fields, such
a  table contains non-object data. An information register is  the closest analogue of
such tables. Table key fields should be specified in  the Key fields property.
NOTE
It is  not recommended fields that contain Null values as a  key fields in  the
external data source table.
For object data tables you can specify a  field that will act as an object representa-
tion. You can use the Presentation field property for this purpose.
If the table stores hierarchical data, the system can be informed about it  via such
properties as Parent field, Missing parent descriptor and Missing parent descriptor
value. These properties are available only for tables where object data is  stored.
The  Parent field property is  intended to specify the database table field that stores
a  reference to the parent for the record. Fields that can be selected in  this property
should have the type of reference to the table being used. The  parent field should
have the ExternalDataSourceTableReference.DBF.products type for the
products table from this example (see page 2-877). The  Missing parent descriptor
and Missing parent descriptor value properties specify which value will define the
record with no parent record. After these properties are specified:
„„ the data composition system uses them when working with hierarchical groups
and when checking hierarchy conditions;
„„ the query language uses them for operations in  the INHIERARCHY construct;
„„ these properties are used to display tables with hierarchical data (the display
options are identical to the options used to display hierarchal catalogs).
The String input property (see page 1-258) can be used to specify the field names
used to search in  the field with the data type specifying the necessary external data
source table.
When tables are created manually the Key fields, Presentation field and String input
properties can be specified only after external data source table fields are created.
Chapter 23. External Data Sources 2-875

23.1.3.3. External Data Source Table Fields

Table fields describe which physical table data are available in the application.
The  Name field property is  used to identify a  table field within the application.
The  Name in  data source property is  used to specify a  mapping between an appli-
cation field and a  physical table field. This  property value should exactly match
the name of a  table column specified in  the Name in  data source property of the
parent field object. Merging data in  one data table field from multiple columns or
multiple tables of an external data source is  not supported.
If the value included in  the Name in  data source property is  in  single quotes, then
it  remains unchanged in  the SQL query to the database irrespective of the charac-
ters used. Where the value in  the fields is  not set in  single quotes, then it  appears
edged with double quotes in  the SQL query to the database if the name includes
special characters.
The Type field is used to specify a type of the field. A restricted set of types
is  available. These types include:
„„ Number
„„ String
„„ Date
„„ Boolean
„„ UUID
„„ BinaryData
„„ types defined by external data source tables
If a  composite type should be specified for a  field, only Number, String, Data
and Boolean types can be used in  this type.
When data are extracted from external sources, the system automatically converts
this data to the type specified for the corresponding field in  the application. See the
description of transformation rules on page 2-893.

23.1.3.4. Other Properties

The form used to display external data source table records and lists can be created
automatically by the system or an application developer. Note that if the table
is  non-object and key fields are not specified, then:
„„ the record form can't be displayed.
„„ access to the ExternalDataSourceTableRecordSet object in  not available.
This is  due to the fact that you can't unambiguously identify the required recordset
in  a table.
2-876 1C:Enterprise 8.3. Developer Guide

23.1.3.5. Loading Table Structures from an External Data Source

You can load table structures from an external data source available to developers
(e.g., a  copy of a  real database).
To do this you need to check the Select from list of external data source tables
option in  the external data source table designer when you are creating the table.
Then you should specify an external database connection string in  the Connection
to Data Source window. You can use the external data source connection string
designer when generating a connection string. Click the "…" button next to the
Connection String field.
When the external database is  successfully connected, a  list of tables and fields
of the connected data source opens. Then you need to select tables and fields that
will be used by the Designer to create object structures describing the current data
source.

Fig. 315.  External data source table designer

The system performs the following actions when you obtain data source structure:
„„ An attempt to determine the data table type (object or non-object) is  performed.
The table is considered to be an object if only one key field is specified;
otherwise it  is  considered to be a  non-object. If the system made a  mistake
in  specifying the key fields, you can manually change the fields that form the
Chapter 23. External Data Sources 2-877

table key. If the table is  defined as an object table, you can specify a  field for
representing the data of such type. The  representation field should be specified
manually.
„„ Data source column types are converted to 1C:Enterprise types that will be used
to specify table attribute types. All external data source types are converted
into the following 1C:Enterprise types: Number, String, Data, Boolean, UUID,
Binary Data and types related to data source object tables.
„„ An attempt to determine table field types is  performed. In  this case the system
tries to determine which data type is  stored in  the table column; if it  can be
considered as a reference to other table data, the system specifies a corre-
sponding type in  the column. If the system selected the wrong table column
type, this can be changed manually.
Then you should check tables and fields that will be migrated to application meta-
data.
If the Remove tables and fields not present in  external data source from configura-
tion checkbox is  selected, when the table designer work is  done fields and tables
that do not exist in  the external source will be deleted from the configuration (for
example, if fields or tables were deleted from the external source).
When the Finish button is  clicked, external data source structure is  loaded.

23.1.4. Example of External Data Source Table Creation

Suppose we have dbf-format database that should be accessed from an application.
The database contains three tables (files):
„„ products tables (stored in products.dbf), with information about products
containing the following fields:
○○ id – product identifier (key field). Type: Number.
○○ code – product code. Type: String.
○○ name – product name. Type: String.
○○ article – product article. Type: String.
„„ price tables (stored in  price.dbf), with current product prices containing the
following fields:
○○ product – identifier of the product whose price is  stored. Type: Number.
○○ price – product price. Type: Number.
„„ sales table (stored in  sales.dbf) with data on every product sale, price, quan-
tity and sum. The  table contains the following fields:
○○ product – identifier of the sold product. Type: Number.
○○ price – product retail price. Type: Number.
○○ qty – quantity of sold products. Type: Number.
○○ summa – total product selling cost. Type: Number.
2-878 1C:Enterprise 8.3. Developer Guide

Let's create necessary configuration objects to get access to all data in these
tables.
First, we will create the data source itself. We'll name it  DBF. The  next step is  to
create data source tables manually. Note that the real name of a  data source phys-
ical table is  specified in  the Name in  data source property of the created object.
We will name the configuration object as follows when tables are created:
„„ the products table will be displayed in  the Products object.
„„ the price table will be displayed in  the Prices object.
„„ the sales table will be displayed in  the Sales object.

Fig. 316.  External source tables

Now we need to create fields for each table, specify the field types and assign key
fields and representation fields (if any).
The example will have one object table (the Products table). Other tables will be
non-object. You can see the physical table fields and configuration object fields
matching and field types in  fig. 317.

Fig. 317.  Table structure in  the application

Chapter 23. External Data Sources 2-879

Then you should specify the subsystem that contains the tables created and other
configuration object parameters (if necessary).
If you start the system in  1C:Enterprise mode and correctly specify the external
data source connection parameters, the tables created will be shown in  the naviga-
tion panel:

Fig. 318.  External data source dynamic list

23.1.5. ODBC Connection String

To connect to an external database, you need to create a  connection string that can
contain all the connection parameters necessary for the selected ODBC driver or
a  reference to the completed data source name (DSN).

23.1.5.1. Full Connection String

For a description of a connection string, please see http://msdn.microsoft.com/en-us/
library/ms722656.aspx. The  following aspects are important in  this description:
„„ Connection string parameters are written in pairs KeyWord=Value and are
separated with ;.
„„ If a  connection string contains several parameters with the same keyword, only
the last parameter specified in the connection string will be used. So, if for
instance the User name or Password parameters are specified in  the connection
string and the Connection to Data Source dialog (see page 2-888), the values
2-880 1C:Enterprise 8.3. Developer Guide

from the Connection to Data Source will be used, as they will be added to the
connection string on the right.
Use http://www.connectionstrings.com/ for reference and help with simplifying creation
of a  connection string.

23.1.5.2. Describing a  Data Source

You can use special utilities to create a data source name (DSN) instead of
specifying the full connection string. In  this case, you need to specify a  special
construction of the type DSN=DSNName in the connection parameters. There are
user data source names and system data source names. User data source names are
available on a  given computer and only to the user who has created the description.
A system description is  created by the system administrator and is  available to all
the users of this computer (provided they have the necessary permissions).

23.1.5.3. ODBC Data Source Administration Utility

To create a data source description, you need to use the ODBC data source
administration utility. To find this utility in Windows OS, go Control Panel  –
Administrative Tools  – Data Sources (ODBC). This opens an administration
utility (version compliant with the OS version) from the Windows Control panel.
In  Linux OS, the utility is  called ODBCConfig and is  only available if the required
package is  installed (this depends on the Linux OS version).
You should remember that drivers and data sources for a 32-bit and a 64-bit
ODBC differ in 64-bit Windows. Therefore, to create a data source name, use
the administration utility version that corresponds to the 1C:Enterprise version.
For instance, if you call ODBC from a  64-bit version of the 1C:Enterprise server,
you need to use a 64-bit version of the administration utility. If you use a file
mode of 1C:Enterprise on 64-bit Windows, use a  32-bit version of the administra-
tion utility, since the client application is  a 32-bit application.
In 64-bit Windows, Administration utilities are located in  the following directories:
„„ 64-bit version: %SYSTEMROOT%\System32\odbcad32.exe
„„ 32-bit version: %SYSTEMROOT%\SysWOW64\odbcad32.exe

23.2. WORKING WITH AN EXTERNAL OLAP DATA SOURCE

23.2.1. Overview
OLAP is  a data processing technology that prepares aggregated information from
large data arrays structured by a multi-dimensional principle. Data in analytical
databases (OLAP systems) are created on the basis of data from transactional data
processing systems (OLTP systems). Information in  OLTP systems is  presented
as a  space (so-called cube), with axes that are measures, and the nodes of this
space contain measures. Each cube measure is  characterized by certain members.
Chapter 23. External Data Sources 2-881

A close (but not similar!) analogue of storing data in  OLAP systems is  an accumu-
lation register, where the register is  similar to a  cube, measure of the CatalogRef
type is  similar to a cube’s measure, and the catalog contains measure members
and register resources are similar to cube measurements.1C:Enterprise presents the
OLAP system cubes as a  model, where:
„„ A cube is  represented by the cube in  configuration.
„„ Dimensions and dimension members are represented as two objects:
○○ Measures are analogues of measures.
○○ Measures tables are used to describe measure member collections.
„„ Measures are presented as resources.
Therefore, an external source that connects to the OLAP system includes cubes,
and each cube consists of a  table of dimensions, the dimensions themselves, and
resources. Tables of measures consist of fields. Cube resources may be numerical
or string.
The object that describes an external data source may be used as follows:
„„ as a  data source for queries.
„„ as a  data source in  the data composition system.
„„ as a  source for dynamic lists.
„„ as a  member of common attributes (see page 1-204).
„„ records of measurement tables and cubes may be displayed in  managed forms
of 1C:Enterprise (using standard forms for external data source objects is  not
supported).
„„ the measurement tables of an external data source may serve as infobase
attribute types.
„„ access rights may be applied to cubes, measurement tables, measurement table
fields, measurements and resources of external data sources.
„„ the script supports access to cubes, measurement tables, measurement table
fields, measurements, and resources.
„„ the cubes and measurement tables of an external data source may be part of
subsystems (see page 1-173).
„„ the cubes, measurement tables and measurements of an external data source
may be part of functional options (see page 1-211).
„„ characteristics may be created for external data source cubes (see page 1-309).
The analytical XML mechanism (XML for Analysis, XMLA) is  used to work with
multidimensional external data sources. The  platform receives access to data with
the help of http requests to a  web server that can be an external system (in rela-
tion to OLAP system) or integrated in  an OLAP server. For further information on
customizing access to OLAP server data, see the documentation for that system.
A line to connect to an analytical external data source is  a combination of an XMLA
provider URL address (for this OLAP system) and the parameters used by 1C:Enterprise
to work with the source. Data from external data sources is  only read-only.
2-882 1C:Enterprise 8.3. Developer Guide

The capabilities of 1C:Enterprise are taken into account when the following OLAP
systems are used as an external data source (Database management system type
property of data source connection parameters):
„„ IBM Infosphere Warehouse
„„ Microsoft SQL Server Analysis Services
„„ Oracle Essbase
NOTE
When working with an external data source, errors may occur if the Database
management system type property of the external data source connection param-
eters contain a  value that does not match the system that is  actually used.
When other DBMSs are used, the external data source capabilities depend on the
DBMS itself. To connect to an external data source, create a connection string.
For further details on connection strings, see page 2-883.
Moreover, an external data source connection should be specified in Designer
(if a  mechanism to import a  table structure from an external data source is  used)
and in  1C:Enterprise mode to obtain the data itself.
Documentation on OLAP systems:
„„ IBM Infosphere Warehouse:
○○ http://publib.boulder.ibm.com/infocenter/db2luw/v9r5/topic/com.ibm.dwe.navigate.doc/
welcome_db2warehouse.html
„„ Microsoft SQL Server Analysis Services:
○○ Version 2008: http://technet.microsoft.com/en-us/library/bb522607(v=sql.100).aspx
○○ Version 2008 R2: http://technet.microsoft.com/en-us /library/bb522607(v=sql.105).
aspx
○○ Version 2012: http://technet.microsoft.com/en-us /library/bb522607(v=sql.110).aspx
„„ Oracle Essbase:
○○ http://docs.oracle.com/cd/E17236_01/nav/portal_3.htm
23.2.2. The general principles of usage
To use information from external data sources in  a 1C:Enterprise based system,
follow the general principles described below:
„„ Examine the structure of an external data source and work out what informa-
tion (cubes, measurement tables, measurements, and resources) is  necessary to
support 1C:Enterprise algorithms and reports.
„„ Create an External data source object in Designer, and create the required
structure for this object. A special assistant can be used to do this.
„„ Implement the use of objects created in  the application.
„„ Set up the external data source connection parameters in  the network where the
application will be used. These parameters may differ from those used when
downloading an external data source structure.
Chapter 23. External Data Sources 2-883

NOTE
In 1C:Enterprise mode the system will not use external data source access param-
eters set in  Designer.

23.2.3. Editing external data source structure

A branch with the name of the corresponding external data source of the External
data source  – Cubes branch of the configuration tree is used for working with
external data source tables. An external data source is  defined in  several steps:
„„ Definition of the external data source itself
„„ Definition of cubes
„„ Definition of measurement tables and fields for each measurement table
„„ Definition of measurements for a  cube
„„ Definition of resources for a  cube
While a  configuration may describe fewer objects than there are in  an actual data-
base, you cannot create an object that is  not present in  an actual database.
The structure of an external data source may be created manually or with the help
of a  special wizard when the structure is  loaded.

23.2.3.1. External data source

Specify the name of an external data source when it  is  created. This  object is  to
be used to identify groups of cubes when querying data in these cubes. A data
source contains one or more cubes that, in  turn, contain other objects (measure-
ment tables, measures, resources).

23.2.3.2. External data source cube

When a  new cube is  created, an object editing dialog opens (see page 1-59).
Table property Name is  used to identify a  cube within the application. Complete
the Name in  the data source property so that the system knows which physical
cube of an external data source matches the configuration object. This  property’s
value shall match the name of a  cube of the external data source exactly. Data from
several external data source cubes cannot be located on one application cube.

23.2.3.3. Dimension table

A dimension table describes members of an OLAP system cube dimension.
The  Name in  the data source property contains the exact name of a  dimension or
a  hierarchy level in  the data source. The  Presentation field property contains the
name of a  dimension property or a  hierarchy level used by 1C:Enterprise to create
dimension table item representation.
2-884 1C:Enterprise 8.3. Developer Guide

If a dimension is hierarchical, a hierarchical dimension table can be used for

such a  measurement. A hierarchical dimension table can be described through the
following properties:
„„ Hierarchical dimension table – contains an attribute that shows that a  dimension
table describes a  hierarchy in  the data source.
„„ Hierarchy name in  the data source – specifies the name of a  hierarchy to which
a  dimension table that describes this level belongs.
„„ Level number – if a table describes a certain hierarchy level, this property
contains the number of this level. This  property is  set to 0 for the hierarchical
table itself, and the Hierarchy name in  the data source property matches the
value of the Name in  the data source property.
The Missing parent descriptor and Missing parent descriptor value properties can
be used to specify how values of the highest hierarchy level are to be identified
in 1C:Enterprise.

23.2.3.4. The dimension table field

Dimension table fields describe which dimension properties will be available from
within the application. The  Name field property can be used to identify a  property
(dimension table field) in  the application. Use the Name in  data source property
to specify correspondence between an application field and a  dimension attribute.
A value in  this property should exactly match a  dimension attribute name speci-
fied in  the Name in  data source property of the parent object of this field. Uniting
several attributes of one or several dimensions belonging to an external data source
in  one data dimension table field is  not supported.
The Type field can be used to specify the type of this field. A limited set of types
is  available for selection. The  following field types are available:
„„ Number
„„ String
„„ Date
„„ Boolean
„„ UniqueIdentifier
„„ BinaryData
„„ Types defined by external data source dimension tables
If a  composite type needs to be specified for the field, such a  composite type may
only contain Number, String, Date and Boolean types.
When data from external sources is received, the system automatically casts
this data into a  type specified for the corresponding field of the application. For
converting rules, see page 2-893.
Chapter 23. External Data Sources 2-885

23.2.3.5. Dimensions
An external data source dimension describes the OLAP system cube dimension.
Only a  reference to a  corresponding dimension table may be considered as such
a dimension type. In reality, dimension tables and the dimensions themselves
form a  1:1 correspondence: one dimension is  described by one dimension table.
Uniting data from several external data source dimension in one field is not
supported.

23.2.3.6. Resources
An external data source resource describes the fact that there is  an OLAP system
cube. The  cube’s resource may be numerical or string. Resource values are calcu-
lated on the basis of cube dimension values. The  Name in  the data source property
should match the name of a  fact (a resource) of the external data source cube.
Uniting data from several facts (resources) of an external data source in  one data
resource is  not supported.

23.2.3.7. Loading the cube structure from an external data source

The cube structure may be loaded from an external data source available to the
developer (for instance, a  copy of a  real database).
To perform this operation, select Select from external data source cube list in  the
external data source cube wizard when creating a  cube. Next, specify a  string to
connect to an external database in  the Connection to data source dialog. To create
a  connection string, use the external data source connection string wizard. Click
"…" to the right of Connection string.
When a connection to an external infobase is successfully established, a list of
cubes, dimension tables, dimension table fields, and resources of the connected
data source is displayed. Select the required cube, dimension tables, fields, and
resources to be used by the wizard to create a  structure of objects that describe the
current data source (see fig. 319).
To obtain the structure of an external data source, the system performs the
following actions:
„„ It attempts to define the fields that form presentations of dimension tables. If the
systems performs the task with errors, the presentation field may be specified
manually.
„„ It transforms the data source column types into 1C:Enterprise types to be used
to specify the object attribute types. All types from an external data source
are transformed into the following 1C:Enterprise types: number, string, date,
Boolean, unique identifier, binary data and types related to the data source
dimension tables.
„„ It attempts to define types for dimension table fields. In  this case, the system
tries to define the type of data stored in  a dimension table column, and if this
2-886 1C:Enterprise 8.3. Developer Guide

can be considered a  reference to data from another dimension table, the system
specifies the corresponding type in  the column. If the system has selected an
incorrect table column type, it  can be changed manually.

Fig. 319.  External data source cubes wizard

Next, mark objects to be transferred to the metadata of the application.

If Remove objects that are not available in  the external data source from the
configuration is  set, the objects (cubes, dimension tables, dimension table fields,
dimension, and resources) that are absent in an external data source (a cube or
a  resource has been deleted from the external source) are deleted from the configu-
ration when the cube wizard terminates.
Click Finish to load an external data source structure.

23.2.4. Query Language Limitations When Using

an Analytical External Data Source
The following limitations should be taken into consideration when working with
cubes and measurement tables in  the query language:
Microsoft SQL Server
Expression Oracle Essbase IBM Infosphere Warehouse
Analysis Services
ALLOWED – – –
DISTINCT – – –
GROUP – – –
HAVING – – –
JOIN – – –
UNION – – –
Subqueries – – –
Chapter 23. External Data Sources 2-887

Microsoft SQL Server

Expression Oracle Essbase IBM Infosphere Warehouse
Analysis Services
FOR CHANGE – – –
EMPTYTABLE – – –
YEAR Yes – –
QUARTER Yes – –
MONTH Yes – –
DAYOFYEAR Yes – –
DAY Yes – –
WEEK Yes – –
DAYOFWEEK Yes – –
HOUR Yes – –
MINUTE Yes – –
SECOND Yes – –
BEGINOFPERIOD Yes – –
ENDOFPERIOD Yes – –
DATEADD Yes – –
DATEDIFF Yes – –

Where:
„„ – – the value specified is  not supported when working with a  corresponding
OLAP system;
„„ Yes – the value specified is supported when working with a corresponding
OLAP system;

23.2.5. An OLAP Server Connection String

An OLAP server connection string looks as follows:
http://<OLAP host address>:<port>/<source>?<parameters>

Where:
„„ OLAP host address, port, source – the OLAP system access address created by
the rules that are described in  the OLAP system documentation.
„„ parameters – parameters used by 1C:Enterprise to access OLAP system data.
Parameters are set as Parameter=Value. Parameters are separated by the &
character. The  following parameters are used:
○○ ProviderName – service name of XMLA OLAP source.
○○ DataSourceName – name of the OLAP source.
○○ Catalog – catalog (or database) name of the OLAP source.
Sample connection strings are shown below:
For Microsoft SQL Server Analysis Services:
http://localhost:80/msolap/msmdpump.dll?ProviderName=Microsoft Analysis Services& DataSourceName=
host&Catalog=Adventure Works DW
2-888 1C:Enterprise 8.3. Developer Guide

For Oracle Essbase:

http://localhost:13080/aps/XMLA?ProviderName=Essbase XML for Analysis&DataSourceName=host&Catalog=Sample

23.3. EXTERNAL DATA SOURCE MANAGEMENT

Before you can use data from external sources in  an application, you should specify
the connection parameters for the external sources being used. The  Management
of external data sources function that is called in the All functions  – Standard
window is  used for this purpose.

Fig. 320.  External data source management

This form lists all external data sources created in  the Designer and available to the
user opened this form.
The Connected column specifies the external data source connection status in  the
current session.
The Administration menu can be used to specify general connection options (the
Change common parameters command) and specific user connection options, if
they are different from the general options (Change user parameters).

Fig. 321.  Connection options

Chapter 23. External Data Sources 2-889

The checkbox in  the left side of the form (before the option names) means that this
option is  used in  this set of connection parameters. Options are analyzed in  the
following order:
„„ Options set for the session using the SetSessionConnectionOptions()
method of the external data source manager.
„„ Options set for the user in an interactive configuration or using the
SetUserConnectionOptions() method of the external data source manager.
„„ General options set interactively or using the SetGeneralConnectionOp-
tions() method of the external data source manager.
The resulting set of options will be used to connect to the external data source.
If some option is  specified in  multiple settings, the first value from the list given
above will be used.
For example, you can combine connection options as follows:
„„ The user and user password are specified in  session connection options.
„„ The connection string with an external data source base is specified in the
general parameters.
„„ Another connection string is  specified as a  specific user parameter that can be
used to test the application.
When you are specifying a  connection string you should remember that access to
external data are implemented not from the computer where configuration takes
place, but from another computer (see the description on page 2-890).
If you click the Connect button, a  dialog opens where you can set (or refine) the
connection options for the selected external data source.

Fig. 322.  Connection options

The necessity of specifying a  user name and password in  this dialog depends on
the ODBC driver and connection string content. There are situations when a  login
and password are not needed. If the user is  not an administrator of the external
data source, the Change general options and Change custom options buttons are
not available.
The Use operating system authentication check box is  available only if the user has
the SessionOSAuthenticationChange right.
2-890 1C:Enterprise 8.3. Developer Guide

When the Connect button is  clicked, the external data source is  connected. If the
connection is successful, content of the Connected column of the external data
source list is  changed.
If the Disconnect button is clicked, 1C:Enterprise is disconnected from the
selected external data source.

23.4. CONNECTING TO AN EXTERNAL DATA SOURCE

IN  1С:ENTERPRISE MODE
When an operation is executed that needs to get data from an external data
source, an attempt to connect is  made if this data source wasn't already connected.
If connection is  successful, any actions currently being performed are continued.
If connection fails, an exception is  called.
If an exception is  raised in  a client application that is  related to the connection of
an external data source, a  dialog is  shown to the user in  which he/she can refine
the connection options (if the user has rights to change the options) and reconnect.
If connection is  successful, the user is  prompted to repeat the action that caused
a  connection error.
NOTE
In version 8.2.13 compatibility mode, ,sometimes the external data connection
dialog cannot be displayed when you are working with a  dynamic list.
You can also connect to a  data source manually. The  Management of external data
sources standard function is  used to do this.

23.5. USING EXTERNAL DATA SOURCES

23.5.1. The Execution Location
of External Data Source Queries
External data source queries are executed:
„„ file mode version – on the computer with the client application.
„„ file mode version with web server access – on the computer where the web
server extension is  running.
„„ client/server variant – on a  computer running the following:
○○ a service for working with external data sources via ODBC: to access rela-
tional data sources.
○○ a service for working with external data sources via XMLA: to access
analytical data sources (OLAP systems).
Chapter 23. External Data Sources 2-891

23.5.2. Using External Data Sources

If an external data source contains data from both relational and analytical data
sources, their simultaneous use is  not supported. This  is  due to the fact that at any
time an external data source may be connected either to a  relational DBMS or to an
analytical one.

23.5.2.1. In queries
To external analitycal sources
External data source tables can act as query sources. In  this case an external data
source table is  described as follows:
ExternalDataSource.<Source name>.Table.<Table name>

Example:
SELECT
Products.Code,
Products.Description,
Products.SKU
FROM
ExternalDataSource.DBF.Table.Products AS Products

This example selects the Code, Name and Article fields from the Products table
of the DBF external data source.
Temporary tables can be used in  queries to an external data source. In  this case
the system attempts to create a  temporary table directly in  the database connected
with the external database. An exception is  called when the database management
system does not support the creation of external data sources. When called, the
name of the temporary table is  generated as follows:
ExternalDataSource.<External data source name>.TemporaryTable.<Temporary table name>

Example:
SELECT Name, ProductID
INTO ExternalDataSource.AdventureWorks.TemporaryTable.Balance
FROM &ValueTable

SELECT Name, ProductID

INTO ExternalDataSource.AdventureWorks.TemporaryTable.Balance
FROM ExternalDataSource.AdventureWorks.Table.Production_Balance

When using external data source queries remember the following:

„„ One query can use one data source. Simultaneous usage of, for example, an
external data source and a  1C:Enterprise infobase is  not supported.
2-892 1C:Enterprise 8.3. Developer Guide

To external analytical sources

Objects of analytical external data sources may function as query sources.
The  cube of an external data source may be described as follows:
ExternalDataSource.<Source name>.Cube.<Cube name>

For example:
SELECT FIRST 10
AdventureWorks.InternetSalesAmount
FROM
ExternalDataSource.OLAP.Cube.AdventureWorks AS AdventureWorks

In this example, the first ten InternetSalesAmount resources from the cube
AdventureWorks of the OLAP external data source are received
CAUTION!
We recommend you do not obtain all records from an external data source cube.
The  number of entries is  very large and may cause the system to overload.
A cube dimension table of an external data source may be described as follows:
ExternalDataSource.<Source name>.Cube.<Cube name>.DimensionTable.<Dimension table name>

Example:
CHOOSE
AdventureWorksMeasurementTableProduct.Ref
FROM
ExternalDataSource.OLAP.Cube.AdventureWorks.DimensionTable.Product AS AdventureWorksDimensionTableProduct

In this example, a  list of references to the Product measurement table members

is  obtained from the cube AdventureWorks of an external data source OLAP.
Temporary tables may be used in an external data source query. An attempt
is made to create a temporary table directly in the database connected to an
external data source. If DBMS does not support creating external data sources,
an exception will be thrown. The  name of a  temporary table when it  is  queried
is  created as follows:
ExternalDataSource.<Name of external data source>.TemporaryTable.<Temporary table name>

If external data sources are used in  queries, remember of the following limitations:
„„ Only one data source may be used in a query. The simultaneous use of an
external data source and, for example, 1C:Enterprise infobase data, is not
supported.
Chapter 23. External Data Sources 2-893

23.5.2.2. In the Data Composition System

The data composition system can use datasets from different data sources. Thus
you can create a  dataset describing a  list of products. Data in  this dataset will be
received from 1C:Enterprise infobases. Another dataset can describe data received
from an external data source, for example a  product sales table from an external
data source.
Then you can configure any dataset links in  the data composition scheme designer
and receive information for the report simultaneously from 1C:Enterprise and an
external data source.

23.5.3. Rules for Converting Values

When data are extracted from external sources, the system automatically converts
this data to the type specified for the corresponding field in the application.
Conversion is  performed according to the following rules:
„„ String type:
○○ A string value is  converted to a  string value.
○○ A numeric value is converted to a string value (the regional operating
system settings on the computer where an external data source query
is  executed are used for the conversion).
○○ The date value is  converted to a  string value (the regional operating system
settings on the computer where an external data source query is  executed
are used for the conversion.
○○ The unique ID value is  converted to a  string representation of the unique
ID value.
○○ Binary data (and other data types) are converted to a  string that is  a text
representation of converted data in  the hexadecimal format.
„„ Number type:
○○ A numeric value is  converted to a  number.
○○ For a  string value, an attempt is  made to convert the string to a  number
according to regional operating system settings on the computer where an
external data source query is  executed are used for the conversion.
○○ An exception is  raised for all other data types.
„„ Boolean type:
○○ A numeric value is converted to False if it is equal to 0, and
it is converted to True for all other values in  an external data source.
○○ Binary data are converted based on the value of the first data byte. If the first
byte is  0, the conversion result will be False, and the result will be True
for all other values.
○○ An exception is  raised for all other data types.
2-894 1C:Enterprise 8.3. Developer Guide

„„ BinaryData type:
○○ All types are converted to binary data.
„„ Date type:
○○ The date value is  converted to a  Date-type value.
○○ An exception is  raised for all other data types.

23.5.4. An external data source included in  a separator

If the external data source is  part of a  common attribute, the following should be
considered:
„„ The structure of external data source tables is  not changed, and therefore the
data are not separated.
„„ The parameters of the connection to external data sources are stored corre-
sponding to separator values that include the external data source.
„„ The unused separator is  an individual value corresponding to which the param-
eters of the connection to external data sources are stored.
Therefore, when an external data source is included in the separator, you can
perform one of the following use scenarios:
„„ The data available for users of different data areas is located in different
databases with similar table structures. Since the parameters are stored corre-
sponding to the separator values, you can configure the work with the required
database for each data area.
„„ The data available for users of different areas are located in  one database but
access to them is  controlled by database management system tools (user name
and password). In  this case you can specify the name and password of the user
on whose behalf data are accessed.
The scenarios provided are not exhaustive. They are given only as an example to
illustrate the use of the external sources of data that are part of the separator.
Chapter  24

THE DATA SEPARATION

MECHANISM

The data separation mechanism is  a special mechanism that is  used to divide all
stored data and application workflow in  different parts.

24.1. OVERVIEW
If the Data split property of a  common attribute is  set to Split, the data separation
mode is  enabled and:
„„ Configuration objects behavior is  changed for configuration objects included
in  the common attribute (hereinafter referred to as a  separator).
„„ The current separator value and its usage flag are determined for every separator
in  the infobase.
„„ Configuration objects included in  such common attributes are called separated
configuration objects.
„„ A configuration with such common attributes is  considered a  shared configu-
ration.
„„ An infobase with a  separated configuration is  called a  separated infobase.
„„ Infobase data available for selected separator values and data of configuration
objects not separated are called a  data area.
In all database record reading operations 1C:Enterprise automatically selects only
those records used whose separator values match the current separator values.
When data are written, the platform checks that the recorded data contain values
of the used separators equal to current separator values or equal to default values of
the corresponding types. If it  is  not, an exception is  called.
2-896 1C:Enterprise 8.3. Developer Guide

Example:
// Initially object is  recorded with the value of the separator
// Subscriber = 1
Object = ObjectRef.GetObject();

// Change separator value in  the current session

SessionParameters.SubscriberValue = 2;

// Object will not be recorded and the exception will occur

Object.Write();

If recorded data contain separator values equal to default values of the corre-
sponding types, current session separator values will be written in object
separators. For separators not used in  the current session:
„„ When data are read, a  filter is  not used for these separators.
„„ When data are modified, the values in  recorded data are used.
A separator can include the following configuration objects:
„„ Constants
„„ Catalogs
„„ Documents
„„ Sequences
„„ Document journals
„„ Charts of characteristic types
„„ Charts of accounts
„„ Charts of calculation types
„„ Business processes
„„ Tasks
„„ Information registers
„„ Accumulation registers
„„ Accounting registers
„„ Calculation registers
„„ Exchange plans
„„ Scheduled jobs
„„ infobase users (see page 2-899)
Note that sequences and document journals are separated objects only if they
include separated configuration objects. Contents of object separators included
in  a sequence or a  document journal should be identical.
A separator in the Independent and Shared mode can be used in data access
restrictions (see page 1-188).
Separator type can't be composite.
Chapter 24. The  Data Separation Mechanism 2-897

If a  common attribute acts as a  separator, it  has some additional properties that
affect system behaviour, and the behavior of configuration objects included in  the
separator also changes. These properties are described in greater detail in the
following sections.

Fig. 323.  Common attribute with separation

IMPORTANT!
You cannot change infobase regional settings when working with Microsoft SQL
Server if a  String-type separator is  being used.
IMPORTANT!
Data separation in  Microsoft SQL Server 2000, IBM DB2 9.1 and other versions
of IBM DB2 is  not supported if case-sensitive comparison of strings is  set in  the
database management system (if the COLLATION_SEQUENCE parameter value
is not UCA500R1_LROOT_AN_CX_EX_FX_HX_NX_S2).

24.2. COMMON ATTRIBUTE PROPERTIES

24.2.1. Using Separated Data
The Usage of split data property determines the ability to use separated configura-
tion objects data if the separator is  not used in  the 1C:Enterprise mode:
„„ Independent – any access to separated objects is disabled (except exchange
plans, for more details see page 1-405) if the separator is not used in the
current infobase session. In  this case the separator is  not available in  the object
model, the query language, XML and XDTO export formats and data access
2-898 1C:Enterprise 8.3. Developer Guide

restrictions. When separated data are written, the system automatically popu-
lates the common attribute with values set in  the current session.
This mode can be used when an application uses the data of only one data area.
IMPORTANT!
In this mode database object references can be identical for objects written
in  different data areas.
„„ Independent and Shared – enables working with separated objects regardless
of separator usage in  the session. In  this mode only the data area determined
by the values of used separators will be available. In  this case the separator
is  available in  the object model, the query language, XML and XDTO export
formats and data access restrictions. In  this mode you can't create predefined
items for objects included in  such separators. If all of the separators in  which
the object is  included are not used in  the session, working with this object will
be less efficient.
This mode can be used in  cases when an application in  most situations works
only with data from one data area (e.g., when documents are entered), and
in  some modes it  can use the data of multiple or all areas, for example, to get
consolidated reports.
IMPORTANT!
In this mode database object references can't be identical for different objects
written in  different data areas.

24.2.2. The Separator Value and Usage Flag

The Data split value property defines a session option that stores a separator
value set in  the current session. The  session option type should exactly match the
separator type.
The Data split usage property defines a  session option (Boolean type) managing
separator usage. If the value of the specified session option is  set to True, it  means
that the separator is  used in  the current session (see fig. 324).
You can change session options in the process of system operation if the user
on behalf of which the session is  running has the rights to change the necessary
session options. 1C:Enterprise does not guarantee application data integrity after
session options change.
Changing a session option value referenced by at least one separator
in  1C:Enterprise script leads to the following:
„„ The object cache is  cleared.
„„ Reusable values are deleted (see page 1-178) both on the client side and server
side.
Separator values can be specified in the 1C:Enterprise 8 startup command line
using the Z option or in  the connection string using the Zn option (see page 2-900).
Chapter 24. The  Data Separation Mechanism 2-899

Fig. 324.  Session options and common attribute

24.2.3. Users Separation

The User split property determines which part of the user list will be available
depending on whether this separator is  used or not. If the property is  set to Do
not use, a  single user list is  used for all separator values. Users separation is  used
when the user list is  accessed programmatically and in  the Designer when you are
editing the user list.
To determine whether a  user is  available in  a session you can use the following
table (related to a  separator):
Separator is  used in  the session Separator is  not used in  the session
The value is  set for Available if separator values are equal Available
the user
The value is  not set Not available Available
for the user

When editing a user, you can specify values for all separators specified in the
configuration, not only those that have the User split property set to Split. Separator
values specified in infobase user properties will be used to set separator values
at the start of the current user session. Separator values in a command line or
a  connection string have a  higher priority than the values specified in  user proper-
ties, if the user is  authorized to change the corresponding session parameters.
2-900 1C:Enterprise 8.3. Developer Guide

24.2.4. Authentication Separation

The Authentication split property is  used to manage the creation of users with the
same name for different data areas. If the property is  set to Do not use, the unique-
ness of user names is  tracked for all data areas. If the property is  set to Split, users
with the same names can be created in  different data areas. For example, you can
create multiple Administrator users who will differ only by their separator values
(for separator values not set too).
If the Subscriber separator exists (the Number type) and its Authentication split
property is  set to Separate, you can create the following user list:
User name Subscriber separator value
Administrator Not set
Administrator 1634
Administrator 2245
Administrator 1245

If the Authentication split property of this separator is  set to Do not use, you can't
create this list. User names should be unique, for example:
User name Subscriber separator value
Administrator Not set
Administrator1634 1634
Administrator2245 2245
Administrator1245 1245

24.2.5. Conditional Separation

24.2.5.1. Overview
Conditional separation is  necessary when the application will be used both in  sepa-
rated and non-separated versions. For example, an application can be used for
a  stand-alone operation. In  this case separators are not used, but they are provided
in  the application. But the application can also be used for a  number of subscribers
who are not related to each other (with an independent dataset in  the infobase).
Such behavior can be implemented using conditional separation: in  case of stand-
alone usage separation is  disabled, but in  the separated mode it  is  enabled.
Conditional separation works as follows:
„„ For a  separator (or an object included in  the separator), you can set an object
storing separator state for this separator.
„„ By changing this object's value you can enable or disable separation with this
separator for all objects (if conditional separation is  set for the separator itself)
or selected objects (if conditional separation is set for the object included
in  the separator).
Chapter 24. The  Data Separation Mechanism 2-901

„„ If the separator is  conditionally disabled, the default value of this separator type
will be used as the separator value.
NOTE
For every separator, the conditional separation value can't directly or indirectly
depend on the value of the separator.
Recursive conditional separation management is  possible when conditional separa-
tion is  configured for a  separator used to determine the conditional separation of
another separator. In  this case determination of the conditional separation state will
start with a  separator, the value of which is  not conditionally separated (but affects
other objects involved in  conditional separation) and then will continue, until the
conditional separation state is  defined for a  separator, the state of which does not
affect any separator. It  is  impossible to create cyclic conditional separation.
Conditional separation can enable or disable separation with the following methods:
„„ For all objects included in  a separator. In  this case the Conditional split sepa-
rator property should be used.
„„ For individual objects included in a separator. The  Conditional split column
in  the separator editing window should then be used.
„„ Using a  combination of the properties described above.
The following specifics should be taken into consideration when conditional sepa-
ration is  implemented:
„„ The following items can act as an object storing conditional separation value:
○○ Boolean-type constant that is not separated by the separator for which
conditional separation is  configured.
○○ Boolean-type attribute of a  reference configuration object that:
□□ is not included in the separator for which conditional separation
is  configured;
□□ should act as a  type of another separator and the separator of this type
should be the only one.
„„ On system startup an initial setting of session options storing the usage flag and
separator values is  performed according to the startup command line options or
values specified for the infobase user. For details on setting separator values on
startup, see page 2-910.
„„ If common attribute separation is  conditionally disabled:
○○ When data are read or written, the values of the current session options
managing separator value and usage are ignored. In  this case the following
values are used:
□□ Usage flag – True (the separator is  used).
□□ Separator value – the default value for this separator type.
2-902 1C:Enterprise 8.3. Developer Guide

○○ When infobase user data are read or written, values of the current session
options managing separator value and usage are ignored. In  this case the
following values are used:
□□ Usage flag – False (the separator is  not used).
□□ Separator value – not used.
„„ If the value that determines conditional separation is  not read or unambiguous,
an exception is  raised.
„„ If the separator used in  another separator's conditional separation is  not used,
the other separator is  also considered as not used.
„„ If all separators are disabled in the session (using conditional separation),
infobase actions previously not available become available if at least one sepa-
rator is  used.
If conditional separation is  configured both in  the common attribute property (the
Conditional split common attribute property) and using the Conditional split column
of the common attribute contents, one of the following values will be used as the
separator value:
„„ The current separator value (set in  the corresponding session option), if condi-
tional separation is enabled both by the object (an attribute or a constant)
specified in  the corresponding common attribute contents column and by the
object (an attribute or a  constant) specified in  a separator property.
„„ The separator type default value, if conditional separation is  disabled with any
method.
NOTE
Conditional separation does not work in the Designer. It is considered that
attributes are always enabled in  a Designer session.

24.2.5.2. Conditional Separation Set in  Common Attribute Properties

Using a  Constant
A separator can be completely disabled using a  constant. The  constant should be
of the Boolean type and should not be separated by the attribute (see fig. 325).
IMPORTANT!
At 1C:Enterprise initial startup (after conditional separation is  added), the con-
stant value will be False and separation will be disabled.
Let's review this case in  more detail.
Chapter 24. The  Data Separation Mechanism 2-903

Fig. 325.  Conditional separation using a  constant

We have the Subscriber common attribute of the Number type. The  Products
catalog is  included in  this attribute with the following contents:
Code Name Subscriber
1 Sandals 0
2 Boots 1
3 Felt boots 2
4 Sneakers 1
5 Slippers 0

Conditional separation determined by the SeparationBySubscribers constant

is  used for the common attribute. If the constant is  set to False, the separator does
not work (separation is off); if the constant is set to True, the separator works
(separation is  on).
Thus, the following scenarios are possible:
„„ The Subscriber separator value is  1, the separator is  used and the Sepa-
rationBySubscribers constant value is True. In this session separation
2-904 1C:Enterprise 8.3. Developer Guide

is conditionally enabled (for the Subscriber separator). In  this scenario the
following items are available in  the catalog:
Code Name Subscriber
2 Boots 1
4 Sneakers 1

„„ The SeparationBySubscribers constant value is False. In this session

separation is  conditionally disabled (for the Subscriber separator). In  this
scenario, regardless of the SubscriberUsage and SubscriberValue options
values, the following items are available in  the catalog:
Code Name Subscriber
1 Sandals 0
5 Slippers 0

Using Object Attributes

A more complex way of managing conditional separation is  used if other sepa-
rator data are used for conditional separation of a  single separator. Then different
behavior is  possible within different data areas for a  separator describing another
data area.
Suppose that there is  a set of configuration objects describing regulatory and refer-
ence information (RRI): Banks, Currencies, VAT tax rates catalogs. The  following
ability should be implemented:
„„ different company groups can be accounted in  an infobase;
„„ every company group consists of organizations;
„„ regulatory and reference information objects content can be common both for
all company group organizations and individually for each organization.
The following configuration objects are required to implement this scheme:
„„ The CompanyGroup catalog with the SingleRRI attribute of the Boolean
type
„„ The Organizations catalog
„„ The Banks catalog
„„ The Currencies catalog
„„ The VATRates catalog
„„ The CompanyGroup separator of CatalogReference.CompanyGroup type
„„ The Organization separator of CatalogReference.Organizations type.
This  separator includes only objects describing RRI:
○○ The Banks catalog
○○ The Currencies catalog
○○ The VATRates catalog
Chapter 24. The  Data Separation Mechanism 2-905

The CompanyGroup separator includes all the catalogs noted (except for the
CompanyGroup catalog), since we need a  separate list of organizations and RRI
content for each company group.

Fig. 326.  CompanyGroup separator contents

The Organization separator includes the Banks, Currencies and VATRates

catalogs only. These catalogs are RRI and two usage options are needed for them:
„„ for each organization of the selected company group
„„ for all organizations of the selected company group

Fig. 327.  Organization separator contents

The CompanyGroup catalog is  not included in  the Organization separator, since
it  is  required by conditional separation rules (see page 2-900).
2-906 1C:Enterprise 8.3. Developer Guide

Now for every CompanyGroup separator (CompanyGroup catalog item) you can
specify the SingleRRI attribute value:
„„ The attribute is  set to False – conditional separation is  disabled and for any
Organization separator value (within one value of the CompanyGroup sepa-
rator) there will be a  single set of Banks, Currencies and VATRates catalog
values.
„„ The attribute is  set to True – conditional separation is  enabled and for any
RRI separator value (within one value of the CompanyGroup separator) there
will be an individual set of Banks, Currencies and VATRates catalog values.
Actually, when the SingleRRI property is  changed, conditional separation for the
Organization separator is  enabled or disabled.
Suppose that the following records exist in  the CompanyGroup catalog:
Name SingleRRI Reference
Progress False GL1
Trading house True GL2

The following records exist in  the Organization catalog (two records for every
CompanyGroup separator value):
Name CompanyGroup Reference
Component parts base GL1 ОР1
AC World GL1 ОР2
Trade and Building GL2 ОР3
Light GL2 ОР4

The Banks catalog will contain the following information:

Name CompanyGroup Organization
Alpha Bank GL1 Empty reference
SberBank GL1 ОР1
VTB GL1 ОР2
Avangard GL2 ОР1
Uralsib GL2 ОР2

Let's have a  look at which data will be accessible in  different sample scenarios.
Example 1
The SingleRRI attribute for the Progress item is  set to False.
This means that separation is disabled for the Banks catalog. So this catalog’s
contents do not depend on the Organization separator value and the value equal
to this separator type default value will be written to the Banks catalog item (for the
Organization separator). In  our example, this value is  an empty reference (since
Chapter 24. The  Data Separation Mechanism 2-907

the Organization separator type is  a catalog reference). So if the CompanyGroup

separator is  set to GL1, the Banks catalog list will display only one record: Alpha
Bank.
Example 2
The SingleRRI attribute for the Progress item is  set to True.
This means that separation is  enabled for the Banks catalog. Thus, this catalog’s
contents depend on both the CompanyGroup separator value and the Organiza-
tion separator value.
Then for the Progress company group and AC World organizations, only VTB bank
will be included in  the bank list.
By changing the value of the SingleRRI (and separator values) when the system
is  operated, you can get this or that Banks catalog list (according to the conditional
separation rules).

24.2.5.3. Conditional Separation Set for an object (the Content Property)

Conditional separation can be set for every configuration object included in  a sepa-
rator. In  this case separation is  disabled not for all objects included in  a separator,
but for objects for which conditional separation is  configured.
Conditional separation can be controlled both by a  constant and a  configuration
object attribute (see page 2-900).
Consider an example of this type of separation.
Suppose that multiple subscribers keep accounting in  a single infobase and at the
same time you can keep accounting on behalf of several partner organizations. One
situation is  possible when all partner organizations operate a  single list of ware-
houses and another situation is  possible when you can generate an individual list of
warehouses for each organization.
The following configuration objects are required to implement this scheme:
„„ The Organizations catalog
„„ The Warehouses catalog
„„ The Subscriber separator of the CatalogReference.Subscribers type
„„ The Organization separator of the CatalogReference.Organizations
type
We need to perform the following steps to implement this scheme:
„„ The Organization catalog should be excluded from the Organization sepa-
rator.
„„ For the Warehouses catalog (included in  the Organization separator), you
need to set conditional separation using the SeparateWarehouseList attribute
of the Subscribers catalog.
2-908 1C:Enterprise 8.3. Developer Guide

Suppose that the following two records exist in  the Subscribers catalog:
Name SeparateWarehouseList
Subscriber 3453 True
Subscriber 4617 False

If a  user logs in  on behalf of subscriber #3453, it  is  possible to keep a  separate
warehouse list for each organization, since the SeparateWarehouseList attribute
is  set to True (Warehouses catalog separation is  enabled in  the Organization
separator).
At the same time, when a user logs in on behalf of subscriber #4617, the list
of warehouses will be the same for all organizations, and the SeparateWare-
houseList attribute will be set to False (Warehouses catalog separation
is disabled in the Organization separator).

24.2.5.4. Specifics of Conditional Separation in  a Distributed System

Using conditional separation in a distributed system has some specific points
which you should know. These can be divided into "logical" and "technical".
"Technical" features include the inability to arbitrarily change the status of the
object controlling conditional separation in a separated session, if this object
is  included in  an exchange plan. It  is  related to the specifics of automatic object
modification registration by separated exchange plans (see page 2-1232). If changes
are made automatically, you can change the object controlling conditional separa-
tion either in  a non-separated session or if the current object session is  False, i.e.,
you can only enable conditional separation but you cannot disable it.
"Logical" features are related to the fact that changing the conditional separation
state in  the main node of a  distributed infobase significantly affects the state and
behavior of the whole distributed system. This modification can affect one data
area if conditional separation is  controlled by an object attribute acting as another
separator type (see page 2-904 for an example of this). Changing a conditional
separation state can affect the entire infobase if conditional separation is  used to
switch between two modes of an application (see page 2-902 for an example of this).
Thus, in  the first case (the RRI example) when conditional separation is  changed,
regulatory and reference information in the peripheral infobase will be lost for
users. So access for changing the attribute controlling conditional separation should
be granted only to the data area administrator or a  person with sufficient privileges
to accept this type of changes.
The second example (switching the application mode) will affect the entire
infobase. In  peripheral bases, users can "lose" all their data (due to separator value
change), etc. Obviously, only an infobase administrator can accept a  change that
critical (or a  person entitled for such actions), as other users can't event read this
attribute (or constant).
Chapter 24. The  Data Separation Mechanism 2-909

24.3. DETERMINING AN ABILITY TO PERFORM

AN ACTION OR A  DATASET
When multiple separators are used in  the system, the following rule should be used
to determine the availability of a  certain action with this or that object:
„„ For every separator that separates the required object, an ability to perform the
necessary object is  determined as there is  only one separator in  the system (of
course, the separation mode is  taken into account – independent or independent
and joint).
„„ Results for all separators are summed with the AND operation.
Further sections discuss the rules of execution of different actions with an object
for one separator (if not explicitly stated otherwise). Then to obtain the final action,
this rule should be applied if the object is  part of multiple separators.
For example, the system has two independent separators: Subscriber and
Organization. There are two catalogs: Nomenclature and Contractors. Every
catalog is  separated by both separators.
Example 1
You need to determine an ability to receive a list of nomenclatures, if the
Subscriber separator is  used and the Organization separator is  not used.
Since both separators are independent, the separator should be used to receive the
catalog's list. Thus:
„„ You can get a  nomenclature list for the Subscriber separator, since the sepa-
rator is  used. The  result is  True.
„„ You can't get a  nomenclature list for the Subscriber separator, since the sepa-
rator is  not used. The  result is  False.
„„ Thus in a session with such separator settings it is impossible to see the
catalog list (True AND False = False).
Example 2
You need to determine an ability to get a  list of contractors, if both separators are
used.
Since both separators are independent, the separator should be used to receive the
catalog's list. Thus:
„„ You can get a  contractor list for the Subscriber separator, since the separator
is  used. The  result is  True.
„„ You can get a  contractor list for the Organization separator, since the sepa-
rator is  used. The  result is  True.
„„ Thus, in a session with such separator settings it is impossible to see the
catalog list (True AND True = True).
2-910 1C:Enterprise 8.3. Developer Guide

Example 3
You need to determine which values for the User column will be returned by
GetEventLogFilterValues(). Two separators are created in  the system and the
current session uses the first one and does not use the second one. Thus:
„„ For the first separator, the method returns only those users who were registered
in  the event log for separation values equal to values in  the current session.
„„ For the second separator, the method returns all users (for more details, see page
2-1240).
„„ Thus in  the session with the specified state of separators the method returns
only those users that are an intersection of lists for the first and the second sepa-
rators (the AND operation).

24.4. SETTING SEPARATOR VALUES ON STARTUP

When 1C:Enterprise starts up, there could be a  need to specify separator values
directly in  the startup command line (e.g., to implement authentication, if authenti-
cation separation is  selected).
If one or more separator values are not specified in the command line, missing
separators are taken from the separators specified for the current user. If the same
separator is  specified both for the user and in  the command line and their values
do not match, the usage flag and separator value will be set from the command line,
if the infobase user has the right to set session options storing the usage flag and
separator value. Otherwise user authentication will not be implemented.
When a client run in the Designer is debugged, you can specify separators
in the startup configuration dialog in the Designer (see page 2-1154). When
specifying a  user on behalf of which the system should start up, users are available
for selection. The  list of users is  restricted by set separator values that separate
authentication.
In the process of infobase user authentication, session parameters, which are refer-
enced by the Usage of data split and Data split value properties of the Common
attribute metadata object, are assigned values defined for the user. Before any
1C:Enterprise script code is executed (in the session module as well), session
option values are set and when they are accessed the SessionParametersSet-
ting event handler will not be called.
Note that the separator value is  identified based on the passed identifier without
considering usage of other separators, i.e., the separator value does not depend on
the procedure of setting other separator values (and usage flag). If the system can't
unambiguously determine the separator value based on its identifier (for example,
there are two catalog items with the same code), an exception is  raised.
Chapter 24. The  Data Separation Mechanism 2-911

If separator usage and the separator value (see below) specified in  the startup line
are different from values specified for a  user, then:
„„ If a  user has the rights to change session parameters, storing the separator value
and usage flag, these values are set from the startup command line.
„„ If these rights do not exist, authentication fails.

24.4.1. The Client Application Command Line

The Z command line option is  used to set separator values.
Syntax:
-Z "[<Flag>][<Value>][,[<Flag>][<Value>]]"

Description:
Every <Flag><Value> pair is used to set one separator. You can't skip
separators. The  <Flag><Value> pairs order matches the order of separators
in  the configuration window. If the common attributes order is  changing (for
example, the list of common attributes is  sorted), you need to change the values
order in  the Z option. <Flag><Value> pairs are comma separated.
Parameters:
<Flag>
Separator usage flag. It  can have only "+" (default) and "-" values. If the "+"
flag is  specified before the separator value (or no flag is  specified), the spec-
ified value will be written to the session option storing the common attribute
value and the session option storing the common attribute flag will be set to
True.
If the "-" flag is  specified before the separator value, this means that the
separator is  not used in  this session (the session option controlling sepa-
rator usage will be set to False), but if the value is specified, it will be
written to the session option storing the common attribute value.
<Value>
Specifies the value that will be set to the session option storing the value of
the corresponding separator. The  separator value is  set in  the text form in  the
following format (depending on the separator type):
„„ For the Boolean type, a  0 (False) or 1 (True) value is  set.
„„ For the Number type, a  number is  set in  the canonic form.
○○ For the Data type, a  date is  specified in  yyyymmddhhiiss format, where:
○○ yyy – year (4 digits);
○○ MM – month number (two digits);
2-912 1C:Enterprise 8.3. Developer Guide

○○ dd – day number (two digits);

○○ hh – hour number (two digits);
○○ ii – minute number (two digits);
○○ ss – seconds (2 digits).
When specifying an option, you should set all date components, i.e., the
option contains 14 digits.
„„ For the String type, text is  specified.
„„ For reference types, a  text representation of the Code or Number standard
attribute. Codes and numbers should be unique for all values of the corre-
sponding configuration object. 0 length code catalogs and documents with
numerators can't be used.
If the "+" or "-" character should be in  the beginning of an option value, the
character is duplicated. If a text string describing a separator value should
include the "," character, the character is  duplicated.
If the value set in  the command line option can simultaneously match values
of different types (e.g., "1" can be True, "1" number, "1" catalog code and "1"
document number), the conversion rule is defined based on the type of the
corresponding separator.
If only a flag is included in the command line ("+" or "-"), but no value
is  specified, the default value of the corresponding type is  used as the separator
value.
Example:
-Z "-0,+001,+,---3"

In this example:
„„ The first separator is  not used, but its value is  indicated: "0".
„„ The second separator is  used and its value is  "001".
„„ The third separator is  used and its value is  the default value for the type
specified as the common attribute type.
„„ The fourth separator is  not used, but its value is  "-3".

24.4.2. The Web Client or Thin Client Connected via

a  Web Server
You can specify separator values when starting a web client (or a thin client
connected via a  web server) using two methods: in  the startup address (command)
line using the Z option and in  the default.vrd file.
Chapter 24. The  Data Separation Mechanism 2-913

24.4.2.1. Using the Z option

Separator values can be set in  the address line using the Z option. The  web client
option format is  similar to the client application startup command line.
Example:
http://localhost/infobase?Z="-FirstSeparator,+"

Characters which are invalid for the URL (RFC 1738, http://www.faqs.org/rfcs/rfc1738.

html) are converted to UTF-8 and encoded according to section 2.2. URL Character
Encoding Issues of the RFC 1738 standard (using % and two hex characters).

24.4.2.2. Using default.vrd

You can configure access to an infobase, so specific separator values will be set by
infobase address and not by the Z command line option or an infobase connection
string. To do this you need to configure the <zones> item of the default.vrd file
accordingly.
You can also disable modification of objects related to the data separation
mechanism if access to an infobase is  enabled using a  web client or a  thin client
connected via a  web server (secure service). This  method should be used when
you need to guarantee that another data area will not be accessible when an infobase
is  accessed via the internet.
For more details on default.vrd file configuration settings, see the "1C:Enterpise  8.3.
Administrator Guide".

24.4.3. External Connection and Connection Strings

The Zn option is used in a connection string and when an external connection
is  started. The  option format is  similar to the client application startup command line.
Example:
Srvr=localhost;Ref=Demo82Srv;Zn="-FirstSeparator,+,---3"

This option can be also specified in  the default.vrd file (in an infobase connection
string) for publication on a  web server.
There is  another method for specifying separators in  the default.vrd file, for more
details see page 2-913.

24.5. SAFE DATA SEPARATION MODE

When different scheduled operations performed within a session with unused
separator values are used, the application solution code whose reliability
is generally impossible to check can be executed. "Reliability" here means
operating in strict compliance with defined restrictions without abusing them.
2-914 1C:Enterprise 8.3. Developer Guide

For instance, the code called should only operate within separator values that the
calling party has set for this code and should not attempt to switch to other data
areas. Any such attempt may result in  an unauthorized access to data of an "alien"
area.
To prevent any attempts to change separator values (and, consequently, the data area
where the program code is  being executed), you can set the safe data separation
mode. To do this, use the SetDataSeparationSafeMode() method. Applying
this method for the separator is  similar to specifying the safe="true" attribute for
the zone item of the default.vrd. file. This  file is  described in  "1C:Enterprise 8.3.
Administrator Guide". Where the safe mode is  enabled via the default.vrd file, you
cannot disable it  by using the SetDataSeparationSafeMode() method.
In the safe data separation mode it  is  not permitted to:
„„ disable separator use, if the separation is  not conditionally disabled;
„„ change the value of the separator used, if the separation is  not conditionally
disabled;
„„ change objects that manage conditional separation:
○○ specified for the separator itself;
○○ specified for objects included in  the separator.
You can set the safe data separation mode for each separator individually. The  safe
data separation mode should be enabled and disabled the same number of times.
However, if the safe data separation mode was enabled (one or more times) within
the procedure or function but was not disabled, the system will automatically
disable the mode as many times as its disabling was not completed within that
procedure or function.
If within the procedure or function the safe data separation mode was disabled for
the selected separator more times than it  was enabled, the system calls an exception.
The execution of this mechanism can be described as follows (there is  Subscriber,
an independent separator, in  the system):
For each SeparatorValue From ListOfSeparatorValues Do

// "Go" to the required area

SetSeparatorValue(SeparatorValue);

// Set the safe data separation mode

SetDataSeparationSafeMode("Subscriber", True);

// Call the required program code

ProcessAreaData();

// Disable the safe data separation mode

SetDataSeparationSafeMode("Subscriber", False);

EndDo
Chapter 24. The  Data Separation Mechanism 2-915

You can check the status of the safe data separation mode by applying the
DataSeparationSafeMode() method.

24.6. DATA AREA DELETION

Sometimes a  data area may become unclaimed during system operation. This  may
be the case, for instance, when a subscriber stops using the service (when each
subscriber works in  one data area) or a  group of companies is  reorganized (when
each company of the group works in  its own area).
Sometimes separators are deleted from the system. But if a separator includes
configuration objects with predefined data, it  cannot be deleted until the predefined
data is  erased (see page 2-1230).
The data area is  deleted by applying the EraseInfoBaseData() global context
method or the /EraseData command string of Designer startup batch mode. In  the
1C:Enterprise script method, the area to be deleted is  defined by values of session
parameters that define separator values in the session from which the method
is  called. The  area defined by the separators used and by any value of separators
that are not used will be deleted.
TIP
It is  recommended that you change the values of the separators that define the
data area right after the method is  executed.
The user must have the Administration right and be able to get exclusive access
to the infobase to call the method. The  exclusive access right should be set via an
explicit call of the SetExclusiveMode() global context method.
When the data area is deleted in Designer startup batch mode, the area to be
deleted is  defined by the /Z parameter of the startup command string (see page
2-910). Where not all separators are set, the area is  defined in  a way similar to
calling the EraseInfoBaseData() method (see above). The system attempts
to get exclusive access to the infobase. In  the case of an error getting exclusive
access, the execution of Designer startup batch mode fails with an error.
IMPORTANT!
If none of the separators is  used in  the session or data deletion is  executed in  an
unseparated infobase, all infobase data will be deleted.
Data will be deleted from:
„„ any tables connected with configuration objects that are part of separators
(including predefined data).
„„ settings storages.
„„ user work history.
„„ the list of infobase users.
2-916 1C:Enterprise 8.3. Developer Guide

„„ Infobase time zone – if independent separators are not defined in  the configura-
tion, this parameter value becomes undefined, otherwise the value is  deleted.
„„ If no separators are used in  the session, the following infobase settings will be
filled with default values:
○○ data lock timeout.
○○ minimum user password length.
○○ user password complexity check.
○○ full text search permit.
„„ If the compatibility mode is set (version 8.3.2 or older), predefined data
receives either values determined in  Designer or default values. If the compat-
ibility mode is  disabled, predefined data will be created when first queried.
„„ The ThisNode item attribute values of exchange plans will be set to their
default values.
„„ Values of nonseparated constants receive default values, values of separated
constants are deleted.

24.7. SPECIFICS OF SYSTEM OBJECTS BEHAVIOR

See the description of system objects behavior specifics on page 2-1229.
Chapter  25

DEVELOPING SOLUTIONS
FOR THE MOBILE PLATFORM

25.1. GENERAL INFORMATION

1C:Enterprise software suite allows you to develop applications for mobile devices
(smart phones, tablet computers). The  Mobile application is  an applied solution
to be executed on the 1C:Enterprise mobile platform. The  Mobile platform is  a
dedicated version of 1C:Enterprise used to execute mobile applications on mobile
devices running iOS (http://www.apple.com/ios/) and Android (http://www.android.com/)
operating systems. The mobile platform architecture is similar to that of the
thin client. A mobile application connects to a  file infobase on a  mobile device.
A mobile application does not require a permanent communication channel
with any component of the external network infrastructure in  order to operate. If
required, external interaction can be implemented using various mobile platform
mechanisms.
In general terms, mobile application development includes the following stages:
„„ It is  decided what type of mobile application is  to be developed:
○○ An application that is independent of any applied solution in a remote
system. In  this case, the data structure for the mobile application is  defined
exclusively by its scope of use. Data exchange is  unlikely to be needed.
○○ A standalone workstation for an applied solution located in a remote
system. In  this case, the data structure is  primarily defined by the applied
solution. However, there will be changes to reflect both the scope of use
and the features of the mobile application. A special data exchange protocol
will most likely be used to exchange data between the applied solution and
a  specific mobile application. The  exchange protocol will not be designed
for exchanges with other solutions.
2-918 1C:Enterprise 8.3. Developer Guide

○○ Universal standalone workstation. In this case, the data structure should

account for specific features of all applied solutions to interact with the
mobile application. The characteristics of the mobile application should
also be taken into account. The  exchange protocol should be universal and
standardized.
„„ It is  specified whether the mobile application is  to operate on mobile devices
only or on mobile devices and computers (e.g., laptops).
„„ The mobile application (including the data exchange mechanisms) is imple-
mented and debugged on a  desktop computer. You must understand that the
mobile platform has a  number of features and characteristics that do not allow
you to verify mobile application operability on a  PC. However, code written
in  the 1C:Enterprise script can only be debugged on a  PC.
„„ Finally, the application interface and functionality is  tested and debugged either
on a  single mobile device or on multiple mobile devices.
TIP
We recommend selecting the standalone workstation option for development as
it  can operate on both mobile devices and PCs.
As you develop the data exchange mechanism, you should remember that appli-
cations with varying versions of the exchange interface need to exchange data.
This  should not cause exchange problems. This  is  related to the fact that updating
an application for the entire infrastructure is  virtually impossible. It  should also be
noted that data synchronization using legacy versions of the exchange protocol can
be used for backup operations before the mobile application configuration update.
When you develop a  mobile application, you should take into account the restric-
tions imposed by the mobile platform as compared with the 1C:Enterprise platform
for a  PC:
„„ Limited set of available configuration objects and mechanisms
„„ Limited set of attribute properties
„„ Limited set of managed form items
„„ Simplified implementation of certain mechanisms (e.g., dynamic list or start
page)
„„ Ordinary forms and ordinary run mode not available
„„ Mobile application debugging tools not available
For a  complete list of features, see page 2-1247.

25.2. THE APPLICATION INTERFACE

The application interface is  similar to the interface that opens forms in  separate
windows, but free switching between windows is unavailable. This means that,
in particular, accessing the main section command interface requires closing all
auxiliary windows.
Chapter 25. Developing solutions for the mobile platform 2-919

25.3. USAGE SPECIFICS

25.3.1. The Global Command Interface
The mobile platform has no sections panel. The mobile platform interface
is  designed to display one form at a  time. Maximum display space is  freed for the
form. Therefore, commands included in  navigation and action panels on a  PC are
incorporated in the main application menu. This menu also includes commands
that allow you to return to the start page, display software information and navigate
to the application list. To open the main application menu:
„„ In iOS, use the Functions button in  the upper left corner of the main application
window.
„„ In Android, use the system button opening the menu.
TIP
We recommend that you take into account the mobile platform capabilities during
command interface development.

25.3.2. User Messages

User messages are displayed in  the message bar. This  bar is  only displayed when
it  contains messages. When the bar is  closed, the message list is  cleared. Clicking
a message activates a form item, if the message is linked to one. To open the
message list again, call the action that reopens the list.

25.3.3. Form
Mechanisms or configuration objects that are not supported by the mobile platform
have no associated form item properties available. For example, the Shortcut prop-
erty or events related to drag-and-drop operations.
The principles and rules of form generation for the mobile platform are generally
identical to the ones for thin client, but there are certain peculiarities that should be
taken into account while developing forms for a  mobile application:
„„ Smartphone displays are mostly vertically oriented (portrait orientation);
therefore, forms have significant width limitations and insignificant height
limitations.
„„ Horizontal scrolling is  not generally used in  mobile devices, as scroll bars are
not permanently displayed on mobile device displays, and users might fail to
notice that a  form (report or table) only displays partial information.
Instead of editing data in a row of a table associated with a tabular section or
value table, the mobile platform provides a special system form. This form
contains all columns for the current table row that are displayed on the parent form.
When you use this form, keep in  mind the following peculiarities:
„„ Columns with the View only property selected are displayed in  the system form,
but are not available for editing.
2-920 1C:Enterprise 8.3. Developer Guide

„„ The system form does not display picture and label fields.
„„ Conditional form appearance applies to the system form.
„„ All event handlers are called.
„„ The system form cannot be edited in Designer nor be modified via the
1C:Enterprise script.
The following form items can be used in  a mobile application form:
„„ Field types:
○○ Text box
○○ Label field
○○ Radio button field
○○ Picture field
○○ Checkbox field
○○ Spreadsheet document field
„„ Button
„„ Table
„„ Decoration: label and picture
„„ All group types
The dynamic list used in  the mobile platform has the following distinctive features:
„„ Only the main table can be used.
„„ Custom query cannot be used.
„„ Attributes cannot be accessed using dot operator.
„„ Dynamic list settings can be managed via the 1C:Enterprise script. To enable
interactive setting, implement the relevant configuration forms yourself.
„„ Interactive list display is  not supported.
„„ Implementation of the Go to beginning and Go to end commands facilitates
navigation to the top or the end of list.
The form navigation panel uses a  special menu that opens as described below:
„„ In iOS, click the window header if it  is  underlined.
„„ In Android, use the system button opening the menu.
In iOS, software buttons are available in  the application title. The  following rules
apply to the display of form buttons in  the application title:
„„ If a  form contains a  default button:
○○ Right-hand part of the title is  displayed:
□□ Default button (with its title).
○○ Left-hand part of the title is  displayed:
□□ Button with the Cancel command and its title (if the command
is  available in  the form).
Chapter 25. Developing solutions for the mobile platform 2-921

□□ Nothing is  displayed, if the right-hand part of the form displays a  button
with the Close command.
□□ Otherwise, a  button with the Close command.
○○ Buttons displayed in  the application title are excluded from the form.
„„ If a  form does not contain a  default button:
○○ Right-hand part of the title displays:
□□ Button with the Cancel command and its title (if the command
is  available in  the form).
□□ Otherwise, a  button with the Close command and its title.
□□ Buttons displayed in  the application title are excluded from the form.
„„ If the form displays a  table related to a  dynamic list that serves as the main
attribute of the form, the right-hand part of the title displays the Create button
(provided that the View only property is  not selected for the table).
„„ If the choice mode is selected for the form, the left-hand part of the title
displays the Close button.
The list of standard commands does not include commands for direct deletion (for
reference type objects), opening Help, list display and form modification.

25.3.4. Working With Files

On mobile devices, all applications operate via a  special mechanism ensuring safe
program execution (sandbox). Within this mechanism, applications are granted
limited access to the file system of a  mobile device. During the mobile application
development, you might need to access the file system, maybe for temporary data
storage or for writing documents generated in  the system, for subsequent exchange
with other computers.
Dedicated functions allow you to access these file system locations:
„„ TempFilesDir() returns the temporary file directory for the application. It  can
be cleared by the operating system, if necessary;
„„ UserDataWorkDir() returns directory recommended for storing "long-term"
user data.
„„ DocumentsDir() returns directory for documents intended for exchange with
external environment (in relation to the mobile application).
Regardless of the actual mobile OS capabilities, we recommend you do not use any
other directories of the mobile device file system in  your work for security reasons
and based on the requirements of mobile OS developers for applied solutions.
2-922 1C:Enterprise 8.3. Developer Guide

25.3.5. Special Features

25.3.5.1. Phone calls and sending SMS messages
Mobile devices may support making phone calls and sending text messages (SMS
messages). These capabilities can be used in  a mobile application. To do so, use
RunApp() or GotoURL() methods and specify a  phone number with tel: prefix,
if you want to make a  phone call, or sms: prefix, if you want to open a  form for
creating a  text message.
Example:
RunApp("tel:+7(999)123-4567");

Mobile devices may handle these commands differently, depending on the oper-
ating system version and device type.

25.3.5.2. Location tools

A large number of mobile devices support finding the geographic coordinates of
where they are located. The  coordinates obtained can also be converted intoto an
address and vice versa. These functions can be accessed via a  location provider.
Each provider is described using a name and a set of parameters (capabilities).
A specific location provider may support a  limited number of capabilities.
In general, the following sequence of actions is  used to work with location tools:
1. Select the required location provider. In each case you should select the
provider that best fits the assigned task. Generally, it is recommended you
select a provider that ensures minimum power consumption and maximum
positioning accuracy.
Example:
// Define provider that is  free of charge and
// uses the cellular network for finding coordinates
SoughtLocationProviderInformation = Undefined;
LocationProvidersInformation = LocationTools.GetLocationProvidersInformation();
For Each LocationProviderInformation From LocationProvidersInformation Do
If NOT LocationProviderInformation.Paid and LocationProviderInformation.UsesCellNetwork Then
SoughtLocationProviderInformation = LocationProviderInformation;
Abort;
EndIf;
EndDo;
If SoughtLocationProviderInformation = Undefined Then
Message("Failed to find the required provider");
Else
Message("Provider found: " + SoughtLocationProviderInformation.Name);
EndIf;
Chapter 25. Developing solutions for the mobile platform 2-923

If your priority is lowest power consumption use the GetMostPowerSa-

vingProvider() method, while if you priority is  the most accurate provider,
use GetMostAcurateProvider() method.
2. Coordinates are found using the selected location provider. Two methods can
be used to obtain coordinates. The  GetLastLocation() method returns the
last location data obtained by the selected provider. Properties of the Loca-
tionData object (returned by the GetLastLocation() method) include the
Date property that describes when location data was obtained. If this informa-
tion was obtained a  long time ago, call the UpdateLocation() method, so that
the location provider re-acquires location data. One of the method parameters
defines a  time-out for location detection. If the method times out, the actual
finding of the coordinates in  this case will depend on the implementation pecu-
liarities of the specific mobile operating system version.
Example:
// If location has never been detected on this device
// or was detected more than an hour ago, update the location and
// get specific coordinates
Coordinates = LocationTools.GetLastLocation(LocationProviderInformationName);
If Coordinates = Undefined OR CurrentDate()-Coordinates.Date > 3600 Then
LocationTools.UpdateLocation(LocationProviderInformationName, 60);
Coordinates = LocationTools.GetLastLocation(LocationProviderInformationName);
EndIf;

3. You can subscribe to coordinate updates. Once the subscription is  no longer
needed, you can disable coordinate change notifications.
After acquiring location data, you can perform certain auxiliary operations with the
obtained location:
„„ Get an address based on coordinates. Use the GetAddressByLocation()
method.
„„ Get location coordinates based on an address. Use the GetLocationByAd-
dress() method.
„„ Display the map with the coordinates for a  single point or for multiple points.
Use the ShowOnMap() method. Please note that iOS will always use the Apple
Maps application, while Android will use Google Maps.
NOTE
For methods for converting coordinates to an address and vice versa to work, your
mobile device must have internet access.

25.3.5.3. Working with multimedia

Mobile devices offer various multimedia capabilities: you can take a photo
and make an audio or video recording. Whether or not these features are avail-
able depends on the mobile device. To determine whether a certain operation
2-924 1C:Enterprise 8.3. Developer Guide

is  supported, special functions are provided: PhotoSupported(), VideoRecord-

ingSupported(), AudioRecordingSupported(). If a mobile device supports
a certain capability, you can use a global context method that activates the
corresponding system application to perform the required action: MakePhoto(),
MakeVideoRecording(), MakeAudioRecording().
Program execution in  the 1C:Enterprise script waits for the required action to be
performed.

25.3.6. Text Input

To enter various data, you can use an on-screen keyboard. As a  rule, you can acti-
vate it  by simply clicking the text box where you want to enter data. Keyboard
features differ, depending on the operating system. In all operating systems the
Enter button helps you navigate text boxes without havng to close the keyboard.
In iOS the keyboard has certain auxiliary features:
„„ Button closing the keyboard.
„„ Buttons that, when clicked, help you navigate to the next/previous text box in  a
form (similar to Tab/Shift+Tab keys on the PC keyboard).
„„ Button clearing the current text box (similar to Shift+F4 shortcut on the PC
keyboard).
„„ Buttons switching the date input mode (for Date type fields).
„„ Calculator mode can be enabled for Number type fields.

25.3.7. Reports
You can generate reports on the mobile platform using one of two different
methods:
„„ Process the existing data and generate a  report in  the 1C:Enterprise script.
„„ Implement a  form in  the mobile platform that can be used to set report genera-
tion parameters (such as filters) and generate a  report in  a remote system that
will return a  spreadsheet document to be displayed on the mobile device.
Selecting one of these options depends on a  number of factors:
„„ Availability of all data required to build a  report in  an infobase of the mobile
application
„„ Availability and quality of the communication channel between the mobile
device and the remote system
„„ Complexity of the report
„„ How the exchange with the remote system is  set up
„„ How you intend to work with the report
„„ Other factors
Chapter 25. Developing solutions for the mobile platform 2-925

If you decide to generate a  report on your mobile device, you must bear in  mind
the mobile platform features (see page 2-1247). Data can be retrieved using selec-
tions, and the report can be generated using software-based spreadsheet documents
(based on a  template) and charts (where necessary) generation.
If the mobile application has a  permanent high-speed communication channel with
the remote system that contains all the required data for report generation, you can
implement report display options (such as filtering or viewing details) only on the
mobile application side. In  this case the report itself is  generated in  the remote
application and is  then returned and displayed on the mobile device.
All intermediate options can also be used: for example, if periodic exchange
is  implemented, you can generate report settings on the mobile device and transmit
them to the remote system in  an exchange session in  order to obtain a  generated
report for display.
Interaction with the remote application can be set up using a  web service (provided
by the remote application) and data exchange based on an exchange plan, etc.
If a  report details display needs to be implemented, please be aware that the mobile
application itself can only display values specified as report cell details. Other
actions should be implemented in  the 1C:Enterprise script, including the retrieval
of a  new report variant based on the assigned filters, etc.

25.3.8. Working With Images

Mobile application works on various mobile devices. One of the distinctive
features of these devices is the resolution and physical size of their displays.
This  is  described by the dpi (or ppi) concept – the number of dots per inch of
display. The  higher the dpi value, the less physical space a  picture of a  fixed size
takes up.
For the image to better fit various displays, you can use a  set of images where each
picture corresponds to a  certain dpi range for a  mobile device display. The  mobile
platform automatically selects the required image from the set, based on the param-
eters of a  specific physical device. The  application programmer does not have to
do anything for the required image to be displayed.
The set of images is  a ZIP-archive that contains 4 images with different names:
„„ l – corresponds to displays with a  resolution of less than 140 dpi.
„„ m – corresponds to displays with a  resolution of resolution from 140 to 180
dpi.
„„ h – corresponds to displays with a  resolution of resolution from 180 to 270 dpi.
„„ x – corresponds to displays with a  resolution of resolution more than 270 dpi.
Each image can have any name (or no name at all), but the last (or only) character
in the name must be one from the list above. The ratio of picture sizes in the
archive can be represented as follows: m=1.5*l, h=2*l, x=3*l. Thus, if the size
2-926 1C:Enterprise 8.3. Developer Guide

of a picture for a toolbar is 16 dots, the set of pictures shall contain pictures
of the following sizes: l=16, m=24, h=32, x=48 dots.
The archive must always include the "l" image (basic image). Other images are
optional. If the required image is  missing, the system uses the image that resembles
it  the closest in  terms of size. You can place the image archive:
„„ In the image library
„„ In Image type configuration object attributes
„„ In the Picture, ValueStorage, BinaryData object created in the
1C:Enterprise script
We recommend you use PNG-format images when you create the archive. If you
place compressed images (PNG, JPG, etc.) in the archive, we recommend you
do not compress the archive. In all other instances, we recommend you create
a  compressed archive.
The basic image is  used in  the following cases:
„„ In an applied solution operating under 1C:Enterprise for PC
„„ In image export to other data formats
„„ In data transfer from server to client
Devices running iOS use the following images from the set:
„„ Regular displays – "m" picture
„„ Retina displays – "x" picture
Devices running on Android use images corresponding to the display resolution of
the device used.

25.4. INTERACTION WITH A  MOBILE DEVICE DURING MOBILE

APPLICATION DEVELOPMENT
You can transfer a mobile application to a mobile device using one of two
methods:
„„ Via the Apple App Store application marketplace (http://itunes.apple.com/ru/genre/ios)
or Google Play (http://play.google.com). This  method is  used to distribute public
versions of mobile applications. For information on how to prepare a  mobile
solution for publishing, see page 2-935.
A publishing-ready mobile solution is approved and published based on the
rules of the relevant application store. Details of this process are beyond the
scope of this guide.
„„ Via the 1C:Enterprise mobile platform for developers. This  method is  used for
mobile application development and is  outlined below.
To start using a  mobile application, a  number of actions must first be performed:
„„ Install the 1C:Enterprise mobile platform for developers on the mobile device.
Chapter 25. Developing solutions for the mobile platform 2-927

„„ Publish the mobile application on the web server.

„„ Create an infobase (application) based on the published mobile application on
the mobile device.
These operations will create an infrastructure that is  ready for the development and
execution of a  mobile application on the mobile device. The  system can be config-
ured so that a  configuration update triggers an automatic configuration update on
the mobile device by the 1C:Enterprise mobile platform for developers.
Further details on each of these actions can be found below.

25.4.1. Installation of the 1C:Enterprise Mobile Platform

for Developers
25.4.1.1. For iOS
To develop a  mobile application for iOS, the following requirements are to be met:
„„ You can work with the mobile device via an Apple computer only (referred to
as "Mac" below) running MacOS X 10.8 or later.
„„ Your Mac computer should have a  free USB port for communication with the
mobile device.
„„ You should install XCode development tool, version 4.5 or later, on your
computer (https://developer.apple.com/xcode/).
„„ You should register in iOS Developer Program (https://developer.apple.com/
programs/ios/).
„„ You need to work with a  mobile device running iOS and corresponding to the
system requirements.
To install the 1C:Enterprise mobile platform for developers on the mobile device
running iOS, do the following:
„„ Connect the mobile device to your Mac computer.
„„ Unzip the mobile platform project file prjios.zip on your Mac computer.
„„ Open the project in  XCode (double-click 1cem.xcodeproj file or select 1cem.
xcodeproj file using the File – Open menu item in  XCode).
„„ Open the Organizer tool using the Window – Organizer menu item in  Xcode.
„„ In the window that opens, select the connected phone (with a  green dot icon
next to it) in  the left-hand panel.
„„ Select the Add to Portal command in  the bottom panel.
„„ The Organizer will request certificates and a  provisioning profile for the phone
from the Apple web-site and will automatically install these on the phone. You
will need to enter the developer password issued when you registered in  iOS
Developer Program.
2-928 1C:Enterprise 8.3. Developer Guide

„„ Use the Product – Edit Scheme menu item in  XCode to open the options dialog
for the current run scheme. In  the dialog that opens:
○○ Select the 1cem value in  the Scheme property.
○○ Select the connected phone in  the Destination property.
○○ Select the Release value in  the Build configuration property.
○○ Click OK.
„„ Run the project using the Product – Run menu item in  XCode.
„„ The mobile platform is  then sent to the mobile device and launched, and its
icon is  included in  the list of applications installed on the mobile device.
„„ The mobile device can now be disconnected from your Mac computer, and the
mobile platform can be launched by pressing the 1C:Enterprise icon in the
application list. If the 1C:Enterprise mobile platform for developers launched
from XCode is  running on the mobile device when you disconnect it, it  is  shut
down.

25.4.1.2. For Android

To develop a  mobile application for Android, the following requirements are to be
met:
„„ Install Android SDK (http://developer.android.com/sdk/index.html) on your computer.
The  minimum requirements for Android SDK are:
○○ Android SDK Tools version – 20.0.3 or later.
○○ Android SDK Platform-tools version – 14 or later.
○○ SDK Platform version – API 17.
„„ Your computer should have a free USB port for communicating with the
mobile device.
„„ You need to work with a  mobile device running Android and corresponding to
the system requirements.
To install 1C:Enterprise mobile platform for developers on the mobile device
running Android, do the following:
„„ Select the following checkboxes in  the mobile device settings:
○○ Unknown sources.
○○ USB debugging.
„„ Download and install the USB driver for the mobile device from the manufac-
turer's web-site.
„„ Connect the mobile device to your compute.
„„ Use the Windows OS command-line interpreter to execute the following
command:
%ANDROID_SDK%\platform-tools\adb.exe install -r "<Platform directory>\1cem.apk"
Chapter 25. Developing solutions for the mobile platform 2-929

Where Platform directory is  the directory where 1cem.apk file is  located.
„„ The mobile platform is  then sent to the mobile device, and its icon is  included
in  the list of installed applications.
„„ Now the mobile device can be disconnected from your computer, and the
mobile platform can be launched by pressing the 1C:Enterprise icon in the
application list.

25.4.2. Publishing a  Mobile Application on the Web Server

To make a  mobile application available on the mobile platform, you must publish
the mobile application on the web server. The  publishing process consists of two
steps:
„„ Preparing the infrastructure for operation and the initial dump of the mobile
application configuration (one-time operation).
„„ Updating the mobile application configuration in  the prepared infrastructure.
Use the Configuration  – Mobile application  – Publish command to prepare your
infrastructure. In  the dialog that opens, select the Create virtual directory on web
server checkbox. If the checkbox is  not selected, Name and Directory attributes are
not available, and clicking the Publish button does not create a  virtual directory on
the web server.
CAUTION!
Publishing requires administrator privileges.

Fig. 328.  Mobile application publishing

Then specify properties for the web server virtual directory:

„„ Name – defines the virtual directory name (this is  included in  the mobile appli-
cation configuration URL to be specified on the mobile device during infobase
creation).
„„ Web server – defines what web server is  used. If Microsoft Internet Informa-
tion Services is  used as a  web server, you can select the Use operating system
authentication on web server checkbox.
2-930 1C:Enterprise 8.3. Developer Guide

„„ Directory – specifies a physical directory on your drive that will store the
mobile application configuration file in  .xml format and will be mapped to the
virtual directory on the web server.
The Update mobile application when a  database configuration is  updated checkbox
manages the automatic update of the mobile application configuration when the
database configuration is  updated. If the checkbox is  selected, the configuration
is updated.
You can also enforce the configuration update by selecting Configuration  –
Mobile application  – Update published application. If the mobile application was
not published before you chose this command, it opens the publication dialog
described above.
CAUTION!
It is  the database configuration, rather than the configuration being edited, that
is  published on the web server.
To launch the publishing process itself, click the Publish button. The process
includes the following actions:
„„ If the Create virtual directory on web server checkbox is  selected, the virtual
directory is  created on the web server;
„„ A directory mapped to the virtual directory is  created on the drive;
„„ You are prompted to dump the mobile application configuration into the direc-
tory (specified in  the Directory attribute of the publishing dialog);
„„ checked check of whether the database configuration matches the configuration
being edited is  performed;
„„ If the infobase configuration does not match the configuration being edited, you
are prompted to update the database configuration. You can skip this operation
if you want to publish the database configuration;
„„ A mobile application checkup is  performed (see page 2-1025);
„„ If no errors are found, the infobase configuration is  dumped into the file; other-
wise, dump is  not performed.
The mobile application configuration file dumped using the Publish command has
a  fixed name, 1cema.xml. This  is  the file that you search for (and update) when
you choose the Update published application command.
TIP
When you create a  virtual directory, the configuration file (1cema.xml) is  set as
its default page. This  allows you to specify a  short URL in  the infobase creation
dialog on the mobile device.
The Disconnect button in the mobile application publishing dialog cancels
publishing by removing both the virtual directory from the web server and the
physical directory.
Chapter 25. Developing solutions for the mobile platform 2-931

25.4.3. Starting and Restarting an Application

on the Mobile Platform
A mobile application should be launched directly from the mobile device.
You cannot start the mobile application from Designer.
If the mobile application is started using the 1C:Enterprise mobile platform for
developers and has the Allow restarting from Designer checkbox selected (see page
2-932), you can restart the mobile application from Designer. To do this, select
Debug – Start debugging – Mobile application: run in  the main menu.
If the configuration has been modified (if changes have been made), Designer
displays the following message: Configuration being edited differs from database
configuration. Update database configuration? If you want to save the changes you
made, click Yes.
If you choose No, the mobile application is  started without configuration update.
If you selected the Update mobile application when a  database configuration
is  updated checkbox during mobile application publishing, the mobile application
configuration is  automatically updated.
The mobile application checks for updates when you open it  if the Allow restarting
from Designer checkbox is selected in the mobile application properties on the
mobile device. If this checkbox is  deselected, updates are not checked when the
application is  opened. However, you can run this check manually (see page 2-932).

25.4.4. Managing Applications on the 1C:Enterprise

Mobile Platform for Developers
25.4.4.1. Create Application
When you want to create an application on the 1C:Enterprise mobile platform for
developers, perform the following steps:
„„ Launch 1C:Enterprise on your mobile device.
„„ Choose the Add Application command.
„„ In the window that opens, enter the URL of the web server where the mobile
application is  published (see page 2-929) in  the Address field.
„„ If required, specify the user name and password used for authorization on the
web server where the mobile application is  published and click the Download
button.
„„ Next, specify the application name and click Done.
„„ The window is  closed, and the application is  created.
The application list is  skipped and the application is  launched immediately if this
is  the only application in  the list. In  this case you can navigate to the application
list by selecting the All applications command in  the main menu of the application.
2-932 1C:Enterprise 8.3. Developer Guide

25.4.4.2. Modifying application properties

You can modify application properties in a special window. Access to this
command depends on the operating system:
„„ In iOS click the greater-than icon in  the right-hand part of the row containing
the relevant application name.
„„ In Android use the long press on the relevant application. Choose Edit in  the
context menu that opens.
In the window that opens, you can modify the application properties specified when
the application was created: name of the application, configuration location URL,
user name and password for access to the web server where the mobile application
configuration is  stored.
You can also do the following in  this window:
„„ Launch the mobile application. To do this, click the Open button.
„„ Check for a  new version of mobile application configuration on the web server.
To do this, click the Check for updates button. If a  new configuration version
is  found, you are prompted to update the mobile application.
„„ Remove the application by clicking the Delete button.
CAUTION!
Once you remove the application, infobase data cannot be restored.
„„ Set up automatic update and restart of the mobile application if a  new configu-
ration version is  found on the web server (see page 2-931). To do this, change
the status of the Allow restarting from Designer checkbox.
The application list is  skipped and the application is  launched immediately if this
is  the only application in  the list. In  this case you can navigate to the application
list by selecting the All applications command in  the main menu of the application.

25.4.4.3. Deleting an application

If you want to delete an application, choose the deletion command and confirm the
action. Access to this command depends on the operating system:
„„ In iOS choose the Edit button and then click the icon in  the left-hand part of the
row with the name of the application you want to delete. Then click the Delete
button in  the right-hand part of the same row.
„„ In Android use the long press on the application to be deleted. Choose Remove
in  the context menu than opens.
The application list is  skipped and the application is  launched immediately if this
is  the only application in  the list. In  this case you can navigate to the application
list by selecting the All applications command in  the main menu of the application.
Chapter 25. Developing solutions for the mobile platform 2-933

CAUTION!
Once you delete the application, infobase data cannot be restored.

25.4.5. Mobile Application Checkup Before Publishing

in  an Application Store
A mobile application to be published in  an application store contains the mobile
platform, mobile application and auxiliary files (icons, logos, etc.,) all of which are
placed into a  single container. This  file can be installed on a  mobile device.
The file generation process differs according to the operating system:
„„ In an iOS application, file generation is  a two-step process:
○○ Generating a  project archive for XCode;
○○ Assembling the created project using XCode.
„„ In Android it  is  sufficient to generate an archive with application components
using a  special procedure.
The archive is  generated using a  special data processor named the Mobile applica-
tion creation wizard.

Fig. 329.  Mobile application creation wizard

Assembly requires the following software to be installed on the computer on which

you intend to run the data processor:
„„ Java SDK supplied by Oracle. For the data processor to operate correctly, Java
SDK version 6.25 or later is  required. You can download it  from the Oracle
web-site: http://www.oracle.com/technetwork/java/javase/downloads/index.html.
2-934 1C:Enterprise 8.3. Developer Guide

„„ Android SDK supplied by Google. You can download this kit from the Google
website: http://developer.android.com/sdk/index.html.
Working with the data processor includes the following steps:
1. Set up the application (use the Settings button to open the relevant dialog).
Specify installation directories for the corresponding SDKs, location for mobile
platform files (prjandroid.zip and prjios.zip) and location for files created upon
completion of the application creation process. If you intend to create applica-
tions for an Android platform, create a  certificate file to sign the application.
You can do this in  the setting form.
If the applied solution uses location tools and is  installed on Android, obtain
the SHA-1 hash value for the certificate file. This  value is  used to obtain the
key required for using Google Maps. To obtain the hash value, click the Get
SHA1 hash button on the Key parameters for Android tab of the settings form.
2. After you configure the settings, specify the operating systems for which the
applications are assembled.
3. Then select the configuration of the mobile application to be added to the
archive. Use the Mobile application configuration field.
4. The system auto-fills the Application name.
5. The Application name field contains the text to be displayed as a  label for the
application icon on the mobile device display. The  field itself displays the text
in  the localization language of the current 1C:Enteprise session. You can edit
this presentation by clicking the magnifying glass button in  the right-hand part
of the field. If multiple languages have been created in  the selected configura-
tion, the application presentation can be edited in  all configuration languages.
6. The Default language field specifies the language used for the presentation if the
localization language of the mobile device is  missing from the list of mobile
application localization languages.
7. The Application ID field is  a unique mobile application ID that expressly iden-
tifies the application among other applications in the application store. We
recommend setting the application ID using the following template: com.e1c.
ApplicationName. ApplicationName is  the name (not the presentation!) of
the mobile application in  the English language.
The data processor generates the application ID using the Name configuration
property. If this property is set in the Russian language, the application ID
should be specified manually (in the English language).
The data processor does not support application ID input in  any language other
than English.
8. If you intend to use location tools in  Android OS, you should get the key for
working with Google Maps. To do this, copy the SHA1 hash for getting the key
for accessing Google Maps field value and use it  in  your developer account
Chapter 25. Developing solutions for the mobile platform 2-935

to obtain the key for Google Maps. Enter the key into the Key for accessing
Google Maps field. This  operation needs to be repeated after every change to
the developer's certificate file.
If you do not intend to use location tools in  Android OS, you do not need to
enter (and obtain) the key.
9. You can use the Set icons and logos command to specify image files to be
displayed on the mobile device.
CAUTION!
During application development, you are only allowed to change application
resources (icons and logos) if they are specified in  the Set icons and logos form.
Changing other mobile application resources is  not allowed.
10. After you set all the parameters, click the Create button. If the creation process
is successfully completed, files <ApplicationID>.zip (for iOS) and <Applica-
tionID>.apk (for Android) are created in the folders that were indicated as
application locations. <ApplicationID> is  the text from the Application ID field,
e.g. com.e1c.test.apk.
11. The APK-file is  ready for immediate installation on the mobile device, while
the ZIP-file can be installed on the mobile device using XCode running on
a  Mac computer. For a  description of the installation process, see page 2-927;
however, remember to use the <ApplicationID>.zip file instead of the prjios.zip
archive.

25.5. PREPARING THE MOBILE APPLICATION FOR PUBLISHING

IN  AN APPLICATION STORE
Preparing an application for publishing in an application store is similar to the
mobile application checkup prior to publishing.

25.5.1. For iOS

After you generate an application archive for iOS, copy the file to your Mac
computer and do the following:
„„ Unzip the mobile platform project file <ApplicationID>.zip on your Mac
computer.
„„ Open the project in  XCode (double-click 1cem.xcodeproj file or select 1cem.
xcodeproj file using File – Open menu item in  XCode).
„„ Use the Product – Edit Scheme menu item in  XCode to open the options dialog
for the current start scheme. In  the dialog that opens:
○○ Select 1cem value in  the Scheme property.
○○ Select the Release value in  the Build configuration property.
○○ Click OK.
2-936 1C:Enterprise 8.3. Developer Guide

„„ Create an application archive using the Product – Archive command in  XCode.
„„ Open the Organizer tool using the Window – Organizer menu item in  XCode.
„„ Go to Archives in  the upper panel.
„„ Select the created archive and click Distribute.
„„ Follow the instructions provided by the wizard.

25.5.2. For Android

After the .apk file is generated, upload it to Google Play using the console for
developers.
Chapter  26

DEVELOPMENT TOOLS

26.1. FORM EDITOR

26.1.1. Background Information
Form editor can be used to perform all actions related to form creation and modifi-
cation. It  is  a group of several interrelated editors:
„„ attribute editor – Attributes tab
„„ command editor – Commands tab
„„ item editor – Elements tab
„„ parameter editor – Parameters tab
„„ module editor – Module tab
„„ command interface editor – Command interface tab
The bottom part of the window contains the form preview.
Editors support multiple selection. In  this case the properties palette displays prop-
erties common to all the selected objects. Changes made in  the properties palette
are applied to all the selected objects (see fig. 330).
Form elements are usually added by dragging form attributes to the item panel.
Form element is  assigned attribute name as its name and attribute path as its data.
The  system automatically defines both the form element to display the attribute
and the item type (if possible). Form element name is  automatically set equal to the
attribute name; however, it  is  done for developer convenience only.
Similarly, commands (both form commands and global commands) are added to
forms. If form attribute or command has been placed in a form, a special grey
marker is  displayed to the right of its name.
When a form element is selected in the Elements tab, it is automatically posi-
tioned in the preview window. If an element is selected in the preview window,
it  is  automatically positioned in  the element tree in  the Elements tab (see fig. 331).
2-938 1C:Enterprise 8.3. Developer Guide

Fig. 330.  Form Editor

Fig. 331.  Editors relation

Chapter 26. Development Tools 2-939

Thus, you can select form elements in the element editor and in the preview
window. Functionality in  the preview window is  nearly similar to the functionality
in  the element list. In  particular, element context menus, the properties window,
element dragging, etc. are available. When an element is  selected in  the preview
window, a  frame is  shown around the element that can have different colors based
on the element:
Frame color Description
Blue Selection of a  normal element.
Orange Selection of automatically created buttons and command bar submenus. It  is  used to
indicate that the configuration (properties, position) is  not available for this element.
Grey Selection of a  parent element if the selected element can't be selected in  the preview
window. For example, if you select the text box context menu in  the element list, the text
box will be highlighted in  grey in  the preview window.
Green Used when elements are dragged, the control to which the selected element is  dragged
(e.g., a  table or a  form group) and the indicator of the position where the dragged
element will be placed are shown.

If you need to select a  parent element (e.g., a  group containing a  field) for any
other element, you can left-click the subordinate element twice sequentially.
This  selection is  possible if the interval between the two clicks is  1 to 2 seconds.
If the interval is  less than 1 to 2 seconds, the system can interpret it  as a  double
click; if the interval is  greater than 1 to 2 seconds, the system can interpret it  as
separate actions. If on the first click several elements are selected, the parent
element will not be selected.

Fig. 332.  Drag-and-drop indication

The Go To command is  used to quickly move to linked objects. This  command
is  located in  the object context menu in  element editors, command interface frag-
ments, attributes, commands and the preview window. This  command can be used,
for example, to quickly move from a  form element (selected in  the element list or
preview window) to a  form attribute displayed by this element. If you can go to
several elements, a  window with a  prompt to select the object you need will be
opened.
2-940 1C:Enterprise 8.3. Developer Guide

Also, in  the form editor, you can quickly create (or go to) event handlers of certain
form elements using the Events submenu of the element context menu.
This menu includes all events available for this form element in the properties
window of this element. If an event name is specified in angle brackets in the
menu, the event handler can't be determined (for example, for the Clearing event
of the Organization element in the fig. 333. You should select the event you
need to create the handler – the form module editor will be opened and the handler
will be created.

Fig. 333.  Events menu

If the event handler has already been created and you click the corresponding
command in  the Events submenu, you will be moved to the existing handler in  the
form editor (for example, OrganizationOnChange() handler in  the fig. 333.
The Events submenu is  not generated for a  button, and the GoTo command for
a corresponding command handler is located directly in the element context
menu.
Chapter 26. Development Tools 2-941

If you create a  client handler, the system has multiple creation options available:

Fig. 334.  Creation of client handler

If you select the first option (Create on client), a client event handler only
is created. In the Create on client and a  procedure on server (no context)
option, a client event handler is created along with a server-side procedure
with no context, and the procedure is  called from the client handler. In  the last
option a  server-side context procedure is  created. If context server calls are not
recommended for a certain client event handler (you can find this information
in  the Syntax Assistant), the last option (with the server-side context procedure)
is unavailable. Deleting an event handler does not remove the server procedure
(if the latter is  created during event handler creation).
When an attribute is  deleted (from a  form attribute list), the Do you want to delete
the related items? message is  displayed. If the answer is  negative, the Data prop-
erty is  cleared for linked form elements. If the answer is  positive, form elements
linked to the deleted attribute are deleted. If the link with this attribute is  not the
main link for the element (footer data, data displayed in  the group title, etc.), this
element is  not deleted, but the link with the deleted attribute is  cleared. Regardless
of the answer for the deletion prompt, form command interface commands linked
to the deleted attribute will be deleted.
When a form command is deleted, the user is prompted to delete all linked
elements. If the answer is negative, form elements are not deleted, but the
Command element property is  cleared. If the answer is  positive, buttons linked to
the deleted command are deleted.
When you develop a  form that you wish to display in  both the Taxi and Version
8.2 interfaces, you need to see how the form is  displayed in  both interface modes.
You can do this in  the form editor.
See fig. 335 for an example of how the display changes when you switch from the
Taxi interface (upper left-hand view) to the Version 8.2 interface (lower right-hand
view). Please remember that some items are displayed in  the Version 8.2 interface
when you test the form in  the Taxi interface.
The Interface mode button is only available if the Interface compatibility mode
property is  set to Taxi. Version 8.2 allowed or Version 8.2. Taxi allowed. Otherwise,
this button is  not displayed in  the form editor.
To open and check a  form, press Ctrl + R. The  form opens in  a new window.
2-942 1C:Enterprise 8.3. Developer Guide

Fig. 335.  Switching interface mode

26.1.2. Role-Based Form Setup

Form editor supports role-based form behavior setup.
This feature is  available for the following properties:
„„ View – form attribute property. If an attribute cannot be viewed, it is not
included in  form data (it is  not transferred from the server). The  user cannot
modify this setting.
„„ Edit – form attribute property. If an attribute cannot be edited, its associated
form element is  read-only. Regardless of how this property is  set, the attribute
cannot be edited if it  cannot be viewed. The  user cannot modify this setting.
„„ User visibility – form element property. It  defines default visibility of a  form
element. The  user can modify this property in  the form settings editor.
„„ Use – form command property. If the Use property is  disabled for a  command,
all of its associated buttons are not included in the command interface.
The  user cannot modify this setting.
Chapter 26. Development Tools 2-943

Editors for all the above properties are identical both in  appearance and in  opera-
tion. Review how editors work using the View property as an example.

Fig. 336.  Editing Form Attribute "View" Property

The View property (in the upper part of the editor window) defines visibility
for each role with the check box in  the third position (shaded check box). Then
visibility status for all the available roles are added up using the OR concatenation
and the result determines the final View property value for the edited object.

26.2. TEXT EDITOR

1C:Enterprise text editor gives users all basic functions needed to edit texts.
Operations with text blocks, search and replacement functions and color syntax
highlighting are standard features of the text editor.
The text editor in the 1C:Enterprise system uses two modes: editing text docu-
ments and editing modules (part of the form editor).
This chapter describes the text editor features used while editing modules.
Since all text editor interfaces in Microsoft Windows are similar, in this
chapter we describe only those features of the text editor that are specific to the
1C:Enterprise platform.
NOTE
Characters that are incompatible with XML specification version 1.0 are
not allowed in the text editor. If the user attempts to enter such a character,
it  is  ignored; if pasting from clipboard is  used, invalid characters are skipped
and are not inserted in  the pasted text.
For help with text editor hot key combinations use the Help menu.

26.2.1. Editing Modules

Modules are edited when a  configuration object form is  created or modules are
developed (application module, external connection module, general modules or
application object modules).
When a  form is  created, the text editor appears as part of the form editor. To open
it, click on the Module tab in  the form editor window. In  all the other cases the text
editor opens in  a new window. If you need to open a  managed application module,
2-944 1C:Enterprise 8.3. Developer Guide

external connection module, session module or ordinary application module, right-

click the configuration name (uppermost configuration tree branch) and select the
appropriate item in  the context menu.
To edit object module select the object and choose Open Object Module in the
context menu.
To edit manager module (if available for an object) select the object and choose
Open manager module in  the context menu.
To edit a  command module double-click the command or select Open command
module in  the command context menu.
To edit common module in  the Configuration window on the Common – Common
modules branch select the required module and choose Open Module in  the context
menu.
Program module text editing process is similar to the text document editing
process. You can use all text editor features.
This section contains the description of all specific text editor features that are
available for module editing.

26.2.1.1. Color Syntax Highlighting

To make module editing more convenient 1C:Enterprise text editor can highlight
the 1C:Enterprise script items with different colors (keywords, constants (other than
configuration objects), different types, operators, remarks, etc.). You can set the
colors for different syntactic constructs in  the Options window by going to Tools –
Options (for information about setting up text editor parameters see page 2-1150).
Built-in function names are not highlighted (the color is  the same as for IDs).
In general this feature is  activated automatically any time you launch text editor to
edit module text. But sometimes module text is  located in  external text file. When
opening this kind of file, the Designer does not recognize the module and treats
it as an ordinary text document. In this case syntax highlighting and automatic
module text formatting is not available while editing the text. The  Text  –Script
menu item which functions as a  toggle shows the Designer that a  module is  being
edited rather than a  text document.
When this menu item is  turned on (a checkmark appears to the left of the Script
menu item), the text editor treats the loaded text as module text and highlights
syntax in  color.

Fig. 337.  Syntax Highlighting On

Chapter 26. Development Tools 2-945

When this mode is  on, a  regular text document is  displayed with the font set as
default for module text in  the Designer parameter settings (Tools – Options menu
item, Texts tab, Font attribute).
The parameter settings in  the 1C:Enterprise system allow the syntax color high-
lighting to be turned off; in  this case selecting the Script item does not enable the
color highlighting for module syntactic constructs, but uses the module print and
tab spacing settings only.
If the syntax color highlighting mode is  switched off, operating system colors are
used for typing out the text.

26.2.1.2. Group
In modules or text documents viewed in  the Script mode some syntactic constructs
are automatically grouped. These include If … Then … EndIf, While … Do …
EndDo, Procedure … EndProcedure and others.
Text groups improve readability of different text parts and support move and copy
functions for entire groups. See fig. 338 to understand how groups are displayed.

Fig. 338.  Groups in  Text Editor

You can expand or collapse a  group with the mouse. To do this, simply left- click
on the group marker.
If you hold down the Ctrl key while clicking all nested groups (conditions, cycles,
etc.), they also collapse or expand.
To display collapsed text move the cursor over the marker, as shown on fig. 338.
If the text is  too large, only its initial part appears.
2-946 1C:Enterprise 8.3. Developer Guide

You might need to group module fragments in the development process.

For example, if you need to select logically connected procedures or functions or
to select algorithm fragments within a  single procedure or function, you can use
preprocessor directives #Region … #EndRegion.

Fig. 339.  Grouping rows

All rows within a region that is limited by the preprocessor directives can be
collapsed in the module editor (just like other 1C:Enterprise script syntactic
constructions). Each region must have a  name based on the 1C:Enterprise script
rules. In the example shown on fig. 340, the region is named PictureFile.
Regions can be nested, but they cannot overlap with other syntactic constructions
of the 1C:Enterprise script. A number of examples, both correct and incorrect, for
using regions can be found below:
// Correct example of using a  region
#Region Correct
…
#If Client Then
…
#EndIf
…
#EndRegion

// Nested regions
#Region CalculationAlgorithm
…
#Region Stage1
…
#EndRegion
…
#Region Stage2
…
#EndRegion
…
Chapter 26. Development Tools 2-947

#EndRegion

// Incorrect example of using a  region

#Region Incorrect
…
#If Client Then
…
#EndRegion
…
#EndIf

// Incorrect example of using a  region

#Region Incorrect
Procedure GetData()
…
#EndRegion
…
EndProcedure

A region can be described using a  comment inserted before the region (#Region).
The  comment can also be grouped.
Groups can be easily manipulated using keyboard shortcuts.
Keyboard shortcut Actions
Ctrl + Num - Collapses the group (cursor can be anywhere in  the group)
Ctrl + Num + Expands the group (cursor has to be over the first line of the group)
Ctrl + Shift + Num - Collapses all the groups
Ctrl + Shift + Num + Expands all the groups
Ctrl + Shift + R Refreshes the groups

During write operations groups are automatically created for all syntactic constructs
of any nesting level by completing the writing of the syntax statement. Groups can
be updated using the Text  – Groupings  – Refresh Groups item or automatically
when saving text according to the group display settings.
Description of procedures, functions, and regions is  considered the first level and
the second level is syntactic constructs that are nested in procedure or function
body, but not in  the body of other syntax statements. Group display mode can be
set up. For information about mode setup see page 2-1153.

26.2.1.3. Module Formatting

1C:Enterprise text editor includes a  number of modes making module development
easier.
Syntax Formatting
Using syntax indention – marking the 1C:Enterprise script control directives with
leading spaces (tabulations), as shown below in  a module fragment, is  considered
good practice for code writing.
2-948 1C:Enterprise 8.3. Developer Guide

Procedure NextItem(Catalog, Selection)

While True Do

If Selection.Next() = False Then

Selection = Catalog.Select();
Continue;
Else

Abort;
EndIf;

If Selection.IsFolder Then

Continue;
EndIf;
Return;
EndDo;
EndProcedure

In this fragment module strings placed inside structure operators If … Then …

EndIf and While … Do … EndDo are shifted to the right in  order to accentuate
their nesting. Module text formatted using syntax indention is  easier to read and
debug.
1C:Enterprise text editor provides automatic formatting functions for 1C:Enterprise
script control directives. For setting up automatic formatting in  the system settings
mode (in Designer, Tools menu, Options section, Modules tab), one of two inden-
tion options can be chosen.
Syntax indent makes module text formatting automatic, shifting the text located
inside control directives If … Then … EndIf and While … Do … EndDo (and
the like) to the right. Shifting is  performed by adding the necessary number of tab
symbols at the beginning of lines.
The standard indent automatically aligns the line text to the left of the previous line.
If automatic indent is  disabled, no other extra characters are added to the text.
Besides automatic formatting of module text during entry process, text that has
already been entered can also be formatted. To do this, select a  text block to be
formatted and choose the Text  – Block  – Format menu item. The text editor
analyzes the module text and formats it  so that each syntactic construct is  shifted
to the right based on the tab size regardless of the original line placement (leading
spaces). The empty lines are filled with tab symbols in accordance with the
syntactic construct.
It is  possible to move text blocks using left or right tabbing. To do this, highlight
a  text block and choose the Text – Block – Increase Indent (Text – Block – Decrease
Indent) command.
Chapter 26. Development Tools 2-949

1C:Enterprise text editor automatically deletes spaces at the ends of the lines.
This  is  performed while recording a  module.

Insertion/Deletion of Comment Marker

When debugging modules it is often required to temporarily "switch off" some
module lines to prevent them from executing during a  system run. This  is  usually
done by changing these lines into comments – by inserting the // comment marker
before them. To later "switch on" the lines converted into comments, delete the
comment marker.
For switching large module fragments off (and on), it is convenient to use the
Auto add comment markers mode for all selected block lines or for the current line
(selecting the line is  not necessary).
In this case a  block of text needs to be selected or the pointer needs to be placed
over the desired line and the Text – Block – Add Comment (Text – Block – Delete
Comment) item chosen.
When more than one comment marker is  placed before the line, only one is  deleted
when deleting the comment.

Insertion/Deletion of Line Wrapping

When writing string constants, the | symbol is  used to wrap the line.
You can easily add or delete this symbol to/from highlighted lines using the text
editor.
To insert/delete the line wrap symbol in all lines within the selected block or
in  the current line (no need to select a  single line), specify the area and select the
Text – Block – Insert Line Break (to insert the symbol) or Text – Block – Delete Line
Break (to delete it).
The line wrap symbol is  inserted in  the left most important position (other than
space or tab character) of each line.

26.2.1.4. Navigation of Module Procedures and Functions

With a large number of procedure and function descriptions contained in the
module, it is convenient to use the procedure search mode supplied by the
1C:Enterprise text editor.
Text  – Procedures and Functions command displays a  window with a  list of all
procedures and functions in  the module being edited (see fig. 340).
Procedure and function names are displayed on the list in  the order of their place-
ment in  the module. If the Sort option is  on, the list is  sorted alphabetically.
Procedure and function names already placed in  the form have an icon to their left.
2-950 1C:Enterprise 8.3. Developer Guide

Fig. 340.  List of Procedures and Functions

To navigate to a  needed procedure or function, select its name on the list and press
the Go To button.
Names of events with no handler procedures are shown in  angle brackets in  the
procedures and functions list. Created procedures and functions are marked with
P() and F(х), respectively, displayed in front of their names. Events that can be
handled are defined by the object and form type as well as the controls located
in  the form. When this kind of line is  selected, predefined procedure text is  added
to the module and a  reference to the procedure is  added to the appropriate event
in the Events category.
IMPORTANT!
Event handler procedures (defined by the system for a  module) should be cre-
ated within the form properties palette, the Events category, by using either the
Procedures and functions window or the Procedures and functions list box. If you
simply try to copy the event handler procedures from different modules, the event
handlers from other modules will not be initiated in the form and the copied
procedures will not be called up to process the events.
When moving the cursor to the module line, the name of the current procedure or
function is  shown in  the procedure selection field of the Module toolbar (Proce-
dures and functions command). Using this list, you can switch to the needed
procedure or function.
To navigate to a  procedure, function or variable, click the appropriate name with
the mouse and press F12. Switching is  possible only for procedures, functions and
variables placed in  this module or procedures to be exported, functions and vari-
ables of application module, common modules and object modules. To return to the
initial point of navigation press Ctrl + - (next to the = key).
If the recorded expression consists of parts defined in  different configuration loca-
tions, prior to switching the list of similar objects appears on the screen in  order
to choose the switch. You can navigate to a  variable definition, metadata object
Chapter 26. Development Tools 2-951

definition with the object type equal to the current expression or procedure or func-
tion definition used in  the expression (for example, in  a module of the object with
the type matching that of the expression).
For example, if F12 is  pressed for the Cat.FindByCode() expression where Cat
is  defined as Currencies catalog, it  displays a  list of navigation to the Cat vari-
able definition and the Catalogs – Currencies metadata object definition in the
configuration object tree.

26.2.1.5. Context Tips During Module Text Entry

The 1C:Enterprise system text editor allows contextual entering of expressions
using system objects, their properties, methods, procedures and functions, object
description defined in  the configuration as well as variables, procedures and func-
tions defined in  common modules, application object modules and form modules.
Predefined items of catalogs, charts of accounts, charts of characteristic types and
charts of calculation types are included in  the list.
Text templates and keywords can also be included in  the context tip list.
NOTE
Context text tips are not supported by the system for text documents with the
Script property enabled.

Text is entered from the list displayed as a context menu at the current cursor
position (relative to the screen edges).
The list is  called by pressing Ctrl  +  Spacebar at any stage of expression entry or
automatically upon entering the . character after an expression that represents an
object with properties or/and methods (if the contextual help is  enabled, see page
2-1154).
The contents of the list depend on the program module execution context (see
section "1C:Enterprise Script Overview") and previously entered text.
At the initial stage, before text has been entered or when only the first expression
characters have been entered, the list structure is  defined by the execution context.
The list is  shown as alphabetically sorted text lines.
If a  text fragment is  entered when the list is  being opened, this list is  positioned
on the first line with a  name that contains as much of the entered or selected text
as possible (starting from the beginning of the name). If the entered text is not
included in  the lines on the list, the line that best represents the entered text is  acti-
vated.
If the typed expression is  a system enumeration, the list can be opened simply by
pressing the = key.
When the list is  opened, it  is  possible to continue entering text. In  this case lines
matching the entered text are activated in  a sequence.
2-952 1C:Enterprise 8.3. Developer Guide

The list can be viewed by the standard method. By pressing the Enter key, the
contents of the chosen line is  transferred to the module, replacing the selected or
entered text.
NOTE
When text is  transferred to the module, method parameters are not inserted and
client application context is  used.
To the left of the lines there are icons showing the object type and location.
Icon Object
Line (black) ■■ Global context properties
■■ System value sets
■■ Enumerations
Line (green) ■■ Universal value collection object properties
■■ Interface object properties
■■ Application object properties
■■ Predefined items
Line (blue) Exported module variables
Line (red) Local module variables
P() (black) Global context procedures
P() (green) Interface and application object procedures
P() (blue) Other exported module procedures
P() (red) Local module procedures
F() (black) Global context functions
F() (green) Interface and application object functions
F() (blue) Other exported module functions
F() (red) Local module functions
Colored lines Keywords (If, Do, Try and others)
Template picture Text template

Text templates are included in  the list only if an auto-replace string is  specified
in it.
If after entering the text or selecting it  from the list the text is  an expression with
properties or methods, then after entering the "." character a  list of properties and
methods available for this expression is  displayed automatically.
For example, if Catalogs. is entered, the list containing names of all catalogs
described in  the current configuration appears. After a  certain catalog is  selected
and the "." character is entered, the list appears again, but unlike the previous
list, it  contains procedures and functions for working with the catalog as well as
predefined catalog items. If the selected method returns a  value of the type with
properties and methods, contextual entry can be continued (it is  essential to enter
the opening and closing brackets at the end of the name). The context tip list
contains the only available set defined by the type of the expression entered.
Context tips can also be used for module variables.
Chapter 26. Development Tools 2-953

Context tips can be used when entering the New operator and for variables created
using the New operator.
Context tips can be used when entering different keywords (like If, For, Do
and others). Keywords form a list opened in the standard way by pressing
Ctrl + Spacebar at any time while typing the word.
Keyword display in  the list can be set up (see page 2-1154).
If the list for any variable or method consists only of one line, then by pressing
Ctrl + Spacebar, the line will be inserted.
Context help can also display a  list of parameters and a  method type. Parameters
are displayed both for global context objects and 1C:Enterprise objects as well as
for applied solution methods that are properly described. Parameters are displayed
after you type "(" or "," characters (for further information on configuring these
characters, see page 2-1154) or after you press Ctrl  +  Shift  +  Spacebar on the
keyboard after entering the "(" character for a  procedure or function call.

Fig. 341.  Context help for parameters

If a  method has multiple syntax options, the first option is  displayed. The  up and
down arrows are displayed above the syntax description. You can use these arrows
to select the options. You can also select an option using the Ctrl + Up Arrow and
Ctrl + Down Arrow keys.

Fig. 342.  Multiple syntax options in  parameter context help

2-954 1C:Enterprise 8.3. Developer Guide

The type of value that can be passed to this parameter is displayed below the
parameter description. If the value can have multiple types, these types are sepa-
rated by a  comma. Each type name is  a hyperlink that you can click on to open
the Syntax Assistant (see page 2-1170) and display the type information. Parameter
context help is  closed when you enter the ")" character or press Esc in  the open
parameter context help window.
If you want context help to display the parameter description and types for applied
solution methods, add a comment based on specific rules prior to the method.
In  general, a  procedure or function description contains the following sections:
„„ Description section – contains a  brief description of the procedure or function’s
purpose and/or operation. In  case of a  function with no parameters, it  can be
the only section.
„„ Parameters section – describes the procedure or function parameters. If no
parameters exist, this section is  skipped.
„„ Returns section – describes the type and content of the returned value of the
function. This  section is  not used for procedures.
„„ Sample section – contains an example of using the procedure or function.
Comments use the following common format:
<Comment> =
[<HeaderSection>]
[<ParameterSection>]
[<ReturnedValueSection>]
[<SampleSection>]

<NewRow> = Beginning of module row

<Name> = 1C:Enterprise script ID
<Type> = <Name> | <Name>"."<Name>
<TypeList> = <Type>{","<Type>}
<StringOfText> = A text line (without line breaks)
<Text> = <StringOfText> {<NewRow> <StringOfText>}

<HeaderSection> = [<Text>]

<ParameterSection> = <NewRow> ("Parameters:") {<ParameterDescription> {<TypeLongDescription>} }

<ParameterDescription> = <NewRow> <Name> ["-" <TypeList>] "-" [<Text>]
<TypeLongDescription> = <NewRow> "-" <TypeList>] "-" [<Text>]

<ReturnedValueSection> = <NewRow> ("Returns:") <ValueDescription>

<ValueDescription> = <NewRow> [<TypeList> "-"] [<Text>]

<SampleSection> = <NewRow> ("Sample:") <NewRow> <Text>

A comment preceding a procedure or function and using the described format

results in  the correct display of a  tip for an applied solution method in  the context
help for method parameters.
Chapter 26. Development Tools 2-955

Fig. 343.  Context tip for the parameters of applied solution methods

Thus, the context tip mechanism in  the 1C:Enterprise system text editor is  a rapid
and proper way to enter module texts.

26.2.1.6. Module Syntax Check

A module being edited can be checked for correct use of the 1C:Enterprise script
syntax.
To check syntax in  the module use the Text – Check Syntax item.
Syntax is  checked in  the following order:
„„ common modules
„„ managed application module
„„ object module
„„ form module
Module control is performed if the module has not been validated or has been
modified.
When module control is being processed, only modules placed in the list
before the current module are checked. For example, when checking the applica-
tion module, only common modules are checked. External connection module
is  checked only when it  is  being edited.
When errors occur, a  list of errors is  opened in  the message window along with
a  complete location address and error description. The  cursor, when pointing to
the line containing the error message, takes the magnifying glass form. To go to
the module line that caused the error, double-click on the message. If the module
containing the error is  closed, it  opens automatically.
If no errors have been found, the message window displays a  message indicating
there are no errors in  the module.
2-956 1C:Enterprise 8.3. Developer Guide

In the Designer parameter setup mode (Tools – Options item, Modules tab, Check
tab, Check automatically check box) the automatic module check mode can be
enabled. If the module has been changed, module syntax check is  performed when
closing the module window or saving the configuration.
The automatic check mode should be used when debugging any configuration item.
For complete check syntax of all configuration modules in a single operation,
select Configuration – Check Syntax in  Modules.
Tips on the 1C:Enterprise script are available in the module error correction
process. To access the tips open the Syntax Assistant and find description of the
applicable script item (see page 2-1170).
Tooltip on a particular 1C:Enterprise script item (operator, procedure, function,
property or method) can be accessed by placing the cursor in  the module on the
appropriate item and pressing Ctrl + F1. Description for the selected 1C:Enterprise
script item is  opened in  the Syntax Assistant.

26.2.1.7. Configuration Module Access Restrictions

Passwords can be set up for some modules. The  main purpose of the password
is  copyright protection for the configuration developers.
The following restrictions apply to passwords:
„„ managed application module is  not protected;
„„ form modules are not protected;
„„ command modules are not protected;
„„ modules containing preprocessor directives are not protected;
„„ common client modules operating in  the managed mode (thin client, web client
and thick client in  the managed mode) are not protected.

Setting Access Password

To set up a  password open the applicable module and choose the Text – Set Pass-
word command. The  item is  available if the module is  open for writing.
If the module contains preprocessor instructions, the program displays a  warning:
Protected module must not contain preprocessor directives. Continue? Clicking
No does not set up the password. Clicking Yes makes password setup possible
and implies that directives are to be deleted in  the future. If the directives are not
deleted, the system issues the warning: Compilation error: Module <module name>.
Source module code is  unavailable and compiled image is  missing.
Password dialog appears on the screen.
Chapter 26. Development Tools 2-957

Fig. 344.  Module Password Setup

Enter the password and confirm it. To set up the password click OK; to cancel the
setup click Cancel.

Opening a  Protected Module

If a  module is  password-protected, when attempting to open the module, a  pass-
word entry dialog appears.

Fig. 345.  Opening a  Password-Protected Module

If the password is  correct, the module is  opened. If the password is  incorrect, the
Incorrect password warning appears and the module does not open.

Password Change
To change the password, open the module and choose the Text  – Set Password
command. Password dialog appears on the screen. Enter the old password. If you
entered the password correctly, the new password dialog box appears on the screen
(see page 2-956).
To disable the password, clear the password text boxes and click the OK button
without typing a  password.

26.2.2. Editing Text Templates

If Text document is  selected as the template type in  the template wizard, the text
editor is  opened in  text template input mode.
The text template editing mode is  also available for text documents with the Text
template extension.
2-958 1C:Enterprise 8.3. Developer Guide

26.2.2.1. Text Template Format

The entire template text is  divided into areas. The  areas have to follow each other
and cannot overlap or include each other. Areas in  the template text are identified
as follows:
#Area ХХХХХ
#EndArea

where ХХХХХ is  the area name.

The area end need not be specified. Declaring the beginning of an area means that
the previous area has ended.
For storing area variants in  several languages, a  language code can follow the area
name:

#Area Heading1 RU
#EndArea

#Area Heading1 EN
#EndArea

If a language code is not indicated for any area variant, this area variant
is  returned when language code that is  not indicated in  any of the area description
variants is  transferred to the GetArea() method.
Each area consists of service and textual parts.
#Area ХХХХХ

[service part]
[text part]

#EndArea

26.2.2.2. Service Part of an Area

The service part has no visible borders. It  contains all lines from the area beginning
that start with the special "#" character. Text template fields used inside the area are
described in  this part. If not needed, the service part can be left out.
Text template directives are highlighted in  color.

Area Service Part Structure

The service part of an area consists of some common area parameters and format
descriptions for fields included in the area. All descriptions in the service part
apply only within the area. If field format is  described in  some area and the field
occurs in  another area without a  format description, the default format is  used.
Chapter 26. Development Tools 2-959

A common area #ReplaceChar A B keyword can be located at the beginning of

the service part. This  keyword is  used to replace characters inside the area lines.
„„ A – character to be replaced;
„„ B – character replacing A.
Characters must be enclosed in  single quotes.
For example, if #ReplaceChar "@" "#" is  written, the "@" character not included
in  the field names inside the lines are replaced with "#".
It makes sense to use this keyword in  cases when the format of a  template string
must contain the # character (using it  directly would mark the text as service).
Field Descriptions
Replacement description is  followed by format description for fields used in  the area.
A field is  created using the #Field FFFF keyword, where FFFF is  the field name
for which format is  to be described.
Subsequent lines contain keywords for the field description. The  field description
applies up to the beginning of the next field description.
#Alignment {Left | Right | Center | Justify} – shows field alignment
within its space limits.

#Field WorkType
#Alignment Justify

#Format <Format string> – specifies format string for field output.

#Field Date1
#Format "DF=dd.MM.yy"
#Field Tm1
#Format "ND=4; NFD=0; NDS=."

#Block <Parameter> – shows the necessity of filling the area for the field by "#"
characters. If <Parameter> = True and field contents do not fit in  the allocated
place, the area is  filled.
#Field ReportTotal
#Format "ND=18; NFD=2; NDS=."
#Block True

26.2.2.3. Text Part of an Area

The text part of an area consists essentially of the text template strings. It  begins
after the last string belonging to the service part of the area and continues up to the
end of the area. Field names can be specified inside the lines of the text template
in  the following format: [FFFF].
2-960 1C:Enterprise 8.3. Developer Guide

The number of spaces reserved for the field equals the number of characters
displayed in  the brackets (brackets included). If the field size consists of only one
symbol, a  single bracket can be used.
Example:
-----------------------------------------------------
![Name ]! [Code ]! [Description ] !
-----------------------------------------------------

If the field name immediately follows the left bracket, then that field has a  left
alignment; if it  is  immediately followed by the right bracket, then it  has a  right
alignment. If whitespaces are placed to the left and to the right of the field,
it  is  centered inside the allocated spaces.
If the field name is larger than the assigned number of spaces, the name
is  displayed using the Fields keyword.
Example:
#Field Number
#Format "ND=3; NFD=0"
#Field Code
#Format "ND=5; NFD=0"
#Field Label
#Format "ND=1"
-------------------------------------
![ ]! [ Code]![ Description ] ! [! #Field Number Label
-------------------------------------

Fields keyword parameters are only indicated for fields if their names are not
enclosed in  brackets inside the template body.
Auto Wrap
If the text does not fit in  the allocated field size, it  may be necessary to use auto-
matic text wrapping to a  new line. To do this, it  is  recommended to use a  field
placement instruction in  the template, using braces and angle brackets.
„„ {FFFF} – field area is  limited by braces. They show that the text stored in  the
FFFF field can be auto-wrapped to this line and indicate the area for the text that
does not fit in  the FFFF field. Even if the line does not need to output any of the
fields, it  is  output anyway.
„„ <FFFF> – field area is  limited by angle brackets. They show that the text stored
in the FFFF field can be auto-wrapped and indicate the area for the text that
does not fit in  the previous line of the FFFF field. If all the fields in  the line are
enclosed in  angle brackets, but none of them has been used for text output, the
line is  not output. If the text still does not fit when output from the field to the
line where the field in  angle brackets is  included, the line is  duplicated until
the entire text can be output from the field.
Chapter 26. Development Tools 2-961

Example:
---------------------------------------------
![ YY]! [XX ]![ ZZ]!
! ! {XX }! !
! ! <XX >! !
---------------------------------------------

This example shows that the XX field is  placed on the first line. The  part of field
XX that does not fit on the first line is  placed on the second line. The  part of field
ХХ that did not fit on the first and second lines is  placed on the third line. If field
ХХ has no text left for the third line, that line is  not output at all, but if it  did have
text left, the third line is  output until the text from field XX ends.

26.2.2.4. Text Template Keyword Description

Area
Description:
This indicates the beginning of the template area, but if the previous area has
not ended, it  indicates the end of previous template area.
Syntax:
#Area <Area name> <Language code>
Parameters:
<Area name> Required
Area name used to show the area using GetArea() text document method
is indicated.
<Language code> Optional
The area language code is specified. If the multi-language configuration
is  to be used, then several areas with the same name can be displayed in  the
text template, but each area must contain a  language code. If language code
is  not specified, this area is  selected when an area with a  language code that
is  missing from the area description is  requested.
EndOfArea

Description:
This indicates the apparent end of the template area.
Syntax:
#EndArea
2-962 1C:Enterprise 8.3. Developer Guide

ReplaceChar
Description:
This keyword is  used for character replacement inside the area lines.
Syntax:
#ReplaceChar <Character to be replaced> <Replacing character>
Parameters:
<Character to be replaced> Required
The character to be replaced is  enclosed in  single quotes.
<Replacing character> Required
This indicates the character replacing <Character to be replaced>.

Field
Description:
This indicates the field that needs formatting keywords specified for it.
Syntax:
#Field <Field name>
Parameters:
<Field name> Required
Field name.

Align
Description:
This indicates alignment for field contents output.
Syntax:
#Alignment <Alignment parameter>
Parameters:
<Alignment parameter> Required
Field alignment value. The  following values are available:
„„ Left
„„ Right
„„ Center
„„ Justify
Chapter 26. Development Tools 2-963

Format
Description:
This indicates the field display format.
Syntax:
#Format <Format string>
Parameters:
<Format string> Required
It defines the field value presentation format.
Example:
"DF=dd.MM.yy"

Block
Description:
If the parameter value is  True and the field value does not fit within the allo-
cated space, the entire space is  filled with the "#" character.
Syntax:
#Block <Parameter>
Parameters:
<Parameter> Optional
It defines the necessity of field filling. Available values:
„„ True
„„ False

Fields
Description:
It indicates a  list of fields with names that cannot be indicated in  their allotted
area.
Syntax:
#Fields <Field name 1> <Field name 2> … <Field name N>
Parameters:
<Field name> Required
Field name. All field names that are not indicated in the template text area
should be specified.
2-964 1C:Enterprise 8.3. Developer Guide

26.2.2.5. Invoice Printing Example

It is  assumed that the Document configuration object named Invoice contains the
PrintText template in  the text template list:

#Area Header EN
Invoice N [DocumentNumber ]
From: [From ]
To: [To ]
=================================================
| N| Description | Price |Pieces| Sum |
#Area String EN
#Field Price
#Format "ND=10; NFD=2; NDS=."
#Field Pieces
#Alignment Right
#Format "ND=4; NFD=0; NDS=."
#Field Sum
#Format "ND=12; NFD=2; NDS=."
|--+---------------+----------+----+------------|
|[]|[Description ]|[ Price]|[ ]|[ Sum]|#Field Number Pieces
| |<Description >| | | |
#Area Footer EN
#Field TotalPieces
#Alignment Right
#Format "ND=4; NFD=0; NDS=."
#Field TotalSum
#Alignment Right
#Format "ND=12; NFD=2; NDS=."
=================================================
Total [ ] [TotalSum] #Field TotalPieces

Director: [Director ]

The template contains the following fields:

„„ Header – outputs the report header;
„„ String – output the tabular section;
„„ Footer – outputs totals.
The document form has a  Print button. Clicking it  invokes the Click() event
with the handler procedure placed in  the form module.

Procedure PrintToText(Button)

CurDoc = New TextDocument();

PrintText(CurDoc);
CurDoc.Show();
EndProcedure
Chapter 26. Development Tools 2-965

CurDoc text document is  created during the procedure, and PrintText(CurDoc)
procedure which fills the text document using the invoice data is called.
The procedure is placed in the document module. The document is opened on
the screen after it  is  filled.
PrintText() procedure text:
Procedure PrintText(CurDoc) Export

// Get template
Template = GetTemplate("PrintText");
// Set language code
Template.TemplateLanguageCode = "RU";

// Header
Area = Template.GetArea("Header");
Area.Parameters.DocumentNumber = Number;
Area.Parameters.From = Format(Date,"DF=dd.MM.yyyy");
Area.Parameters.To = Contractor;
CurDoc.Output(Area);

// Process 'Contents' tabular section

StrTotal = New Structure("TotalPieces, TotalSum",0,0);
For Each StrContent From Content Do
Area = Template.GetArea("String");
Area.Parameters.Number = StrContent.StringNumber;
Area.Parameters.Description = StrContent.Nomenclature;
Area.Parameters.Pieces = StrContent.Count;
Area.Parameters.Price = StrContent.Price;
Area.Parameters.Sum = StrContent.Sum;
CurDoc.Output(Area);
StrTotal.TotalPieces = StrTotal.TotalPieces + StrTotal.Count;
StrTotal.TotalSum = StrTotal.TotalSum + StrTotal.Sum;
EndDo;

// Footer
Area = Template.GetArea("Footer");
Area.Parameters.Fill(StrTotal);
IR = InformationRegister.ResponsibleEmployees;
Area.Parameters.Director = IR.GetLast(Date).Director;
CurDoc.Output(Area);
EndProcedure

26.2.3. Editing Template Text

Besides the module text editor features, the template text editor allows creating and
editing available templates (for details on templates see page 2-1160).
2-966 1C:Enterprise 8.3. Developer Guide

26.2.4. Query Text Editor

In this mode the text editor has all the standard features, plus several important
additional features.
Query language syntax is highlighted with color. For a description of query
language constructs see page 1-442 or section "Work with Queries" in the
1C:Enterprise script help.
Editor commands are extended with commands for setting and clearing comments.
In the 1C:Enterprise mode, users with administrative permissions are given the
opportunity to open the query wizard.
Besides query text, query texts can be edited for text documents with the enabled
Query language extension and for text document fields with the enabled Query
language extension.

26.3. CONFIGURATION COMMAND INTERFACE EDITOR

Configuration command interface editor can be used to set up initial order of
sections in  the sections panel (see page 1-85) and initial visibility based on roles.

Fig. 346.  Configuration Command Interface Editor

Command column can specify the order of sections.

Visibility and Visibility by roles columns are used to set default visibility for open
subsystems commands.

26.3.1. General Rules for Setting Visibility

Table box contains a common visibility management column (Visibility column)
and a  set of columns matching the number of roles defined in  the configuration.
Initially the command display order and visibility settings are set up by the system.
You can set up visibility for all commands, as well as for specific commands
selected by roles to which these commands are available.
Chapter 26. Development Tools 2-967

Object visibility can be set up in  the command interface using several methods:
„„ Editing the Visibility column. In this case command visibility is set up for
all roles. Command visibility for a  particular role is  defined by the Visibility
column if a  special visibility management box status is  selected for the role
(see example of Sales subsystem visibility on fig. 346).
„„ Selecting a  specific visibility value (checked or unchecked) for a  particular role
indicates whether the command is  visible by default (or hidden – depending on
the check box status) for the role. Common status (Visibility column) is  ignored
in this case. Thus, fig. 346 demonstrates that Goods inventory section
visibility for the Administrator role is  disabled (though common visibility box
is  checked) and command for navigation to the Enterprise subsystem for the
Sales manager role is visible by default (though default visibility for this
section is  disabled).
Visibility status can be changed for multiple commands from the list.
To show only visible commands in  the Command list press the Hide invisible by
default button.

26.3.2. Filter by Roles

In the Filter by roles field you can specify several roles that will define the current
display of the command list. Only commands available to these roles will be
included in  the list. To disable filtering select Not set. The  selection list allows the
user to enable one of the latest filters quickly.

26.4. START PAGE WORK AREA EDITOR

This editor can be used to set up a  general layout of forms on the start page as well
as the list of forms that can be displayed on the start page.

Fig. 347.  Start Page Work Area Editor

The user can select a  general layout of forms on the Start page in  the Starting page
template field:
„„ One column – the start page displays forms in  a single column.
2-968 1C:Enterprise 8.3. Developer Guide

„„ Two columns, same width – the start page displays forms in  two columns of
equal width.
„„ Two columns, different width (2:1) – the start page displays forms in two
columns and the left column is  twice as wide as the right one.
After the required forms have been selected, the user can specify their sequence
order on the start page and height for each form (Height column).
Visibility editor is  similar to other role-based properties editors (see page 2-942).
As the user develops the start page interface, he/she should pay particular attention
to placing the most important forms on the start page. These are forms that are most
frequently used by users with a  particular set of roles.
Please remember that forms that cannot be viewed by the user due to insufficient
rights are not displayed on the start page regardless of the Visibility column status.

26.5. MAIN SECTION COMMAND INTERFACE EDITOR

This editor can be used to set up commands in  each command bar, their display
order and visibility of command interface items based on roles.

Fig. 348.  Main Section Command Interface Editor

The editor includes two table boxes. The one on the right is used to edit the
command interface; the one on the left contains a hierarchical list of avail-
able configuration commands that can be added to the main section interface.
Commands in  the Available commands list meet the following requirements:
„„ They have no parameters.
„„ Groups indicated for commands belong to the navigation or action panel.
The Command column of the interface editor table box displays structure of
commands grouped by action panel categories (Important, Normal, See also),
navigation panel categories (Create, Reports, Tools) and categories of commands
defined in  the metadata tree branch Common  – Command groups. The table box
Chapter 26. Development Tools 2-969

also contains the Visibility column. The system also creates command visibility
columns for each role defined in  the configuration.
To select the required command expand the appropriate branch in the available
commands table and pick a  command. 
To move the command to the command interface select it  and click Add command
to main section (alternatively, press Enter or double-click the command line).
The  selected command is  moved to the panel and group defined for the command
during setup of the current metadata object (Group property). If the Add command
to main section button is  unavailable, the selected command cannot be moved to
the desktop. For example, it  could happen if the Include in  the command interface
property is  not set for the enumeration.
Initial order of command display in the main section command interface and
visibility settings are set up by the system. The  user can set up visibility for all
commands as well as for specific commands selected by roles to which these
commands are available.
Move a  command button can be used for moving commands between groups.
Commands can also be dragged to the required position within groups of a  single
panel. To set up command order in  a group use up and down buttons.
Pressing the Set default properties button resets the command visibility settings and
group membership to the default system settings.
If the configuration has no subsystems, the editor looks differently:

Fig. 349.  No Subsystems

In this case all system commands are available on the desktop and the user only has
to set their default visibility.
For rules of visibility management see page 2-966. For a  description of filtering by
roles see page 2-967.
2-970 1C:Enterprise 8.3. Developer Guide

26.6. COMMAND INTERFACE EDITOR

The command interface editor can be used to set up commands in  each command
bar, their display order and visibility of command interface items based on roles.
The first (leftmost) column of the table box displays a  complete list of commands
grouped by categories (both system categories Important, Normal, See also,
Reports, Tools, etc. and categories defined in  the metadata tree branch Command
groups) of the action and navigation panels. This is  followed by the column that
manages general visibility of commands.

Fig. 350.  Command Interface Editor

The system sets up the command order automatically. If manual setup of the
command display order is required, use buttons to move the commands up and
down or drag them. In  this case a  line saying (manual order) is  displayed next to
the group. To undo the order changes select Restore automatic order in  the group
context menu.
Move a  command button can be used for moving commands between groups.
Commands can also be dragged to the required position within groups of a  single
panel. To set up command order in  a group use up and down buttons.
Pressing the Set default properties button resets the command visibility settings and
group membership to the default system settings.
For rules of visibility management see page 2-966. For a  description of filtering by
roles see page 2-967.
Chapter 26. Development Tools 2-971

26.7. ALL SUBSYSTEMS EDITOR

All Subsystems editor is  designed to facilitate solving the following tasks:
„„ editing command interface for any subsystem
„„ setting contents and properties for any subsystem
„„ setting up order of subsystems
„„ editing contents of subsystems
NOTE
The subsystem command interface editor can also be opened from the Command
interface subsystem property using the Open link.

The Subsystems list defines the order of subsystems in the configuration tree.
This  order does not affect the order of subsystems in  the sectionsections panel.

Fig. 351.  All Subsystems Editor

To set up subsystem order in  the sections panel, go to the root item in  the Subsys-
tems list and set up the subsystem order.
Subsystem properties can be edited in  the properties palette or subsystems editor
(select the subsystems and click Change current item).
To move a  subsystem (together with subordinate subsystems) select it  and click
Move subsystem. Use the selection window that opens to specify the destination
subsystem for the current subsystem. Transfer to subsystems that belong to the
current subsystem is  not allowed.
For rules of visibility management see page 2-966. For a  description of filtering by
roles see page 2-967.
2-972 1C:Enterprise 8.3. Developer Guide

26.7.1. Subsystem Contents Setup

The subsystems list is followed by the Content hierarchical list that is used
to define contents of metadata for the current subsystem. Please note that the
displayed contents do not include metadata of subordinate subsystems if no meta-
data are defined in  these subsystems.
To modify the contents click Edit subsystem content. It  opens the object selection
window with the metadata tree. Objects with selected check boxes are included
in  the subsystem.
Use the selection window to pick the object to be included in the subsystem
contents. Click OK to close the selection window and generate the subsystem
contents.

26.7.2. Subsystem Command Interface Settings

Subsystem command interface can be set up in  the table box to the right of the
subsystems and commands lists.
For rules of visibility management see page 2-966. For a  description of filtering by
roles see page 2-967.

26.8. QUERY WIZARD

The Query Wizard enables you to write query code in  a module and edit existing
queries.
To call the Query Wizard open a  module, select the procedure that is  to contain
the query, place the cursor in  the part of the procedure where the query code is  or
should be located and select Text – Query Builder.
If there is  no query, the user is  prompted: Query text not found. Create new query?
Clicking Yes displays the Query builder window. If you are editing a  query, the
Query builder window containing the data of the current query appears.
The list of objects can be sorted using the Sort the list button above the Database
list. Pressing the button again cancels the ordering.
You can use the Display change tables button to display change tables for the
configuration objects in  the object list as a  separate Constants (Changes) branch.
Pressing the button again hides the branch.
Click Create a  nested query to create a  nested query (see fig. 352). Compile the
required query in  the query wizard that appears and click OK. The  nested query
will be displayed in  the Tables list.
Click Create a  temporary table description to use the created temporary table (see
fig. 352). In  the displayed form, enter the table name and names of the required
fields and specify the field value type, if necessary.
Chapter 26. Development Tools 2-973

Fig. 352.  Query Wizard in  Report Generator

Fig. 353.  Temporary Table Description

Using the Next > buttons in  the query wizard work your way through the tabs and
select the necessary source data, specify groups and conditions, set the desired order
and describe the resulting data. The  wizard will create a  form and template which
will be placed on the appropriate branches. Using the Query button you can open
a  window with the text of the query generated from the specified data at any time.
2-974 1C:Enterprise 8.3. Developer Guide

To correct the data use the < Back button.

Select the required objects in the Tables and fields tab and move them to the
Tables and Fields sections.
To specify additional criteria you can use the custom expression generation mode
in  your query. To do so, select Add from the Fields list context menu. A custom
expression window appears on the screen.

Fig. 354.  Custom Expression Wizard

The expression text is  generated in  the lower box. You can enter the expression
with the keyboard. For convenience in  entering the names of attributes, you can
drag the desired fields from the fields list and select the desired query language
functions from the list by dragging them with the mouse to the expression text box
as well.
The wizard will also have the Links tab if you specify several tables.

Fig. 355.  Define Link Conditions for Tables

The Links tab enables you to specify the criteria for the links between the table
fields. Click Add to enter a new criterion and select one of the tables from the
Table1 column; from the Table2 column select the table whose fields are linked
Chapter 26. Development Tools 2-975

with those of the first table. Controls that are used to create table link criteria are
located below the criteria list.
On the Grouping tab, if necessary, select the attributes by which items are to be
grouped.

Fig. 356.  Query Result Groups

Specify conditions for source data filtering at the Conditions tab.

Fig. 357.  Query Conditions

Choose a  condition for each selected field (for a  custom condition, set the check
box in  the Arbitrary column). If the check box is  not set, select condition type and
specify parameter description. If the Arbitrary check box is  set, you can use the
custom expression generation window (see above).
2-976 1C:Enterprise 8.3. Developer Guide

Specify any additional criteria on the More tab.

Fig. 358.  Additional Query Parameters

If temporary table creation has been selected on the More tab, fields to be used as
a  basis for index can be picked on the displayed Index tab.

Fig. 359.  Temporary Table Index

On the Unions/Aliases tab, enter field aliases if necessary (see fig. 360).
The table shows the mapping between the selected fields and source data. You can
change field names and mappings. To change the name select the field and press
Enter. Then enter the new field name. To change the mapping select the desired
row in  the Query column and press Enter. Select the desired value in  the drop-
down list.
If you need to select only unique values, check the box in the No duplicates
column.
Aliases for fields that have been changed by the user, loaded from the query text or
assigned mandatory aliases by the wizard at the alias generation step are displayed
in bold.
Chapter 26. Development Tools 2-977

Fig. 360.  Query Unions/Aliases

Specify the result output order on the Order tab (if necessary).

Fig. 361.  Query Result Ordering Setup

As you can see in  fig. 361, the user has selected to output data sorted by date,
while within a  single date sorting by Vendor is  used.
On the Totals tab, if necessary, specify which fields should be subtotaled and
whether overalls should be generated (see fig. 362).
If you press the >> button located next to the group fields, all reference fields are
placed into the group fields. If you press the >> button located next to the totaled
fields, all numerical type fields are placed into the list of totaled fields.
2-978 1C:Enterprise 8.3. Developer Guide

Fig. 362.  Setting Totals for Query Result

The report builder settings are provided in  the Builder tab. Select tables and fields,
specify conditions, order of presentation, and describe the total data.
„„ The Tables tab can be used to edit parameters of virtual table report builder
and mark optional tables. To edit virtual table parameters select the table that
requires parameter setup, call the Virtual table parameters command and enter
the table parameters required for the report builder into the new dialog box. To
mark an optional table clear the Required check box for the appropriate table.
For a  group of optional tables you can also specify its number. Optional tables
with matching group numbers and adjacent link listing are combined into one
optional group. Optional tables with different group numbers are separated into
different groups.
„„ The Fields tab can be used to select the fields that the report builder uses as
available fields in  the report output.
„„ The Conditions tab can be used to select the fields that the report builder uses as
available fields for filtering.
„„ The Order tab can be used to select the fields that the report builder uses as
available fields to sort the results.
„„ The Totals tab can be used to select the fields that the report builder uses as
available fields for report grouping.
The Query batch tab enables the user to create a  succession of batch queries when
working with batch queries. Each query can be edited and configured in  the same
window and all previous tabs allow switching between the queries being configured
(see fig. 363).
Clicking OK in  the program module generates query text. If the wizard attempts
to open invalid query text, the cursor is automatically placed in the query line
containing the error and a  troubleshooting message is  displayed.
Chapter 26. Development Tools 2-979

Fig. 363.  Query Batch

Depending on the source of query wizard call (data composition system, query with
result processing, etc.), the wizard form can have new tabs that are described in  the
calling mechanism description.

26.9. QUERY WIZARD WITH RESULT PROCESSING

This wizard is  designed to generate code for query result processing. This  wizard
helps create the following versions of query result processing procedure:
„„ standard iteration over query results
„„ outputting results to a  spreadsheet document
„„ outputting results to a  plan
To call the wizard use the Query Wizard with result processing context menu item
in  the module editor.
When called the wizard looks for some wizard-created code in  the current line.
If the code can be found, the wizard loads it  (including template names etc.).
In this case query wizard window is different from the query editor described
above (see page 2-937).

Fig. 364.  Query Wizard with Result Processing

2-980 1C:Enterprise 8.3. Developer Guide

If the wizard is  opened in  this mode:

„„ Query result processing type is  selected at the Result handling tab:
○○ Result iteration;
○○ Output to spreadsheet document;
○○ Output to chart;
„„ If Output to spreadsheet document or Output to chart is  selected, parameters
for output into these objects are displayed.
Clicking OK generates the code to be inserted in  the current module position. If the
wizard has been called for the existing code, the old code is  replaced.
When outputting to a  spreadsheet document a  template is  created in  the metadata
object whose object or form module has called the document. It  is  also modified
if the wizard is  invoked again. This  template is  removed if the wizard has been
used to create the spreadsheet document and is now called to generate another
method of query result processing. If the wizard is  called in  a common module,
a  common template is  created.
NOTE
If the configuration editing mode is  set for modes of managed application startup,
report generator cannot be invoked from the metadata object menu.

26.10. REGISTER RECORD WIZARD

Use the register record wizard for documents.
To launch the register record wizard, go to the Posting tab in  a document editing
window, specify the list of registers that will be affected by the document and
press the Register records wizard button. If a  list of records for at least one register
is  defined for the selected document, this item is  available in  the context menu.
When launched the wizard asks the user to select a  register for which a  Posting()
procedure is  generated and opens the wizard window (see fig. 365).
Initially, the list contains only the specified register. You can change the list by
adding registers from the list of registers marked on the Posting tab of the docu-
ment editing window.
Preliminary settings must be specified for each register (depending on its type).
For balance accumulation registers, specify the type of register records.
For accounting registers that do not support correspondence, specify the corre-
spondence type and the account; for those that do support correspondence, specify
the debit and credit accounts.
Initially, the list contains only the specified register. You can change the list by
adding registers from the list of registers marked on the Posting tab of the docu-
ment editing window.
Preliminary settings must be specified for each register (depending on its type).
For balance accumulation registers, specify the type of register records.
Chapter 26. Development Tools 2-981

Fig. 365.  Register Record Wizard

For accounting registers that do not support correspondence, specify the corre-
spondence type and the account; for those that do support correspondence, specify
the debit and credit accounts.
If a  document has tabular sections and their data must affect the status of registers,
include the tabular section in  the Tabular Section selection list.
Then fill the attribute formulas for each register using the data from the document
attributes.
In the list of formulas, place formulas that define how to calculate register records
from the selected document attributes.
You can create these formulas "manually" as follows. Enter the formula in the
Expression column for each register attribute selected in the list. You can type
it manually in this box or manually edit an existing formula there. The wizard
does not verify the formula accuracy.
You can also insert data of the corresponding attribute into a  formula by double-
clicking in  the document attribute list. The  wizard does not check the agreement
of selected attribute types.
If at least one type belongs both to the register and to the register dimension/
resource and their names match, autofilling can be used for these subordinate
objects. When you press the Fill Expressions button, names of attributes are entered
in the Expression column and can be edited.
2-982 1C:Enterprise 8.3. Developer Guide

The wizard creates a Posting() procedure in the object module. The wizard

displays the following warning at the beginning of the procedure: This  fragment
was built by the wizard. Warning! All manually made changes will be lost next time
you use the wizard.

26.11. PRINT WIZARD

The print wizard is  designed to create a  template with specified named areas and
print procedures for a  configuration object.
The print wizard works with the following configuration objects:
„„ catalogs
„„ documents
„„ document journals
„„ charts of characteristic types
„„ charts of accounts
„„ charts of calculations
„„ exchange plans
Basic techniques for working with the print wizard are discussed below using the
example of working with a  catalog. For other configuration object types, there may
be some differences in  working with the wizard.
To start up the print wizard point to the desired object in  the Configuration window.
Select Wizards – Print Design Wizard in  the context menu.
Because the result of the print wizard operation is  a print routine located in  an
object manager module, the wizard begins by checking the accessibility of that
module. If the object module has restricted access, a  password dialog box appears.
After you enter the password, the wizard window appears.

Fig. 366.  Select Behavior Option

First, the wizard prompts to select the startup option for which the print module
is  to be generated.
Chapter 26. Development Tools 2-983

Then it asks the user to create a new print command or modify an existing
command. Name must be specified for a new command. The default command
name is  Print. The  specified name is  subsequently used as:
„„ object command name;
„„ command module server method name;
„„ method name in  an object manager that implements the print procedure.

Fig. 367.  Print Command Creation

If the user chooses to edit an existing command, the following texts are replaced
in  the command module: CommandProcessing() handler, server method with the
command name (Print() in  this case), object manager module method with the
command name and template.
After you press the Next > button, the wizard switches to selection of header attrib-
utes. Create the attribute list using the transfer buttons.

Fig. 368.  Header Attribute Selection

2-984 1C:Enterprise 8.3. Developer Guide

If the configuration object has tabular sections, then after the Next  > button
is  pressed the wizard switches to selecting attributes of the next tabular section.
The  print list is  generated the same way as the header attribute list.
If the configuration object has tabular sections, then after the Next  > button
is  pressed the wizard switches to selecting attributes of the footer.
Then the user should select the group for the created command and specify certain
parameters of the generated document.

Fig. 369.  Print Wizard Settings

Clicking OK closes the print wizard.

The wizard does the following:
„„ Template template with a  print form is  created for the selected object (form
name matches the created command name).
„„ Command is  created for the selected object; it  prepares the spreadsheet docu-
ment and calls the server procedure (with the command name) that fills the
transferred spreadsheet document.
„„ A procedure with parameters allowing to print multiple objects (a list) at one
time is generated in manager module of the selected object. The created
command is  assigned rights similar to the View right for the object that initiates
wizard call.
Chapter 26. Development Tools 2-985

26.12. GENERATION SETTINGS WIZARD

The "Generation settings" wizard makes it easier to develop a procedure to be
used to generate a  new object.
This wizard can be used for the following objects:
„„ catalogs
„„ documents
„„ charts of characteristic types
„„ charts of accounts
„„ charts of calculation types
„„ exchange plans
„„ business processes
„„ tasks
To launch the wizard point to the desired object in the Configuration window.
Select Wizards  – 'Generate' Wizard in the context menu. If "Generate" mode
is defined for the selected configuration object, this item is available in the
context menu.
When you launch it, the "Create Based On…" Wizard window opens.

Fig. 370.  Create based on Wizard

In the upper part you can see a  list of base objects and a  list of attributes for the
base object selected in  the first list.
2-986 1C:Enterprise 8.3. Developer Guide

The lower part displays a  list of attributes for the resulting object.
The object attribute list must be supplemented with formulas to specify how the
document attributes are filled from the selected attributes for the base object.
These formulas can be created "manually" as follows. A formula is  defined in  the
attribute entry Formula text box for the attribute of the object selected in  the list.
Formula can be manually entered or edited in  this box. The  wizard does not verify
the formula accuracy.
By double clicking in the list of attributes of the base object you can also insert
correctly represented data of the corresponding attribute in  the attribute entry Formula
text box. The  wizard does not check the agreement of selected attribute types.
You can also combine these two methods: when placed in  the text box, data from
the list of attributes of the base objects do not replace all of the information already
there, just the selected characters.
Clicking the Fill Expressions button after request and confirmation creates filling
formulas for base object attributes. Auto-filling does not change the previously
filled formulas. Document attributes are matched with base object attributes
according to the attribute names, IDs and types.
Clicking the Clear Expressions button after request and confirmation clears all
formulas created both automatically and manually.
When formulas are created for a base object selected from the base object list,
they are retained in  memory when a  different base object is  selected. So without
ending the wizard session, you can create "Create-on-basis" procedures for several
base documents. You can also resume editing the procedure for any base object by
selecting it  in  the list again.
To end your wizard session use the OK or Cancel buttons (with and without saving
your changes, respectively).
The Refresh button allows you to see your changes in  the form module without
leaving the wizard window.
The wizard creates a Filling() procedure in the object module. The wizard
displays the following warning at the beginning of the procedure: This  fragment
was built by the wizard. Warning! All manually made changes will be lost next time
you use the wizard.
The next time the wizard is  used, all formulas previously generated for any base
document appear in  the document attribute list when the corresponding base docu-
ment is  selected in  the base document list. The  wizard makes formulas generated
in its previous session available for viewing and editing, both through the Fill
Expressions and manually. Moreover, it  also takes formulas entered manually into
the document module into account if they are placed in  the procedure it  gener-
ates. The  wizard does not check the correctness of these formulas. For example,
if filling with two different base document attributes is  specified for a  document
Chapter 26. Development Tools 2-987

attribute, the wizard selects one for display (by alphabet). This is the one that
remains in  the module after the wizard results are updated. The  second line corre-
sponding to the same attribute is  deleted.

26.13. CONFIGURATION OBJECT FORM WIZARD

The Form Wizard is  launched whenever a  new form is  added to any configuration
object that can include a  subordinate Form type object. This  special wizard is  used
to select the form type and set the configuration object attributes. The wizards
have a  great deal in  common, despite substantial differences between the types of
objects for which forms are created. Therefore, the use of form wizards will be
demonstrated using the document form wizard as an example.
When creating a  new form object, the screen displays the form wizard.

Fig. 371.  Form Wizard

The selections available under Select form type depend on the type of object for
which the form is being created. The following forms can be created for the
Document configuration object:
„„ document form
„„ document list form
„„ document selection form
„„ generic form (blank form)
The number of forms for each type is  unlimited. If the object has multiple forms
of the same type, you can choose one of them as the default form. When you open
an object without specifying explicitly which form to call, the default form opens.
2-988 1C:Enterprise 8.3. Developer Guide

To set a  form as the default place a  check mark in  the Set form as default check
box in  the wizard. The  default form can be changed later, on the Forms tab in  the
object editing dialog box (see page 1-59).
Selecting the Generic form type does not result in creation of a main attribute.
In  this case the form behaves in  the normal manner. Selecting another form type
results in creation of a main attribute and sets a different form type behavior.
These exceptions are defined in  objects known as form extensions (see descrip-
tions of relevant object in  the 1C:Enterprise script help).
Form type selection determines the main attribute type and consequently the entire
form behavior, including the available toolbar commands.
Specify the form name, synonym and comment.
The functions of the command bars are determined by the action source and type of
the form main attribute.
When the Finish button is  hit, the wizard automatically places the controls in  the
form and opens it  for editing.
If form attributes have to be changed, click the Next  > button. The  attribute set
depends on the main form attribute.

Fig. 372.  Form Attribute Selection

The attributes to be placed in the form are chosen at this point in the wizard.
Selections are made in  the Attributes column by checking the box to the left of the
entry.
IMPORTANT!
The form wizard does not include non-displayable attribute types (such as Val-
ueStorage) in  the list.
Chapter 26. Development Tools 2-989

26.13.1. Constant Form Wizard Features

Each constant can have its own editing form. To create this form select Create
Constant Form in  the context menu of the relevant constant.

Fig. 373.  Creation of Constant Editing Form

Executing this command opens the common form wizard that lists all system
constants as data and the current constant is  the only selected attribute (by default).

Fig. 374.  Selection of Editable Constants

2-990 1C:Enterprise 8.3. Developer Guide

This form is  also auto-generated by the system if the constant has its Default Form
property non-filled and its Include in  the command interface property filled.
To create an editing form for multiple constants create a  common Constants form
first and then select the constants to be edited in  the attribute selection page.
Constant forms belong to the command interface of the subsystems that own the
constant (if the Include in  the command interface property is  set for the constant)
and the common constant editing form (if the Include in  the command interface
property is  set for the common form).
If an editing form is created for the constant with the specified Include in  the
command interface property, the common form wizard clears the Include in  the
command interface property for the form. Therefore, the constant editing form
is only included in the command interfaces of the subsystems that own the
constant.

26.14. TEMPLATE WIZARD

Use the template wizard to create configuration object templates and common
templates.
The wizard window appears when you select Actions  – Add if the branch of the
subordinate Templates or Common templates object is  selected.

Fig. 375.  Template Wizard

Specify name, synonym and comment and select template type.

The Spreadsheet document type assumes you use standard 1C:Enterprise system
method to create and use spreadsheet document templates.
Chapter 26. Development Tools 2-991

Selecting the Text document type assumes you use text documents specially
prepared as templates. For a  text document, the Extension property is  set to Text
template.
Selecting the Binary data type means that the configuration developer knows how
to work with this type of object.
Selecting the Active document type enables you to use the OLE  active document
technology. If you press Finish, the wizard searches for available Active document
types and offers to select one of those it  finds.

Fig. 376.  Active document Insertion

You can select a  ready Active document and use it  as a  basis for template creation
(load template prototype from a  file). If you have selected a  file whose type is  not
on the list of supported Active documents, the wizard displays a  warning.
Selected document is  saved in  the configuration. Working with the template, you
must use properties and methods provided by the selected platform.
If you select the HTML document type, the HTML template editor opens.
This mode supports all features of the HTML editor. In addition, the HTML
template editor enables you to use pictures from the picture library, from a  file,
from clipart or from "internal" pictures. Internal pictures are those already selected
from a  picture file and stored "inside" the template.
To place a  picture in  a template, select Element – Picture.

Fig. 377.  Picture Insertion

2-992 1C:Enterprise 8.3. Developer Guide

To select a picture press the selection button. Select the required picture in the
window that opens.

Fig. 378.  Picture Selection

The Geographical schema type allows you to create templates using documents
prepared with the geographical schema editor.
If the Graphical schema type is selected, the user can use graphical schemas
prepared in  the graphical schema editor or load schemas from files and use them
as templates.
Selecting the Data composition schema type opens the data composition schema
wizard (see page 1-547).
If the Data composition appearance template type is selected, the appearance
template wizard window appears (see page 1-622).

26.15. FORMAT STRING WIZARD

Use the format string wizard to write expressions using numeric, date and logical
expression representations.
To open the wizard place the cursor over the required module text area and choose
the Text  – Format String Wizard item. The  editor displays the following message
for the new string: Format string not found. Create new format string? Clicking Yes
displays the wizard window.
The wizard can also be invoked from Format and Edit Format properties of form
element. In  this case click the selection button in  the appropriate property.
Window tabs correspond to the data type of the format string to be generated in  the
window.
Chapter 26. Development Tools 2-993

Controls for selecting the presentation format are located on three tabs, according
to the data types:
„„ number
„„ date
„„ logical values
Language (Country) field (L parameter) defines information presentation based on
the regional settings. Values specified in  the following tabs override the country
settings.
Select the Number tab for numbers.

Fig. 379.  Format String Wizard for Numbers

Length field (ND parameter) specifies the total number of decimal places (for the
integer and fractional parts). Precision field (NFD parameter) states the number of
decimal places in  the fractional part.
Shift field (NS parameter) specifies the digit shift. A positive value results in  divi-
sion by 10 to the corresponding power and multiplication is  performed if negative.
Decimal separator field (NDS parameter) specifies the decimal separator.
Thousands separator field (NGS parameter) specifies the thousands separator. When
separator is  set to an empty string, non-breaking space is  used as a  separator.
Grouping field (NG parameter) specifies the option for grouping digits in  the integer
part of a  number.
Zero presentation field (NZ parameter) is  used to select how zero values are repre-
sented. This  parameter can be used in  a format string, but it  is  not used for text
boxes.
2-994 1C:Enterprise 8.3. Developer Guide

Negative number representation field (NN parameter) specifies how negative

numbers are represented.
Leading zeros are displayed when Display leading zeros (NLZ parameter)
is selected.
TIP
The bottom part of the wizard window displays format string results (Example
group) and the format string itself.
Select the Date tab for dates.

Fig. 380.  Format String Wizard for Dates

The date presentation option is  selected in  the Date format field (DF parameter).
The local date presentation option is  selected in  the Local date format field (DLF
parameter). DD parameter value is  not allowed for text boxes.
Empty date presentation field (DE parameter) is  used to select an empty date pres-
entation option. This  parameter can be used in  a format string, but it  is  not used
for text boxes.
TIP
The bottom part of the wizard window displays format string results (Example
group) and the format string itself.
For Boolean type data select the Boolean tab (see fig. 381).
If a  value is  not selected, default settings are used.
For details on format string parameters see a description of the Format String
parameter for the Format() method in  the 1C:Enterprise script description.
Chapter 26. Development Tools 2-995

Fig. 381.  Format String Wizard for Logical Value

If the format string wizard is  used, the generated format string is  inserted into the
text (or text box) when clicking OK.
TIP
The text editor can be used to place the cursor in  the format string and edit it  by
selecting Text – Format String Wizard in  the menu.

26.16. WIZARD FOR STRINGS IN  DIFFERENT LANGUAGES

Use this wizard to edit strings in  all configuration languages and other languages if
their codes are included in  the edited set, but not in  the configuration.
The wizard produces the following string:
<language_code1> = <String_1>; <language_code2> = <String_2>;…

You can use the wizard to easily create the Source Line parameter for the global
context function NStr().
To open the wizard place the cursor over the required module area and choose
Text  – Multilingual string wizard. The editor analyzes the module text where the
cursor is  located and, if the construct is  found, opens the wizard window. If the
construct is  not found, the wizard informs the user about it (see fig. 382).
The wizard window contains as many text boxes as there are languages in the
configuration.
Enter the text and press the OK button. The  wizard produces the following string:
ru = 'Доброе утро!'; en = 'Good Morning!'
2-996 1C:Enterprise 8.3. Developer Guide

Fig. 382.  Wizard for Strings in  Different Languages

26.17. SPREADSHEET DOCUMENT EDITOR

The Spreadsheet Editor in  1C:Enterprise is  used to create various print forms and
forms for viewing and entering information in  spreadsheet documents.
For a  table of shortcuts for the spreadsheet editor see Help menu.

26.17.1. Spreadsheet Documents in  1C:Enterprise

Although 1C:Enterprise spreadsheets may be used for entering, processing and
displaying information like standard spreadsheets (using spreadsheet documents
in  a form), they are mainly used to view processed information, e.g., a  description
of a  printable report form. Program modules in  the 1C:Enterprise system language
are used to process information and place it  on the spreadsheet for most configura-
tion objects.
The 1C:Enterprise spreadsheet editor is  used to work with spreadsheet documents
and print form templates.
Generated spreadsheet documents can be saved to disk in various formats.
If a  document is  saved in  MXL, it  can later be viewed in  the file manager which
is  available at http://1c-dn.com/developer_tools/fileworkshop/.
Templates are stored in  the configuration. There are common templates (located
at Common  – Common templates branch, e.g., templates of standard payment
documents printed based on different documents) and templates for specific
configuration objects (e.g., a  fixed asset card). A configuration object may have
several print form templates.
Spreadsheet documents may also be placed in  a form. Use the Spreadsheet docu-
ment field control for this purpose. In  this mode other controls can be inserted into
a  spreadsheet document.
As far as the user is  concerned, the templates and spreadsheet documents are prac-
tically identical.
Spreadsheet documents (files and templates) may be compared and merged.
Chapter 26. Development Tools 2-997

26.17.2. Template
Templates can be created in  the template wizard (see page 2-990) and the query
wizard with result processing (see page 2-979).

26.17.2.1. General Principles of Template Design

Designing a  template involves creating its components and building blocks (named
areas) that constitute a  ready-to-use output form (report). Since nearly all business
documents have a rectangular structure, it is best to create templates for these
documents in  an editor that supports rectangular elements.
That feature is  provided by the 1C:Enterprise spreadsheet editor. When creating
a template, the following may be done: entering texts into spreadsheet cells;
configuring formatting parameters (for the entire cell); modifying row height and
column width; adding lines, rectangles and other graphical elements to templates
(pictures, OLE objects and plans) and various controls; specifying appearance for
the entire spreadsheet or separate cells and cell groups.
Please remember the following when creating a  report template.
Virtually every report has a header which contains the report name and source
parameters. These data are generally included in  a named Header area. If a  report
contains a  tabular section, the header usually contains column names.
Create named areas (Row in  the example on fig. 384) for outputting information to
spreadsheet. It  is  normally impossible to know the number of spreadsheet rows
in  a template; however, the structure of information is  always the same. There-
fore, the same areas should be used for each row when creating a  report. Different
parameters (Account, Description, Price, Total, etc. in  the example below) should
be assigned to cells for outputting specific information. First, values of these
parameters are written for each row, then a new area is placed into the report.
This  procedure is  repeated until all information on the spreadsheet is  output.
A report usually ends with summary data and attributes of the responsible persons.
This information is placed in the Footer area.
A finished template consists of several rectangular areas representing parts of the
report: report header area (name, date, etc.), column header area, etc (see fig. 383).
The report generation procedure is  described below.
„„ Reports are always created as empty spreadsheet documents. Please note that
a template is not directly linked with the finished report. A template is a
wizard, a  set of areas used by the program module to make a  report.
„„ When the report algorithm is processed, named areas are extracted from
template in  the required order, translated (parameters are replaced with values)
and copied to the final report. The  report language permits expansion of reports
both horizontally and vertically.
2-998 1C:Enterprise 8.3. Developer Guide

Fig. 383.  Sample Template

26.17.2.2. Template Cell Properties

Template Property Category
The Template property category is shown if the Template option is turned on
in  the spreadsheet document properties.
The FillType property specifies what information is  stored in  a cell. This  option
is  displayed if the Values category does not have the Contains Value option turned
on. It  does not change cell appearance and is  used only during template processing
when the final spreadsheet document is  generated.
This list contains the following items (see table below).
Data Format Details
Text The cell contains text information which is  to be moved into the final spreadsheet docu-
ment from the template without any changes.
Parameter Cell information is  a parameter. The  name of this parameter is  specified in  the Param-
eter property.
Template Cell contains text with parameter names in  brackets. When a  spreadsheet document
is  generated, variables are calculated and placed into the text. The  place allocated to
parameter values depends on the value length.
Sample template: Director: [Director]

Information in  the cells of final spreadsheet documents is  transformed to String
type.
Chapter 26. Development Tools 2-999

Parameter – the name of parameter for cell contents. This  property is  displayed
if the Values category contains the Contains Value property or when the FillType
property of the Template category has the Parameter value.
Details Parameter – specifies the parameter for processing cell value details.
It is reasonable to use this property when the resulting spreadsheet document
is  located in  a form (Spreadsheet Document Field control).

Fig. 384.  Cursor Types in  Spreadsheet Document

When a  finished spreadsheet document is  opened in  the Read Only mode and the
mouse is  moved over a  cell with the Details Parameter property filled, the mouse
pointer can appear as shown on fig. 385. (Hyperlink type cursor is  only displayed if the
Hyperlink property is  set for a  hyperlink cell). It  means that you may view the detail
of a  spreadsheet document. Now, if you double-click this cell (or make it  active and
press Enter or simply click it  if it  is  a hyperlink), the field value is  displayed:
„„ String, Number, Date and Enum values are opened for viewing;
„„ for Document values corresponding documents are opened for viewing and
editing;
„„ if a  value is  a catalog item, this item is  opened for viewing and editing in  a
dialog box. If editing in  the list is  turned on in  catalog properties, a  catalog
list form is  opened and the spreadsheet field pointer is  moved to the required
catalog item.
This is  standard detail processing that does not require any additional settings.
If you want special details processing, specify the name of the handler procedure
for the cell for the Detail Processing event in  the Events category of spreadsheet
document properties. Describe drill down processing in  the form module in  this
procedure using the 1C:Enterprise script.
Review the following example. A form and PrintTemplate template have been
created for a  report. The  template includes Title, Header, GoodsHeader and Goods
named areas. The  Goods area contains a  cell which has a  details parameter named
Detail The form contains the Table form element associated with the Spread-
sheet form attribute of the SpreadsheetDocument type. The  Detail Processing
property in  the Events category refers to the cell selection processing procedure
named DetailProcessingResult() located in  the report module.
2-1000 1C:Enterprise 8.3. Developer Guide

The following procedure is  used to generate a  spreadsheet document:

Spreadsheet.ShowGrid = False;
Spreadsheet.ShowTitles = False;
Spreadsheet.Protection = True;
Spreadsheet.ReadOnly = True;

Template = Documents.GoodsConsumption.GetTemplate("PrintTemplate");

// Header
Area = Template.GetArea("Title");
Spreadsheet.Output(Area);

// Header
Header = Template.GetArea("Header");
Header.Parameters.Fill(ThisObject);
Spreadsheet.Put(Header);

// Goods
Area = Template.GetArea("GoodsHeader");
Spreadsheet.Put(Area);
GoodsArea = Template.GetArea("Goods");

For Each CurRowGoods From Goods Do

GoodsArea.Parameters.Fill(CurRowGoods);
Spreadsheet.Put(GoodsArea);

EndDo;

Sample implementation of details selection processing procedure:

Procedure DetailProcessingResult(Item, Details, StandardProcessing)
StandardProcessing = False;

DetailsType = TypeOf(Details);
If Detailstype = Type("CatalogRef.Nomenclature")
Then

ReportFormName = "ReportForm1";
Else

ReportFormName = "ReportForm2";
EndIf;

ReportForm = DataProcessorObject.GetForm(ReportFormName);
ReportForm.ExecuteReport(Details, PeriodFrom, PeriodTo);
ReportForm.Open();

EndProcedure

ReportForm1 and ReportForm2 are forms developed specifically for detailed

reports (usually these forms contain a  spreadsheet document field where the result
is output).
Chapter 26. Development Tools 2-1001

Drill Down Use – specifies the drill down use area. If a  cell is  selected, drill down
are shown for the current cell only; if a  row is  selected, drill down are shown for
all cells in  the current row. If DontUse is  selected, no drill down are shown in  any
case: the pointer does not change its appearance (for possible cursor types see fig.
384) and cell selection is  not processed.
Values Property Category
Contains Value – if this option is  turned on, a  cell contains a  value. This  property
influences the properties of other categories.
Value Type – type of cell value. For spreadsheet documents, this list contains
Number, String, Date and Boolean types. For Spreadsheet document field form
element, the list also contains types defined for the current configuration, including
documents, catalogs, enumerations and others, in addition to primitive types.
The  Arbitrary data type may be added as well. This data type may be deter-
mined with 1C:Enterprise script tools during form filling.
Control – a  control may be selected for editing cell contents. The  list of possible
values depends on the selected content type. For example, if Number data type
is selected, Text box or Checkbox may be used as an editor. A row with the editor
type Text box or Checkbox is  added to the object list (Cells, Spreadsheet Docu-
ment) for the specified editor type. Contents of the properties palette for this object
depends on the type of selected control.
Format – format string to be used for displaying the value. If the display format
is  not configured, it  is  selected from the infobase regional settings.
Editing format – a  format line that will be used for displaying the value is  speci-
fied. If the image format is  not configured, the format is  selected from infobase
regional settings.
Format can be entered manually or using the format string editor (see page 2-992).
NOTE
When a  spreadsheet document is  edited in  a thin client, the following cell prop-
erties are not available: Contains Value, Value Type, Control, Editing format.

26.17.3. Spreadsheet Document in  Data Input Mode

A report can also be created by entering information into cells of a  spreadsheet
document placed into a  form element.
This information is  processed with 1C:Enterprise procedures located in  the form
module. Calculation results may be used to calculate values for other cells of
a  spreadsheet document.
After entering the required information, you may print a report and save it for
future work.
2-1002 1C:Enterprise 8.3. Developer Guide

The overall procedure for working with a  spreadsheet document in  the data input
mode looks like the following:
„„ Spreadsheet document template is  generated; it  is  prepared in  a special way
and used to input data.
„„ A form that will contain a  Spreadsheet document field field for data input
is generated.
„„ Spreadsheet document field form element handlers that will process user-
entered data (when necessary) are generated.
Let us review the steps listed above using generation of a goods delivery form
based on the GoodsDelivery document. The  target form is  demonstrated on fig.
386. In  this form, underlined fields are to be filled in  by the user. Delivery date
field value is automatically calculated by summing up Issue date and Delivery
period values. Issue date is  the document date.

Fig. 385.  Delivery Form

26.17.3.1. Spreadsheet Document Preparation

Implementing a  table box in  the data input mode requires a  Spreadsheet docu-
ment template (named DeliveryForm). The generated template must then be
opened and its Template property must be set to False.

Fig. 386.  Spreadsheet Document Properties

Chapter 26. Development Tools 2-1003

Then the required structure must be created for the document to be generated.
Create the required fields:
„„ Delivery address. Merge several cells and define the following properties:
○○ Name – ShipToAddress
○○ Protection – False
○○ Contains Value – True
○○ Value Type – String
○○ Control – Text box
„„ Delivery period. Define the following properties for the cell:
○○ Name – DeliveryTime
○○ Protection – False
○○ Contains Value – True
○○ Value Type – Number, length: 3, precision: 0, non-negative
○○ Control – Text box
„„ Delivery date. Define the following properties for the cell:
○○ Name – DeliveryDate
○○ Protection – False
○○ Contains Value – True
○○ Value Type – Date, date content: Date
○○ Control – Text box
„„ Issue date. Define the following properties for the cell:
○○ Name – IssueDate
○○ Protection – True
○○ Contains Value – True
○○ Value Type – Date, date content: Date
○○ Control – Text box
○○ Format – DLF=DD
The resulting spreadsheet document should look as shown on fig. 387.

Fig. 387.  Finished Template

The Show Named Cells mode is  enabled for the template (to do this, select Table –
Names – Show Named Cells in  the menu).
2-1004 1C:Enterprise 8.3. Developer Guide

NOTE
Properties that can be set for the text box in  the template are neither saved nor
used by the system to generate text boxes in  spreadsheet documents in  the data
input mode.

26.17.3.2. Form Preparation for Data Input

After the spreadsheet document template has been finished, generate the form to be
used for data input and implement a  procedure to call it  from the document.
Create ExecuteDelivery form command with the following code in the docu-
ment:
&AtClient
Procedure ExecuteDelivery(Command)

DeliveryParameters = New Structure("DocumentDate", Object.Date);

OpenFormModal("Document.GoodsDelivery.Form.DeliveryExecution", DeliveryParameters);

EndProcedure

The command should be placed in  the form.

Now create the form to be used for data input.
To do this, create a custom DeliveryExecution form in the GoodsDelivery
document and generate the following form elements:
„„ DocumentDate form parameter of Date type
„„ DocumentDate form attribute of Date type
„„ SpreadsheetDocument form attribute of SpreadsheetDocument type
„„ SpreadsheetDocument form element associated with SpreadsheetDocu-
ment form attribute

Fig. 388.  Delivery Execution Form

Chapter 26. Development Tools 2-1005

After that implement the following handlers in  the form:

&AtServer
Procedure OnCreateAtServer(Cancel, StandardProcessing)

// Save document formatting date

DocumentDate = Parameters.DocumentDate;

// Set finished template

SpreadsheetDocument = Documents.GoodsDelivery.GetTemplate("DeliveryForm");

// Set document creation date in  the spreadsheet document field

SpreadsheetDocument.Area("IssueDate").Value = DocumentDate;

EndProcedure

&AtClient
Procedure OnOpen(Cancel)

// Activate spreadsheet document area

Items.SpreadsheetDocument.CurrentArea = SpreadsheetDocument.Area("ShipToAddress");

EndProcedure

The resulting form filled with data looks like the following:

Fig. 389.  Delivery Form

2-1006 1C:Enterprise 8.3. Developer Guide

26.17.3.3. Implementation of Response

to Spreadsheet Document Cell Change
The resulting form has no recalculation for Delivery period and Delivery date fields
should they change.
To make recalculation possible, implement processing of the relevant event for the
form attribute associated with the spreadsheet document.
Add the OnChangeAreaContent handler for the SpreadsheetDocument form
element. The  handler should contain the following code:

&AtClient
Procedure SpreadsheetDocumentOnChangeAreaContent(Item, Area)

If Area.Name = "DeliveryDate" Then

SpreadsheetDocument.Area("DeliveryTime").Value =
(SpreadsheetDocument.Area("DeliveryDate").Value -
StartOfDay(DocumentDate)) / (24 * 60 * 60);

ElseIf Area.Name = "DeliveryTime" Then

SpreadsheetDocument.Area("DeliveryDate").Value =
StartOfDay(DocumentDate) +
SpreadsheetDocument.Area("DeliveryTime").Value *
24 * 60 * 60;

EndIf

EndProcedure

Now the spreadsheet document is  interactive.

26.18. FLOWCHART EDITOR

Flowchart is  the schema of the sequence of actions for a  business process. It  is  a
part of the graphical schema.
The main difference between a  flowchart and a  graphical schema is  the special
processing of particular schema items (start and end points, actions, conditions,
etc.).
The flowchart also plays the role of system instruction on the business process
execution sequence and an illustration of the business process structure as well
as a means to view the current state of a business process (see description of
GetFlowchart() method in  the 1C:Enterprise script help).
Flowchart is  a rectangular screen area that usually contains different items, e.g.,
start point, end point, decorations, connecting lines, etc.
Chapter 26. Development Tools 2-1007

26.18.1. Flowchart Editing

To edit a  flowchart in  the business process edit window, click Route map on the
Other tab.
You can edit a  flowchart by placing various map items on the flowchart, editing
properties of these items and connecting these items with lines.
You can use both the mouse and the keyboard to edit a  flowchart. (Some opera-
tions can be performed only with the mouse, e.g., you cannot use a  keyboard to
connect flowchart items with lines.) When a  flowchart is  opened for editing, the
Insert schema elements toolbar buttons and the Flowchart menu become available.
You can use the properties palette to configure a  flowchart (see page 1-53).

26.18.2. Flowchart Items

26.18.2.1. Appearance Recommendations
The best way to draw a  flowchart is  to place the map in  the vertical direction.
A flowchart is vertically arranged (top-down). For example, when you add an
Activity flowchart item (hereinafter referred to as an item), it is created with an
outgoing downward-oriented connecting line.
Labels should use identical fonts. You can use various fonts as an additional means
to attract attention (e.g., in  a header of a  decoration of a  group of items).
You can use the flowchart editor to put various items into flowcharts, specify item
size, level borders, etc.
The flowchart editor provides different features that simplify item placement. These
features include a  grid and different actions with item groups (leveling, distribution
in  a flowchart, size specification, etc.).
You can use individual item appearance as an additional feature. In properties
under Appearance, the developer can select text and background colors, text font,
border type and color, a  picture to be displayed, tooltips, etc. Item properties vary
depending on the type of item.

26.18.2.2. Items Order

Unlike regular graphical schemas, the flowchart preserves the type-specific order
even if the order of certain items has changed. The  following rules apply:
„„ Decorations are always located in the background (below), i.e. you cannot
change the order of decorations as related to other items as they are always
located below.
„„ Connecting lines are located above decorations.
„„ All other items (business process visualization points) are located at the top.
In this manner, when drawing the flowchart items, they are always placed
above the decorations and decorative connecting lines by sort order.
2-1008 1C:Enterprise 8.3. Developer Guide

26.18.2.3. Working with Connecting Lines

Flowcharts are used to show business process sequences by linking item with the
Connecting line item. You cannot insert connecting lines arbitrarily as they are
always attached to certain points in  the business process and cannot exist per se.
You cannot delete connecting lines unless allowed by the point in the business
process (for example, Spliting Point and Switch).
You can link all business process visualization points, i.e. all items except Decora-
tion, Connecting line and Decorative line items. By default most business process
visualization points are inserted into route maps with one outgoing line that cannot
be detached or deleted. However, you can move this line to a  different port. A port
is  an area of an item where a  line can be attached – usually it  is  a middle point
of one of the sides of the rectangle containing the item. Available ports are marked
with blue crosses on the map.
To work with the Connecting line item of a flowchart, you have to select it by
clicking anywhere on the connecting line or by using the Tab (Shift + Tab) key to
switch to it.
If the end of a line is not attached to any item, the rectangle at the end of the
line is  red and the arrow has an contour appearance, i.e., it  is  not painted inside.
To connect the line to an item you have to drag the end of the line (a grey or red
rectangle) to the port area of any item. The connecting line shall automatically
rebuild upon dragging. You can also reconnect a  connecting line by dragging its
end to a  different item. In  this case the following restriction applies: you cannot
create a  direct cycle of items (point1 → point2 and point2 → point1) if neither of
these flowchart items belongs to the Condition Point or Switch item types.
When you insert an item into the flowchart, free ports of these items are automatically
connected to the closest available lines if it is possible. When you move or resize an
item, the free ports of this item are automatically connected to the closest available
lines and the outgoing lines of this item with free ends are automatically connected to
a free port of other items in direct proximity if such a connection is possible.
Decorative line item is designed to connect decorations and flowchart points.
You can place any number of decorative lines in  a flowchart.

26.18.2.4. Flowchart Check for Correctness

When you run the Flowchart  – Test command or save a  flowchart, the flowchart
is  automatically checked for correctness. The  following improper conditions are
checked:
„„ cycling;
„„ unconnected lines;
„„ route points (except for starting points) that have no incoming lines;
„„ flowchart without starting points;
„„ route points without a  path to the end point;
Chapter 26. Development Tools 2-1009

„„ flowcharts where some of the lines entering the join don't come out of the corre-
sponding splitting point;
„„ flowcharts where parallel branches (coming out of the splitting point) enter the
same route points (before the join);
„„ flowcharts with a cycle that do not contain any points of Activity, SubBusi-
nessProcess Point or Data processor Point type;
„„ flowcharts where any route point of Condition Point or Switch type has no event
handler (ConditionCheck() or Switch(), respectively).

26.18.3. Flowchart Items

This chapter describes all types of flowchart items listed alphabetically.
Behavior of items is  configured in  the properties palette by setting and selecting
values. Some item properties are common for all or most items. Individual proper-
ties of each item are detailed in  the 1C:Enterprise script help.

26.18.3.1. Common Properties of Flowchart Items

There are many properties that are common for all or most item types. Usually these
properties have a  common purpose and are edited in  a uniform manner. Below you
will find a  description of these properties. For more information on editing unique
properties of some items, see the sections dedicated to individual item types.
Only properties that make flowchart items different from graphical schema items
are described.
For descriptive convenience, the properties are grouped by category as they are
in  the properties palette.
Some properties that are described below can be unavailable for some items.
Main Property Category
Task Description – description of the task to be generated in  Activities or SubBusi-
nessProcess Points.

Events Property Category

Use this category of properties to configure the business process point behavior
for specific actions, e.g., for interactive activation, task creation, condition check
(for Condition Point items), etc.
When working with items, most actions can initiate the launch of procedures
related to these actions. The body of each procedure contains a description
of event handling in  the 1C:Enterprise script.
To initialize the creation of a procedure responsible for event handling, click
a  special button on the properties palette located to the right of the attribute with
event name in  the Events property category (see fig. 390).
2-1010 1C:Enterprise 8.3. Developer Guide

Fig. 390.  Creation of Event Handler

The procedures are created in  the business process module which contains the edit-
able flowchart as a  property.
When you work with a business process and a certain event occurs, program
execution control is  passed on to a  procedure that is  linked to this event.
For a  list of flowchart events or items along with conditions that invoke them, see
a  description of the relevant object in  the 1C:Enterprise script help.

26.18.3.2. Connecting Line

Connecting line items of the flowchart are used to connect business process visuali-
zation points (e.g. Start Point, Activity, Condition Point and other items). Connecting
line items are automatically rearranged when you change the item position.
You cannot modify the connecting line creation algorithm.
Connecting line is  inserted automatically when you enter the other flowchart items;
it  cannot exist by itself. Only Spliting Point and Switch items allow you to insert
additional connecting lines.
When the system creates a connecting line, it tries to create the shortest path
consisting of vertical and horizontal line sections that does not cross other map
points.

26.18.3.3. Activity
Activity items in a flowchart are used to display the main points of a business
process that are used to assign and execute tasks.
Addressing Property Category
Explanation – a line that contains additional characteristics of the activity.
It  is  used when addressing attributes are inserted by the 1C:Enterprise script and
not predetermined during flowchart design.
Group – if this option is  set to True, all tasks for this business process point are
issued to all group (department) members. Otherwise, one task is  assigned to the
entire group, e.g., Sales Department and only one person (the first who undertakes
it) shall execute this task.
Addressing attributes – the number of these properties equals the number of
addressing attributes for a  task selected in  the Task property of the current busi-
Chapter 26. Development Tools 2-1011

ness process. You can use the properties palette to select one of the predefined
values of the type specified in  the addressing attribute of the task (e.g., from the
Departments or Performers catalog).

26.18.3.4. Splitting Point

The Splitting Point item of a flowchart contains a business process point where
the work flow splits into multiple parallel threads. By default this item has three
outgoing connector lines.
Use the Add Outgoing Connector Line command from the context menu to add an
outgoing line to this item. To delete an outgoing line you have to select this line
and use the Delete command from the menu. You cannot delete the only remaining
outgoing line.

26.18.3.5. Condition Point

Condition Point item is  a business process point that has two possible exit points
depending on the logical condition.
By default, Condition Point has two outgoing connecting lines from the left side and
from the right side. The  right line contains the process for the True value of the
ConditionCheck() handler. You can swap the condition branches. To do this,
drag a  rectangle at the beginning of the line outgoing from Condition Point and
move it  to the opposite side of the Condition Point item.

26.18.3.6. End Point

End Point item contains the end point of a  business process. A flowchart can have
several items of this type.

26.18.3.7. Start Point

Start Point item contains a  business process start point. If a  business process has
several Start Point items, you have to specify the required start point when you run
the process. The  Start Point item cannot contain connecting lines.

26.18.3.8. Join
Join item of a  flowchart map contains a  business process point where all parallel
paths going out of the Spliting Point join. Until the task execution for all parallel
paths arrives at the join point, no transfer to the point beyond the join point
is  executed. One splitting point always corresponds to one join point (although the
opposite is  not true; hence, there can be splitting points with no join points). You
do not have to specify explicitly which Spliting Point item corresponds to the Join
item. The  system determines it  automatically.
2-1012 1C:Enterprise 8.3. Developer Guide

26.18.3.9. SubBusinessProcess Point

SubBusinessProcess Point item contains a business process point that executes
a  business subprocess. Execution of the main (parent) process resumes only after
the subprocess is  complete.

Data Property Category

Business process – a  reference to a  business subprocess.

26.18.3.10. Data processor Point

Data processor Point item contains a business process point that is executed
in  automated mode and has no destination.

26.18.3.11. Switch
Switch flowchart item contains a  business process point with several exits (vari-
ants), one of which is  selected on the basis of the Variant parameter value of the
SwitchProcessing() handler.

26.18.4. Module
Flowcharts have no modules of their own. Event handlers are placed in  the busi-
ness process object module.

26.19. PICTURE EDITOR

The Designer offers users a  special tool to edit pictures and picture collections.
Pictures are stored in the Common  – Common pictures configuration branch as
well as in  the files on the local hard drive.
The Actions  – Add command of the Common  – Common pictures configuration
branch creates a  new picture which then can be opened for editing.
To edit a picture select it in the Common  – Common pictures configuration
branch and then use the Actions – Change menu command; in  the dialog box that
opens click the Edit button. If the picture format is  different from PNG, the soft-
ware prompts the user to convert the picture to PNG when it  is  opened. If the user
cancels conversion, the picture cannot be edited.
WMF or EMF pictures cannot be edited.
To create a  new picture located in  a file on the local drive, select File – New and
select Picture in  the editor selection window. Edit the empty picture and save it  by
selecting File – Save or File – Save as…
Chapter 26. Development Tools 2-1013

To edit a  picture stored in  a file on the local hard drive, select File  – Open and
then select the necessary file from the list.
The editor has two modes of operation: picture editing and picture collection
editing. The  difference between picture and picture collections editing is  purely
conventional. A picture collection is  a picture consisting of multiple picture items
of the same size. Any picture can be saved as a  picture collection. For example,
a  picture collection can be used to store and edit pictures with similar application,
like icons, button pictures, etc. The  picture-editing mode is  a default mode of the
editor.
Editing methods are independent of the selected picture type (see page 2-1013).
For details on how picture collections work see page 2-1016.

26.19.1. Picture Editing

When you have selected (or created) a  new picture, it  can now be edited.

Fig. 391.  Picture Editor

The editor window consists of a  toolbar, two panels (the preview panel on the left
hand side and the editing panel with the magnified picture on the right hand side)
and a  color palette where you can select colors.
2-1014 1C:Enterprise 8.3. Developer Guide

The picture can be edited in  both panels. Editing is  done using the mouse. First
you should select a  painting tool or a  shape (pencil, brush, airbrush, rectangle or
ellipse) and a  color using the color palette.
The status bar shows the current position of the mouse pointer as well as the scale
of the image.
A picture is  a rectangle consisting of a  grid of dots (pixels) that you can resize
by dragging the handle on the lower or right border or in  the lower right corner.
A picture can also be resized using the Picture Settings window (see below).
Editing consists of setting the color of each dot in the picture. The number of
colors is defined by the picture resolution. The larger resolution is, the more
colors can be used.
IMPORTANT!
Using 24-bit resolution for large pictures leads to an increase in  the configuration
size.
Color selection is made separately for each mouse button in the color palette.
The  selected color is  outlined by a  double frame.
Each color can be modified. To do so, double-click the color you want to modify.
In  the window that appears, select the color you need form color swatches or create
a  new one.
Picture size can be changed. Dragging a  handle located on the sides or the corner
of the picture area is  just enough to achieve this task.
The grid (of pixels) is designed to simplify picture editing. The grid is formed
with dotted lines. To setup grid display select Actions – Grid. The  following dialog
will open:

Fig. 392.  Grid Settings

If the Pixel grid check box is  checked, the pixel grid is  displayed.
If the Image grid check box is checked, the program handles the picture as
a picture collection consisting of pictures of the same size (picture collection
editing is  discussed in  the next section). In  this case collection item size selection
fields become active. Besides the pixel grid, a  collection grid is  displayed in  the
picture editing field consisting of thin solid lines. However, the editing mode stays
the same.
Chapter 26. Development Tools 2-1015

If the Image grid check box is  checked, the picture resize step is  equal to a  cell
size. If this check box is  unchecked, the picture is  resized by one pixel.
Various tools and the set of shapes are used for drawing. The  set of tools and the
way they are used is  similar to the standard tools used in  Paint, an integral part of
Microsoft Windows. The  shortcut table for the picture editor can be found in  the
Help menu.
However, there are some differences. By using the Scale button you can scale the
image from 1:1 to 20:1 in  a six step operation. By clicking the button you select
the next scale step. If you reach the 20:1 scale, the next time you click this button
the image is  returned to the original scale, 1:1. The  necessary scale can be selected
at once by clicking the scale selection button with a  small triangle pointed down-
ward, located to the right of the scale button.
Clicking Scale and dragging the mouse pointer over any picture area causes the
frame to appear. The  latter indicates the picture area to be displayed when the user
clicks the mouse.
You can also change the scale by holding down the Ctrl key and scrolling your
mouse scroll.
Shape buttons (rectangle, rounded rectangle and ellipse) also have selection buttons
and by using them you can select the shape type (common, outlined and filled or
filled).
Clicking the Picture parameters button opens the following dialog box:

Fig. 393.  Picture Settings

The picture size and resolution (the maximum number of colors) are set in  this
dialog. Alpha channel cannot be used for pictures with 1-, 4- or 8-bit resolution.
Only one transparent color is allowed. Alpha channel can be used if resolution
is  higher than 8 bit.
NOTE
It is not recommended to use alpha channel for pictures that are bigger than
40000 pixels in  size (e.g., 200х200 pixels). The  web client operating in  Micro-
soft Internet Explorer 6.0 cannot render these pictures correctly. This  rule does
not apply to picture collections with items smaller than the size mentioned above.
The picture editor supports standard clipboard commands. Use Ctrl  +  V to paste
a picture, Ctrl  +  C to copy it  and Ctrl  +  X to cut (copy and delete). If the picture
size is  larger than the current dimensions, the editor suggests that you change the
current dimensions.
2-1016 1C:Enterprise 8.3. Developer Guide

The toolbar contains a  button that changes its purpose depending on the selected
tool or shape. It  is  located in  the second row to the right next to the Picture param-
eters button. When the line or freehand tool, rectangle or ellipse shape is  selected,
this button indicates thickness of the line used to draw the shape in pixels. By
clicking this button you can modify the thickness (five steps). By clicking the selec-
tion button you open the pop-up menu where you can select the thickness you need.
This  button sets the size of the airbrush, the size and shape of the brush and the
size of the eraser. When a  selection or text tool is  active, this button allows you to
set the transparency mode.
Click the Text button to enter text. The  following dialog box is  displayed:

Fig. 394.  Text Entry Dialog Box

Enter the text in  the multiline text field. The  font family, size and other attributes
are set using the Font button. The  font family is  selected from the list of system
fonts or from the styles defined in  the configuration.
By using the Replace Colors button you can easily change the font color selected
by the mouse pointer on the color set for the given mouse key. In  this fashion you
can quickly change the drawing color using two colors per mouse key.

26.19.2. Picture Collections

A picture collection is  a picture consisting of individual items (pictures) of the
same size. These items form a rectangular matrix and each cell of this matrix
contains an independent picture.
Picture collections are designed to simplify the selection of the necessary picture for
controls, column title bars and so on. By using the collection you enable selecting
pictures of the same size for identical application.
The picture editor enables you to create and edit picture collections. Select Collec-
tion Mode to go to the collection editing mode. By selecting this item you break
the picture in the preview field into cells. To edit a picture item in the editing
field simply double-click it. The  drawing techniques are discussed in  the previous
section.
Two buttons (Add Column and Add Row) are added to the toolbar. By clicking these
buttons you can add a  new column or a  row respectively to the picture.
Item size can be modified in  the Picture Settings dialog box only (scale handles are
not available).
Chapter 26. Development Tools 2-1017

Fig. 395.  Collection Parameters

In the Picture Settings item group, the cell (picture) parameters are set. In the
Collection Options item group, cell size in  pixels (dots) are set.
A picture collection can also be edited as a common picture. If you do this,
it  is  recommended that you setup the image grid first (see page 2-1013).

26.20. HTML DOCUMENT EDITOR

This editor offers the user all the major features for editing HTML documents.
It  can also be used to edit help content for configuration objects.

Fig. 396.  HTML Document Editor

The editor has three tabs:

„„ Edit – use this tab to edit documents in  visual mode.
„„ Text – use this tab to edit documents with the help of HTML markup language.
In  this case editor functionality matches that of the text editor (see page 2-943).
„„ Preview – this tab can be used to preview the created document; however,
editing is  unavailable.

26.20.1. Visual Editing

26.20.1.1. Formatting Text
You can format HTML document text, e.g., set up its style (font, size, decoration,
indents, alignment, etc.).
When you copy text from other text editors, for example Microsoft Word, the
original text formatting is  retained.
2-1018 1C:Enterprise 8.3. Developer Guide

26.20.1.2. Inserting and Editing Tables

You can add tables to HTML documents. To do this, select the Table – Insert Table
command. A dialog box will open. Type a  number of rows and columns in  the
dialog box.
If you find out later in  the course of editing that the specified number of rows or
columns is  not sufficient, more can be added.
To edit a  table (insert and/or delete rows, columns and cells), use the commands
from the Table menu of the Designer main menu.
"Table" menu option Action
Insert Row Add a  new row above the current one
Delete Row Delete the current row
Insert Column Add a  new column on the right
Delete Column Delete the current column
Insert Cell Add a  new cell on the left. All the cells on the right are shifted
Delete Cell Delete the current cell. All the cells on the right are shifted to the left
Merge Cells Merge two cells (the current cell and the one on the right). The  information
entered into these cells is  also merged. If more than two cells need to be
merged, repeat this operation several times
Split Cell Split the current cell into two cells

Tables can be nested. To add a  nested table create a  new table in  a cell of the
existing table.

26.20.1.3. Picture Insertion

You can insert pictures into your HTML document.
To insert a  picture select the Element – Picture command. A dialog box will open.
Type in  the path to the picture file (a path and a  file name) or select a  file in  a
standard file selection dialog box. In  the Text field, enter tooltip text which will
show up as a floating popup in the view mode when the user hovers a mouse
pointer over the picture.
If necessary, specify picture alignment (position in  the document) in  the Layout
attribute group.
Alignment Option Actions
Not assigned Picture is  in  the text
Left Picture is  in  a new row closer to the left border of the document
Right Picture is  in  a new row closer to the right border of the document
Above the Text Picture is  in  a text aligned towards the center of the picture
Bottom Picture is  in  a text aligned towards the bottom of the picture
Middle Picture is  in  a text aligned towards the center of the picture
Top Picture is  in  a text aligned towards the top of the picture
Chapter 26. Development Tools 2-1019

If the picture has to be placed in  a border, enter border width in  the Border width
dialog box attribute. If the width is  not defined or equals 0, then the border is  not
displayed. Click OK to insert the picture. Attributes specified in  the dialog box can
be changed using the picture properties palette.
Inserted pictures can be moved. To do this, point to the picture and drag it  to the
correct place in the document. The Position picture property does not change
in this case; for example, if neither Left nor Right is set up, the picture can be
added to the text, otherwise the picture is  placed in  a new row.
Pictures can be copied. Copy operations are standard (through the clipboard or
using the mouse with the Ctrl key held down).
Pictures can be placed anywhere in  HTML documents (text, table or label).

26.20.1.4. Marquee
Marquee is  a special object of HTML documents. It  is  an area where text, a  table,
a  picture or other labels can be placed. When a  label is  displayed, nested objects
scroll continuously from right to left.
To insert a  label select the Element – Marquee command.
Labels can be resized. To do this, select a label and move its marker with the
mouse.
Labels can be placed in  a text and a  table.

26.20.1.5. Hyperlink
HTML documents support creation of links for hypertexts.
Select a  text or a  picture object and go to Element – Link. The  link creation dialog
box appears on the screen (see fig. 397).
Specify the following in  the URL attribute:
„„ hyperlink path;
„„ reference to help information about the configuration object;
„„ reference to the system help section. If Managed application is  selected as the
configuration editing mode, only help sections associated with managed appli-
cations are displayed (along with the column that describes availability of these
sections in the web client). If Managed application and ordinary application
is  selected as the configuration editing mode, all help sections are displayed
with information about their availability in  managed applications, web clients
and ordinary applications;
„„ tab name (preceded by the "#" character).
2-1020 1C:Enterprise 8.3. Developer Guide

Fig. 397.  Insertion of Hyperlink

To create the link click OK.

The selected object can be formatted in  compliance with the style of the hyperlink.
It  is  usually blue underlined text. Picture is  placed inside a  blue border.

26.20.1.6. Bookmark
You can create bookmarks for internal references within the current HTML docu-
ment. To do this, select a  text or picture object and go to Elements  – Bookmark.
Dialog box for bookmark name entry appears on the screen. The  selected object
is  not formatted now.
Bookmarks are used to organize internal links.

26.20.1.7. Line
Lines can help organize a  document visually.

26.20.2. Editing in  HTML Format

Features of the HTML document editor listed on the Edit tab are limited. In  the
Text tab, the developer can edit the document directly in  the HTML code.
Please remember that manual encoding changes using the charset attribute of
the META tag do not affect editor behavior. When you save an HTML document,
Chapter 26. Development Tools 2-1021

it is encoded using UTF-8 with the unchanged charset tag, which is set to
UTF-8 when the document is  read.

26.20.3. Viewing Results

To view the final HTML document switch to the Preview tab and check the layout
and behavior of document objects.

26.21. LOCALIZATION OF CONFIGURATIONS

Localization of configurations means translating the 1C:Enterprise system strings
to languages specified in  the Common  – Languages branch of the configuration
tree. Strings can include names of interface objects, names (synonyms) of objects,
help content, module texts, etc.
The most difficult part of this work is  finding the places where the text is  to be
entered in the required language. Therefore, it is convenient to use this mode
even when only one language is  selected.
To start searching use the Edit – Edit interface texts command.
The following dialog box is  displayed:

Fig. 398.  Edit Interface Text

On the Configurations tab, you can select configuration objects for editing interface
texts.
2-1022 1C:Enterprise 8.3. Developer Guide

The configuration list includes all open configuration windows (in addition to the
main configuration, these can include database configuration, configuration files,
repository configuration and vendor configuration).
You can select Entire configuration to create a full list of configuration objects
containing interface properties. You can perform search only for specific objects if
you select this object in  the combo box.
Use the Files tab to select text and spreadsheet documents as well as external data
processor stored in  files.

Fig. 399.  Set Up Search in  Files

Check the Search in  NStr functions in  modules option on the Modules tab if you
need to determine where the NStr() operator is  used in  modules.
To remember the search parameters (the list of configuration objects, files and open
documents), specify a  name for the current settings in  the Search domain attribute.
When you reopen the search window, you just have to select the area you need
from the list and perform your search.
Select the objects you need and click Find. The  following window is  displayed:

Fig. 400.  Search Results Window

The window contains a  table box. The  first column of this box shows the location
of the found text. Other columns are usually used for other languages. The  table
Chapter 26. Development Tools 2-1023

box can have more columns than the number of languages specified. Additional
columns appear when new Language objects are created in the configuration
process and then they are deleted or their language code is changed (when the
language code is  deleted or changed, the Designer does not reset the interface text
for these languages).
Table box content is  sorted by the contents of one of the columns. Click a  column
header to change the sort order. Clicking the header again changes the sort direction.
Text can be edited directly in cells. To do so, select a cell and press Enter.
Text box opens in  the edit mode. Enter the text you want and press Enter again.
The  modified text is  shown in  red.
For quick access to the interface text for a  specific object, double-click the required
line in  the Arrange column. A form with this text is  displayed. You can also view
and replace the found text in the properties palette. If text has been modified
outside the editing window, you can refresh the table box.
Above the table box, there are controls for performing various actions and window
setup.
Use the Collapse combo box to specify the text collapse mode for different
languages. If this option is set to None, the text is not collapsed. If this option
is set to Matching in  sort language, all items with the same text in a sorting
column are collapsed. The  first column contains the group mark (+) which can be
used to expand the group. The  first column also contains the <Prefixes: N> text
(where N is  the number of item occurrences). If other columns of this group have
different text values, cells in  these columns contain <Different values> text.
If this option is  set to Matching in  all languages, all items with the same text are
collapsed.
You can perform mass replacement for text in  collapsed rows. To do so, enter this
text into a  cell for the appropriate language as if it  were one string. This  text will
replace the text in  all rows of a  group.
Use Actions – New search to open the setup window for configuration sections to
be searched.
Use Actions – Copy texts to copy all texts in  one language to a  different language.
It  is  recommended to use this operation only when words and phrases in  different
languages are similar to each other.
Actions – Clear texts clears all texts in  the selected language.
Use Actions – Fill texts to translate synonyms, headers, tooltips and interface texts
quickly using a matching file. This represents a spreadsheet document with
several columns (according to the number of languages used).
The first row of each column contains a  language code (for example, en or de).
Other rows contain matching samples. There are no requirements to sorting
(ordering) rows. Rows can be duplicated.
2-1024 1C:Enterprise 8.3. Developer Guide

Fig. 401.  Filling Texts

After selecting the matching file specify the default language (By language) and the
languages of the translation (To languages). Setting the Only fill unfilled check box
locks rewriting already localized rows.
Select the key language and languages for filling from the languages discovered
during the interface text search. All languages selected for filling must be specified
in  the matching file (it must contain columns with headings corresponding to the
codes of these languages).
NOTE
If you see rows in  only one language when you open the Edit interface texts win-
dow, the Fill texts command becomes unavailable.
Fill interface texts by pressing OK. Texts are filled not only performing a  check
for matching to the language used as a  basis for the loading, but for matching to all
languages available in  the text matching file.
This allows you to insert different rows in  one language as a  match to identical
rows in  another language. You can create a  secondary language in  the bilingual
configuration to comment on the interface texts and provide different comments
to homonyms in  the default language. For example, two Account strings can have
different comments: financial term and user account. Then, when the interface texts
are filled from a  file, you can match them with different words.
Use the Actions – Export to spreadsheet command to move the contents of a  table
box to a spreadsheet document. When you execute this command, only unique
rows are displayed.
Use the Actions – Settings command to set up a  table box view and editor opening
mode for mass replacement.
Chapter 26. Development Tools 2-1025

Fig. 402.  Interface Text Editing Window Options

The Button position group is  used to select a  mode for column placement:
„„ Horizontally – as shown on fig. 401.
„„ Combined – columns are placed one below the other.
„„ Combined, with selection of sort language – this option places columns as
follows: to the right of the Arrange column you will see the column with the
current language of sorting and further to the right there will be columns with
other languages. When you click the header of a column, the list is sorted
by this column and it  is  moved to the left of the Arrange column. A column
for sorting replaces the selected column. If there are only two languages, the
columns will simply change places.
If the Show as tree on collapse option is  checked, you can access collapsed rows
and collapsed groups are shown as a  tree.
It is  recommended not to check the Open editors on change option if there are
many entries.
If the Show edited strings in  contrasting color option is  checked, the text in  modi-
fied rows is  shown in  another color.

26.22. CENTRALIZED CONFIGURATION CHECK

To perform the configuration check select Configuration  – Check configuration.
The  following window is  displayed (see fig. 403).
Let's review how configuration is  validated in  more detail. Any application code
in  1C:Enterprise is  executed in  an environment. This  environment is  character-
ized by a  certain set of defined preprocessor instructions (see page 1-159) and a  set
of available objects. Respectively, when the configuration is  checked, the Designer
defines preprocessor instructions for every checked item and performs a  valida-
tion. Note that if a  client application is  checked in  the client/server version, all
application code is  checked on the client side, and only common modules available
from the client application are checked on the server side.
2-1026 1C:Enterprise 8.3. Developer Guide

Fig. 403.  Check Configuration

Since there are quite a lot of operating modes, validations are divided into two
groups:
„„ A group of validations available for forced and automatic check when the
configuration is edited. These modes are available for selection in the
Modules – Check settings configuration dialog of the Designer (see page 1-159).
„„ The whole list of validations that can be called for a  central configuration check
(described mode).
Further, we describe which preprocessor instructions will be defined for every
validation mode, mode specifics (if any) and validation modes that are not related
to determination of the environment of the executed source code.
General Options

Verifying configuration integrity and consistency

It is a standard check (typically performed before updating the database).
This  check deletes incorrect data that could have been added to the configura-
tion after the previous versions of the system were edited.
Chapter 26. Development Tools 2-1027

Find unresolved references

It searches for references to deleted objects. It is performed for the entire
configuration, including forms, templates, interfaces, etc. Logically incorrect
references are also detected.
Module syntax check

Thin Client
It checks the module compilation while checking the thin client environment
in  the managed application mode (executed in  the file mode).
Web Client
It checks the module compilation while checking the web client environment
in  the managed application mode (executed in  the file mode).
Server
It checks the module compilation in the 1C:Enterprise server environment
check mode. The  following preprocessor instructions are defined: Server.
External connection
It checks the module compilation in  the external connection environment check
mode (executed in  the file mode version). The  following preprocessor instruc-
tions are defined: ExternalConnection.
External connection (client/server mode)
It checks the module compilation in  the external connection environment check
mode (executed in  the client/server mode).
Mobile application - client
Module compilation is  checked in  the environment check mode for the client
application running on the mobile platform.
The following preprocessor instructions are defined: Client, AtClient,
MobileAppClient.

Mobile application - server

Module compilation is  checked in  the environment check mode for the client
application running on the mobile platform.
The following preprocessor instructions are defined: Server, AtServer,
MobileAppServer.

Thick client (managed application)

It checks the module compilation in the managed client environment check
mode (executed in  the file mode).
2-1028 1C:Enterprise 8.3. Developer Guide

If the Use ordinary forms in  managed application configuration property is  set
to False ordinary form modules are not checked when this test is selected.
The  following preprocessor instructions are defined: Client, ThickClientMa-
nagedApplication, Server.
Thick client (managed application, client/server mode)
It checks the module compilation in the managed client environment check
mode (executed in  the client/server mode).
If the Use ordinary forms in  managed application configuration property is  set
to False ordinary form modules are not checked when this test is selected.
The  following preprocessor instructions are defined: Client, ThickClientMa-
nagedApplication.
Modules shipped without source texts
If the configuration distribution settings for some modules specify transfer
without source texts, it  checks whether module images can be generated.
Logical module check

Search for unused procedures and functions

It searches for local (non-exported) procedures and functions with no refer-
ences. Unused event handlers are also detected.
Form module procedure or function is  considered used if its name can be found
in  "ProcedureName" (including double quotes), i.e. if it is a parameter for
a  method, e.g., assignment of handler for an event.
Check assigned handlers availability
It checks availability of event handlers for interface, form, control and flowchart
items.
Search for empty handlers
It searches for assigned event handlers that perform no actions. If available,
such handlers can reduce the system performance.
Extended check
For a  restricted set of types, calls of object methods and properties are checked
"over the period". Parameters set by the string are also checked for correctness
for a  restricted set of methods.
Search for methods that open modal windows
This checkbox is only available if extended configuration check is enabled.
In this mode Designer looks for methods to open modal dialog windows
in  modules. The  Modality usage mode configuration property does not affect
the check mechanism. If you select this checkbox, errors are generated even
if the Modality usage mode property is  set to Use or Use with warnings.
Chapter 26. Development Tools 2-1029

Mobile application checkup

Search for unsupported functionality

In this mode, check reveals the following:
„„ Configuration objects that are not implemented for the mobile platform
in  the applied solution;
„„ Exchange plans with their Distributed Infobase property selected in the
applied solution;
„„ Configuration objects that are not supported by the mobile platform:
○○ In Type properties of object configuration attributes, constants, session
parameters;
○○ In the Command parameter type property of the Command object;
○○ In the Type property of attributes and form attribute columns.
„„ Non-managed forms;
„„ Form items that are not supported by the mobile platform. This check
is only performed for forms that are intended for use on mobile devices
(this is  specified in  the Use purposes form property).
„„ Multiple forms on the start page.
You can save the specified settings for further use. To save the settings, specify
their name in  the Verification options field. To use previously saved settings,
select their name in  this field.
All error messages are displayed in  the message window.
To interrupt configuration check use Ctrl + Break shortcut.
NOTE
In the initial check stage interruption can be processed with delay.
When configuration connected to the repository is checked, it is recom-
mended to lock the configuration root object in  order to avoid errors related to
metadata information.
If the Edit configuration for startup modes parameter (see page 2-1148) is  set
to Managed application and ordinary application, the following parameters are
added to the dialog box:
„„ Thick client (ordinary application)
„„ Thick client (ordinary application, client-server variant)
2-1030 1C:Enterprise 8.3. Developer Guide

In this case the dialog box looks like the following:

Fig. 404.  Check Configuration

Below is  description of these tests.

Thick Client (Ordinary Application)
It checks the module compilation in  the client application environment check
mode (executed in  the file mode).
If the Use managed forms in  ordinary application configuration property is  set
to False, managed form and command modules are not checked when this test
is  selected. The  form module specified in  the Default Constants Form property
is  tested at the time this test is  selected regardless of the Use managed forms
in  ordinary application property value.
The following preprocessor instructions are defined: Client, ThickClientMa-
nagedApplication.

Thick Client (Ordinary Application, Client/Server)

It checks the module compilation in  the client application environment check
mode (executed in  the client/server mode).
Chapter 26. Development Tools 2-1031

If the Use managed forms in  ordinary application configuration property is  set
to False, managed form and command modules are not checked when this test
is  selected. The  form module specified in  the Default Constants Form property
is  tested at the time this test is  selected regardless of the Use managed forms
in  ordinary application property value.
The following preprocessor instructions are defined: Client, ThickClientMa-
nagedApplication, Server.

26.23. USABILITY ANALYSIS FOR OPERATION OF SOLUTIONS

BASED ON 1C:ENTERPRISE PLATFORM
Launching a  client application with the /logui command line key creates logui.txt
file in  the application file folder %APPDATA%\1C\1Cv82\<Unique IB Identifier> on
the user machine. This  file registers all interactive user actions (pressing keys or
clicking the mouse).
Example:
"19.06.2008 16:22:49","Event FormActivate","Name
Document.GoodsReceipt.Form.ListForm","t=0"
"19.06.2008 16:22:49","Event FormActivate","Name
Document.GoodsReceipt.Form.ListForm","t=0"
"19.06.2008 16:22:49","Event LClick","Form
AccumulationRegister.Settlements.Form.CurrentSettlements",
"Type TableBox","t=0","beg"

Interactive actions are recorded for thick and thin clients and are not recorded for
web clients.
For details on logui.txt file format see "1C:Enterprise 8.3. Administrator Guide".
2-1032 1C:Enterprise 8.3. Developer Guide
Chapter  27

DEBUGGING AND TESTING OF

APPLICATION SOLUTIONS

Debugging is  a step in  the application solution development process. It  involves
finding, isolating and eliminating application errors.
Debugging can include using a  debugger (see page 2-1033), performance meas-
urement results (see page 2-1052), output of server calls (see page 2-1057) and
limitation of delays for server calls (see page 2-1057). You can also run the auto-
mated testing scenario (see page 2-1060).
This chapter describes platform tools that can be used for application debugging
and testing.

27.1. DEBUGGER
Debugger is  a tool that facilitates program module development and debugging
in  1C:Enterprise. Debugger has the following features:
„„ debug module execution (in both file mode and client/server modes) and back-
ground jobs. Client modules of web clients cannot be debugged;
„„ execute module step-by-step;
„„ set breakpoints;
„„ interrupt and resume module execution;
„„ debug multiple modules at once;
„„ calculate expressions for variable status analysis;
„„ view procedure and function call stack;
„„ abort upon error;
„„ edit module during debugging.
2-1034 1C:Enterprise 8.3. Developer Guide

Debugger uses debug items. A debug item is 1C:Enterprise script context with
a  set of parameters:
„„ name of the user executing 1C:Enterprise script code;
„„ debug item type;
„„ name of the machine used to execute 1C:Enterprise script code;
„„ number of the used session;
„„ number of the IP port used by the debugger to control the debug item.
NOTE
In the client/server version, if there are multiple workflows in  a cluster and
a  session was redirected to another workflow in  the process of debugging web
client or server code, debugging is  impossible. For details on sessions, see the
"1C:Enterprise 8.3. Client/Server. Administrator Guide".
Debug items can have the following types:
„„ Thin client – 1C:Enterprise script code executed at the thin client;
„„ Server – 1C:Enterprise script code executed on the server;
„„ Server (file mode version) – 1C:Enterprise script code executed on the server
in  file mode version;
„„ COM-connection – 1C:Enterprise script code executed through an external
connection;
„„ Web-service – 1C:Enterprise script code that handles Web-service method
calls;
„„ Background job – 1C:Enterprise script code that handles background jobs;
„„ Thick client – 1C:Enterprise script code executed at the thick client;

27.1.1. Debugger Use

To debug 1C:Enterprise script code you should run the application that executes the
code in  the debug mode.
IMPORTANT!
Debug mode requires TCP/IP support enabled on the computer. You can enable
TCP/IP in  the corresponding network connection settings.
If 1C:Enterprise is  not launched, select Debug  – Start Debugging. The  Designer
will start 1C:Enterprise up in  the debug mode.
If debug mode is enabled or debugging is set to begin upon startup in the
Designer settings (you can open them by selecting Tools – Options and opening the
1C:Enterprise startup tab; see page 2-1154), you can launch debugging in  the run
mode by selecting Tools – 1C:Enterprise. If you need to debug the code executed
by a  specific user, you can specify the user who launches the debug mode in  the
settings form.
Chapter 27. Debugging and Testing of Application Solutions 2-1035

The debugger and debug items use IP-address 127.0.0.1 when they search for each
other.
To ensure stable operation of data transport service map address 127.0.0.1
to symbolic name localhost. The following mapping can be written to the file
C:\Windows\system32\drivers\etc\hosts:
127.0.0.1 localhost

DNS-server is  used when computer name specified in  the Debugging Items dialog
box and used to search for debug items is not represented as an IP-address or
when debugger specified in XML files for debug settings of COM-connections
and Web services is  not represented as an IP-address. In  other words, debugger
URL is  used for COM-connections and Web services as it  is  written in  the file.
If computer name is  written instead of IP-address, DNS-server is  still called.
To enable debugging you need to enable 1560  – 1591 port range (default) on
the computer where the Designer is installed and on computers where debug-
ging objects being used are located. If another port range is selected using the
debugcfg.xml file (see page 2-1042), you need to allow usage of the new port range.
Moreover, this port range should be specified on all computers where debugging
objects are located (except server debugging objects that use the port range set
in  the 1C:Enterprise server configuration).
If ports required for the debugger are not permitted to be used on the computer
where Designer is  installed, debugging is  not available on that computer and the
following may occur:
„„ Starting time of the client application increases.
„„ 1C:Enterprise server workflow slows down, if the server uses the debugging
mode (-debug switch).

27.1.1.1. Application Setup for Debug Mode

Debugging Client Application
You can use the following launch startup options to enter the debug mode:
„„ In the Designer mode, on the Tools  menu, click Options, click 1C:Enterprise
startup tab, click Additional tab, and select the Enable debugging mode check
box. Then attach the debug item. You can also check the Begin debugging on
startup check box to attach the debug item automatically upon 1C:Enterprise
startup.
„„ Open the infobase in  the 1C:Enterprise mode by using the -debug command
line key (debug mode).
„„ If a client application is running, open the settings form (select Tools  –
Options) and set the debug mode (check the Enable debugging mode check
2-1036 1C:Enterprise 8.3. Developer Guide

box). Please keep in  mind that you cannot uncheck this check box after you
apply the settings.
„„ If the 1C:Enterprise mode is  launched and you need to enable debugging for
the next launch, open the settings form (select Tools – Options), and check the
Allow Debug debugging on startup check box.

Debugging Code on Server

In the debugging mode configuration objects are loaded when needed rather
than upon system startup as in the standard server operation mode. It makes
1C:Enterprise startup faster in  case of configuration changes, i.e. accelerates the
development process.
Please note that system performance in  the debug mode is  lower than in  standard
operation conditions. Therefore, it  is  not recommended to use server debug mode
for real user operations.
For location and configuration of srv1cv83 configuration file and for more details
on 1C:Enterprise startup command line parameters, see the "1С:Enterprise 8.3.
Сlient/Server. Administrator Guide".
The Server as an Application
If the 1C:Enterprise server is operating in an application mode (any OS),
you should stop the server and restart it  to include the -debug parameter in  the
command line parameters.
ragent -debug <other command line parameters>

The Server as a  Windows service

If a  server is  running as a  Windows service, do the following:
1. Stop the 1C:Enterprise server.
ragent –stop

2. Re-register a  server agent as a  Windows service to include the -debug param-

eter in  a list of ragent command parameters.
ragent -instsrvc -debug <other command line parameters>

3. Launch the 1C:Enterprise server.

ragent -start
Chapter 27. Debugging and Testing of Application Solutions 2-1037

The Server as a  Linux daemon

If you need to transfer a  1C:Enterprise server that is  working as a  Linux daemon
in  the debug mode, do the following:
1. Stop the 1C:Enterprise server.
/etc/init.d/srv1cv83 stop

2. Set the SRV1CV8_DEBUG parameter to 1 in  the srv1cv83 configuration file.

SRV1CV8_DEBUG=1

3. Save the configuration file.

4. Start the 1C:Enterprise server.
/etc/init.d/srv1cv83 start

Debugging External Connection

To enable debug mode for an external connection use the settings in XML file
comcntrcfg.xml that should be located in  conf subdirectory of the 1C:Enterprise setup
directory. If the file cannot be found, the application runs in  the standard mode.
Sample comcntrcfg.xml:
<config xmlns="http://v8.1c.ru/v8/comcntrcfg">
<debugconfig debug="true" debuggerURL="tcp://localhost:1560"/>
</config>

For details on comcntrcfg.xml file see "1C:Enterprise 8.3. Administrator Guide".

If the url attribute is  specified for the debug item, the Designer should be available
at the specified URL when the external connection is  accessed. Otherwise, external
connection will be paused and the system will wait until the Designer becomes
available. You need to connect the required debugging object to continue working
in  the Designer.
Debugging Web Service
To instruct a  web service to start in  the debugging mode (only for a  file mode
infobase), you must use settings in the default.vrd file, which should be located
in  a virtual application directory. You need to specify the debug item in  this file,
otherwise,the web service can't be debugged if this item is  not present.
Example of the "debug" item from the default.vrd file:
<debug enable="true" url="tcp://localhost"/>

For more details on the default.vrd file, see the "1С:Enterprise 8.3. Administrator
Guide".
2-1038 1C:Enterprise 8.3. Developer Guide

If the url attribute is  specified for the debug item, the Designer should be available
at the specified URL when the web service is  accessed. Otherwise, the web service
will be paused and the system will wait until the Designer becomes available. You
will need to connect the required debugging object to continue working in the
Designer.
If you need to debug a  web service in  the client/server version of an infobase, you
should enable the debugging mode on the server using the debug command line
switch. For more details on 1C:Enterprise startup command line switches, see the
"1С:Enterprise 8.3. Сlient/Server. Administrator Guide".

Debugging Web Client

You can use the following launch options to enter the debug mode:
„„ In the Designer mode, in the settings form (open with Tools  – Options) on
1C:Enterprise startup – Additional, check the Enable debugging mode checkbox
and then connect the debugged object. Also, you can check Begin debugging on
startup, in  this case connection is  performed automatically when you launch
1C:Enterprise.
„„ Open the infobase in  the 1C:Enterprise mode by using the debug command line
key (debug mode).
http://localhost/demo?debug

„„ Open the infobase in the 1C:Enterprise mode by using the debug and
debuggerurl="ip address" command line key.
http://localhost/demo?debug&debuggerurl="127.0.0.1"

ip address is the debugger address. In  this case the debugger at 127.0.0.1 auto-
matically connects debugging objects (the debugger should have started at the
specified address).
If you need to enable debugging of the server side file mode version, you can use
two methods:
„„ Start debugging directly in  the Designer as described above. In  this case the
debugging mode for the server side of the file mode infobase version located on
the web client computer is  enabled automatically.
„„ Enable the debugging mode using the default.vrd file that should be located in  a
virtual application directory. You need to specify the debug item in  this file,
otherwise if this item is  not present, the web service can't be debugged.
Example of the "debug" item from the default.vrd file:
<debug enable="true" url="tcp://192.168.0.30"/>
Chapter 27. Debugging and Testing of Application Solutions 2-1039

You should also consider the fact that system performance is slower in the
debugging mode than in  the normal mode. So it  is  not recommended to use
the debugging mode of the file mode server side in  real user experience.
For more details on the default.vrd file, see the "1С:Enterprise 8.3. Administrator
Guide".
Note the following when debugging a  web client:
„„ The ability to interactively enable the debugging mode is  not supported.
„„ Automatic search of debugging objects on remote computers is  not supported
when you are debugging a  web client for a  file mode infobase.
„„ Activating the Designer from a  debugged web client is  not supported.
„„ Debugging external reports and processes is  not supported.
IMPORTANT!
To debug a web client (including client application code) in the client/server
version, the 1C:Enterprise server should be started in  the debug mode (the debug
switch).
NOTE
It is  not recommended to debug a  web client in  low-speed communication chan-
nels.

27.1.1.2. Attach Debug Items

To debug a  module the debug item should be attached for debugging.
To manage attachment select the Debug  – Attach for Debugging menu item.
The  debug item selection dialog will open. The  list contains only items that belong
to the infobase being debugged and have debugging enabled. The  list includes only
those debugging items for which the following conditions are true:
„„ Infobase connection string for the Designer and the debugging item exactly
matches with options describing the infobase location (the File option for the
file mode version and the Srvr and Ref options for the client/server version),
including text case.
Examples of non-matching connections strings:
// network drive R: is  connected to folder \\Server\database,
// At that, the following addresses are not the same from the
// points of the debugger view:
File=\\Server\database\mybase;
File=R:\mybase;
// computer db_server has ip-address 192.168.1.1,
// At that, the following addresses are not the same from the
// points of the debugger view
Srvr=db_server;Ref=my_db;
Srvr=192.168.1.1;Ref=my_db;
2-1040 1C:Enterprise 8.3. Developer Guide

„„ Debugging should be enabled in  the application (for a  server – the debug flag,
for a  client application – the corresponding command line switch or a  client
application settings dialog flag or a  correctly configured configuration file).
Debugging items are available for connection during the session within which
a specific background job, web service or external connection is working.
This  interval can be very short and in  this case you can use automatic configura-
tion of the debugging items connection.
NOTE
When a  debugging item is  connected, the infobase user list should include users
on behalf of which authorization was performed both in  the Designer and in  the
debugging item.
Usually the list contains one line that refers to the configuration running in the
1C:Enterprise mode. If several 1C:Enterprise applications are running with this
configuration, the list may contain several lines.

Fig. 405.  Attach Debug Items

If the Search for debugging items on remote computer check box is  selected, enter
computer name or network address in  the box to the right of the check box or select
it  from the list of previously entered names. The  debug items found on the remote
computer will be added to the available debug items list. The  list of attached debug
items contains the items already attached to the debugger.
To connect the selected debug item to the debugger, press Attach. In  the attach-
ment window, the debug item is  moved from the available to the attached list.
To exclude debug item, select it  in  the list of attached items and press Detach.
In the attachment window, the debug item is moved from the attached to the
available list and you can attach it  once again. At that moment, breakpoints set
in  detached debug items do not function when execution passes through them.
To close a  debug item press Break. To break execution press Stop.
Chapter 27. Debugging and Testing of Application Solutions 2-1041

To open range setup dialog box press Options. The  range defines limits where the
debugger searches for debug items on the current or specified remote computer.

Fig. 406.  Debugger Settings

The Debugger field of the dialog box contains settings for the current debugger.
You can use them, for example, in  command line during client application startup
as the /debuggerURL command line key parameter or in  an XML file containing
debug settings for external connection or Web-service.
To set auto-attachment for debug items on the 1C:Enterprise server running in  the
debug mode, use the Autoattach dialog box and select the required debug item
types.

Fig. 407.  Auto-attachment Settings

Auto-connection of a  background job run by the client application or web server

extension is  not managed in  this dialog. Background jobs can only be debugged if
certain conditions are met:
„„ For the thin or thick client:
○○ Allow debugging in  client application;
○○ Allow auto-connection to background jobs in  the auto-connection settings
dialog.
„„ For the web server:
○○ Allow debugging for debugged infobase in  the publication file (default.vrd);
○○ Allow auto-connection to background jobs in  the auto-connection settings
dialog.
2-1042 1C:Enterprise 8.3. Developer Guide

27.1.1.3. Additional Port Range Settings

If all ports for connection within the standard range are busy, you can specify
additional range. This range is configured in the debugcfg.xml file, which
should be located in the configuration files directory on the computer where
the Designer and debugged client application are located or where an external
connection is performed. If a port range is changed on the computer with the
debugged application, these ports should be set for the Designer where debugging
takes place (if the debugged application and the Designer are located on different
computers). If the file cannot be found, you can use ports from the standard range
(i.e. 1560:1591) for debugging. Debug items on the server use the same ports that
the server processes do: rmngr and rphost. It  is  not necessary to specify additional
port ranges for debug items on the server.
Example:
<config xmlns="http://v8.1c.ru/v8/debugcfg">
<debugports range="1540:1550"/>
</config>

For details on debugcfg.xml file see "1C:Enterprise 8.3. Administrator Guide".

27.1.2. Breakpoint
A breakpoint is a place in the program module where module execution stops
and control passes to the debugger.
The current breakpoint, break locations and breakpoint statuses are shown in  the
left column of the module text, with special marks.

Fig. 408.  Breakpoint Types

A breakpoint can be set on any line of the module at any time working with the
debugger. If the line with a  breakpoint does not contain any operators (e.g., is  an
empty line), contains non-executable text (e.g., procedure or function header,
variable declaration, etc.) or continues an operator that begins on previous lines,
Chapter 27. Debugging and Testing of Application Solutions 2-1043

breakpoint location is  automatically adjusted. Breakpoint location is  marked with
a  special character in  the left column of the module window. Different characters
are used for enabled and disabled breakpoints (see fig. 408).
The mouse can also be used to set or remove breakpoints. To do this, double-click
in  the grey margin next to the line where you want to set the breakpoint.
Use the following commands on the Debug menu of the Designer (see table below)
to manage breakpoints.
Command Details
Breakpoint Set or remove a  breakpoint on the line where the cursor is  located
Conditional Breakpoint Set a  breakpoint and open the dialog box for break condition entry (a logical
expression). If the condition has been entered, the command opens the
dialog box for condition editing. If a  breakpoint has been set on this line, the
command opens the dialog box for breakpoint condition entry. Execution stops
at the specified breakpoint only if the condition is  satisfied
Toggle Breakpoint Off Toggle breakpoint on/off. The  command is  available if the current line has
a  breakpoint
Clear All Breakpoints Delete all previously set breakpoints in  all modules
Disable All Breakpoints Disable all previously set breakpoints in  all modules without deleting them
Breakpoint List View and manage breakpoints
Stop on Errors When an error is  found, the debugger stops execution and moves to the
module line that has caused the error

Set breakpoints are saved when the configuration is closed. To view the list of
breakpoints open the configuration and use the Debug – Breakpoint List command.

Fig. 409.  Breakpoint List

Use check boxes in  the On/Off column to manage the breakpoint state. If the check
box is  selected, the debugger stops execution at the breakpoint.
For description of other buttons see fig. 409.
2-1044 1C:Enterprise 8.3. Developer Guide

27.1.3. Step-by-Step Execution

In the step-by-step execution mode, the debug item completes each command and
waits for a  debugger command to continue execution.
When the first debug item is attached, the system adds debug management
commands to the Debug menu.
There are several options for each step of module execution. Use the following
commands from the Debug menu to select an option.
Command Details
Step In If the next executable module operator calls a  function or a  procedure,
it  is  executed in  step-by-step mode; otherwise the debugger moves to the next
operator
Step Over If the next executable module operator calls a  function or a  procedure,
it  is  executed completely (instead of step-by-step) and then the debugger
moves to the next operator
Step Out Break the step-by-step execution of a  function or a  procedure and stop at the
first operator after its call
Go to Cursor Break the step-by-step execution, execute all operators up to the cursor position
Continue Debugging Break the step-by-step module execution and continue free execution

When applications are debugged, you need to remember the following: if the
Execute() operator is  used in  the debugged code, then:
„„ Step-by-step execution of the code passed as an operator parameter (including
procedure and function calls) is  not supported.
„„ Interruption of the program code is supported using breakpoints inside
procedures and functions called from the code, which was transfered as the
Execute() operator.
If you debug multiple debug items, you should remember about some step-by-step
execution features:
„„ if you stop a  debug item, other debug items are also stopped when you execute
the code;
„„ if you select Continue, it  results in  resuming execution of all debug items;
„„ if you select Step Over, it results in stepping to the next line for all debug
items;
„„ if you select Step In (if the executable module operator calls a function or
a  procedure), it  results in  stepping to the first operator in  the call, while Step
Over command is  performed for other debug items.
If you debug the client/server mode and the code is  sequentially executed on the
client and the server (client and server debug items are attached), then:
„„ if you select Step In (if the executable module operator calls a function or
a procedure on the server), it results in stepping to the first operator in the
call;
Chapter 27. Debugging and Testing of Application Solutions 2-1045

„„ if you select Step Out or Step Over for the last executable operator (if the
executable module operator calls a function or a procedure executed on the
server and called from the module executed in  the client application), it  results
in  stepping to the next executable operator in  the call.
The current debug item can be selected in  a special Debug Items toolbar. It  has
a  single combo box that displays the current debug item. The  box is  only acces-
sible when the debugger controls one of the attached debug items (e.g., after
a breakpoint is activated). The list of debug items only contains items that are
currently controlled by the debugger, including the current debug item.
Use the immediate window and the Expression dialog box to get values for the
relevant expressions. You may use the Call Stack to trace the sequence of proce-
dures and functions.
If you use step-by-step execution, the call stack and variable values (in the imme-
diate window and the Expression dialog box) are displayed for the current debug
item. When you change the debug item, it  also changes the call stack and variable
values.
IMPORTANT!
If you attach the client and server debug items and move from the client to the
server, no calculations are performed at the client levels of the call stack. These
levels are highlighted in  grey in  the call stack window.
If you need to continue module execution, select Debug  – Continue Debugging
to enable free module execution for the attached debug items (up to the next
breakpoint). If a  client application is  attached for debugging, it  is  activated auto-
matically.
If you want to end the entire debugging process (except background jobs), remove
all breakpoints from all modules and run the Debug  – Continue Debugging
command if a  breakpoint has been activated. If you need to abort debugging and
terminate the attached debug items, select Debug – Break. In  the latter case Befo-
reExit() and OnExit() procedures are not executed.
You can edit the current configuration and save changes during debugging.
IMPORTANT!
Although a  debugged module may be edited, the debugger does not compile the
modified code and debugging is  continued for the database configuration code
(that existed at the moment when the debugger was launched or when the connec-
tion was opened). To debug changes made to the configuration you should update
the database configuration.
If you set the exclusive mode in  the 1C:Enterprise mode, you will not be able to
save the current configuration until the exclusive mode is  removed.
If a file mode infobase is executed step-by-step in 1C:Enterprise or it is in a
breakpoint and there is an open transaction (explicit or implicit), some oper-
2-1046 1C:Enterprise 8.3. Developer Guide

ations (e.g., an attempt to lock objects in configuration storage) can cause an

error: Configuration repository operation failed. (Information collection error for
configuration storage) Lock conflict during transaction. Couldn't lock table FILES.
We recommend shutting client applications down before retrying. To perform the
operation that caused an error, you should continue 1C:Enterprise script execution
until the transaction is  completed.
For a  table of shortcuts for the debugger see the Help menu.

27.1.4. Debugging External Data Processors (Reports)

To debug external data processor (report) modules you have to open the external
data processor file in  the Designer using the File – Open command.
Then you may work with external data processor (report) modules in  the same way
as with any other modules.

27.1.5. Debug Management

Use the Debug  – Restart command to stop configuration execution and restart
it  in  the 1C:Enterprise mode. If the configuration has been modified, the program
asks the user whether the database configuration should be updated.
The Debug – Break command aborts debugging and terminates current debug item.
The Debug  – Stop command stops module execution on the current operator.
This command allows you to start module debugging from the next executable
line. This  command is  useful for module "cycling" analysis.
The Debug – Stop on Errors command opens the dialog box to set up the Stop on
Error procedure.
The Stop on Errors check box status indicates whether debugging should stop if
an error occurs during execution. If execution stops on error, the Runtime error
warning appears on the screen with an explanation of the location and cause for this
error.
If the Stop on errors with text only flag is  set, then debugging is  stopped in  the
place of an error occurrence (if the error message contains the substring indicated
in  the table box). If the check box is  not selected, debugging stops on an error irre-
spective of the error message text. At the same time the substring specified is  taken
into account only if you select the check box next to it.
The current execution point for the current debug item is  moved to the location of
the error and the debug item with the error becomes active. You may view expres-
sion and variable values to pinpoint the cause of the error.
Chapter 27. Debugging and Testing of Application Solutions 2-1047

27.1.6. Expression Window

Expressions can be calculated using the Expression window during step-by-step
execution. Use the Debug – Evaluate Expression command to open this window.

Fig. 410.  Evaluate Expression

Enter an expression in the 1C:Enterprise script into the Expression field of this
window. You may enter an expression "manually" or select it  from a  list of previ-
ously entered expressions.
If the cursor in  module window is  placed over an expression or if an expression
is  selected when you open the Expression window, this expression is  automati-
cally entered into the Expression field.
Use the Evaluate button to calculate an expression. The expression evaluation
result is  displayed in  the Value field.
The Add to immediate window button places the expression into the immediate
window. This helps track expression changes during debugging. The expres-
sion is  placed in  a new line of the immediate window. The  immediate window
is  opened if it  has not been opened yet.
If an expression has a  String type or is  a collection of values or an array, the
Show Values in  Separate Window button becomes available.
The Evaluate Expression window is used for a more convenient view of long
lines. This  window contains a  control of Label type that displays the line value for
viewing.
To make it  easier to view a  collection of values or an array, a  window containing
a table box is opened. Columns in this window correspond to attribute names
and rows contain attribute values. The  window also shows the count of items in  a
collection and the first column contains an index of each collection item.
If a  specific value is  also a  collection of values or an array and a  row, you may
view these values in  a separate window (as shown on fig. 411). To do this, select
the required value and select the Show Values in  Separate Window command from
the context menu or press the F2 key.
2-1048 1C:Enterprise 8.3. Developer Guide

Fig. 411.  Display Values

A window with the line expression in  a multi-line field will open. You may copy
this expression to the clipboard.
The contents of the calculation result from the table box can be output to a  text or
spreadsheet document using the Output list button. If the calculated value is  repre-
sented as a  tree, you can only output data from the opened strings of this tree.
You may also view current value of the expression by moving the mouse over it.
The current value is shown as a tooltip near the variable. You may view it if
the value can be represented as text. In  the same way, you may view the property
value. If the property is represented as <Object>.[<Object>. …]<Property>
(Example: FormElements.CommandBar.Buttons.Get.Enabled), you may view
its value by moving the mouse over the text. The  value is  displayed if the text
does not contain parentheses or square brackets. You may also view the value of
the array item that has an index (as a  number or variable with a  value specified at
the moment of viewing). To do this, you need to select the array ID and index.
When you move the mouse over an object or over a  selected object or a  group
of objects in  <Object>.[<Object>. …]<Property> text, its type is  displayed.
For example, if you select FormElements.CommandBar1 in text FormEle-
ments.CommandBar1.Buttons.Get.Enabled, CommandBar type is  shown.
Chapter 27. Debugging and Testing of Application Solutions 2-1049

27.1.7. Immediate Window

Immediate window is a special window that contains calculation results for
variables and formulas that have been entered into it  during debugging. Use the
Debug – Immediate Window command to open it.

Fig. 412.  Immediate Window

An immediate window is a four-page form. Each page of the form contains

a  table box for entering variables and formulas for control. Formulas may include
arithmetical expressions, expressions using 1C:Enterprise script functions and
application module and common module functions.
Each formula is  entered into the first column of the table box and should be located
on a  separate line. The  formula calculation result is  displayed in  the Value column.
Enter the expression type into the Type column. If you have made mistakes when
entering a  formula, the following error message is  displayed: Syntax errors found!
You can control the immediate window and the calculated results using commands
from the context menu.
You may copy calculation results to the clipboard using the Copy Result command
from the context menu of the second column.
Some types of data (see the previous paragraph) can be viewed in  a separate window.
The immediate window can also be output to a  spreadsheet or text document.
If the source data for the expressions change during processing, you must do
a  refresh to obtain valid results. Run the Recalculate or Recalculate All command
from the context menu of the immediate window to perform recalculation.
The immediate window uses two modes for page selection: in  the first mode, the
pages are selected using tabs below; in  the second mode, they are selected using
the context menu. You may select the mode by checking or unchecking the Tabs
option in  the context menu.
To clear the contents of a  line in  the immediate window, select it  and press the
Del key.
The immediate window may be shown in different modes. After debugging the
window automatically closes.
2-1050 1C:Enterprise 8.3. Developer Guide

27.1.8. Call Stack

Call stack contains a sequence of function and procedure calls that leads to the
currently debugged module line.

Fig. 413.  Call Stack

The window shows:

„„ executed method – the Name column
„„ module string number – the Line column
„„ the debugging item where the module is  located – the Item column
The first column of the window can contain two icons:
„„ the yellow arrow indicates a  top of the call stack.
„„ the green arrow (to the left of the CommonForm.CallStack.Form.ServerMethod()
row) indicates a  method in  the context of which variables will be calculated
in the Expression window and the Immediate window. If the top of the stack
matches the current context, the green arrow is  not shown. To change context
(and position the pointer to the row indicated in  the Line column) you need to
double click the required row in  the Call Stack window.
In the example shown in fig. 413, the VariableAtServer variable is set to
AtServer, since the debugger is  switched to the ServerMethod() context (as indi-
cated by the green arrow next to CommonForm.CallStack.Form.ServerMethod().
Chapter 27. Debugging and Testing of Application Solutions 2-1051

If you switch the context to the top of the stack (double click the row with the
yellow arrow), the value of VariableOnServer will be set to Recall, since the
context is  switched.
Some rows in  the Call Stack window are shown in  grey (the last two rows in  fig.
413). This means that you can switch to a module row, but you can't evaluate
expressions in  the context of the called method. Thus those stack items are selected
that are "located" on the client, and the top of the stack is  "located" on the server.

27.1.9. Debugging Protected Modules

If the module line calls a procedure or function that is located in a protected
module (see page 2-956) and you use the Step In  command to move to this proce-
dure or function, the debugger asks you to enter a  password.
If you enter the password correctly, the debugger opens the protected module and
passes control to the first line of the called procedure or function. When you move
to the protected module again in  the same session, you are not asked to enter the
password.
If you decide not to enter the password, the debugger skips the protected code (but
still executes it) and moves to the first line of code following the protected module.
The  same procedure is  followed for the Step Out command.
A call stack always contains the procedure and function names. If the protected
module has not been opened yet, the debugger asks you to enter a  password when
you try to move to the selected procedure for the first time. When you try to move
to the protected module from the call stack again (during the same session) you are
not asked to enter a  password.

27.1.10. Use Options

This section contains a  brief description of typical debugger operation scenarios.

27.1.10.1. 1C:Enterprise Startup in  Debug Mode

To start up 1C:Enterprise in  debug mode select Debug – Start Debugging or press
F5. Type of the client launched in  this case is  defined by the Designer settings (see
page 2-1154) and default configuration run mode (see page 1-165).

27.1.10.2. Connection to Running 1C:Enterprise

To debug a  mechanism in  the running 1C:Enterprise do the following:
„„ Enable debugging in the running 1C:Enterprise instance. To do this, select
the Allow Debugging in  Current Session check box in the parameter setting
window (Main Menu – Tools – Options).
2-1052 1C:Enterprise 8.3. Developer Guide

NOTE
Not available in  a web client.
„„ Define number of the session to be debugged. To do this, enable display of
the All functions command (select the Show "All functions" command check
box in  the parameter setting window). Then open a  list of active users (Main
Menu – All functions – Standard – Active users) and save Session column status
for the selected user (current user). The  list of active users can only be viewed
by users with sufficient access rights.
„„ Then use the Designer to open the infobase to be debugged (for details on
starting up various 1C:Enterprise modes see "1C:Enterprise 8.3. Administrator
Guide").
„„ After this open the debug item attachment window (see page 2-1039) and attach
the debug item with the Session value equaling the Session value in  the list of
active users (see above).
Now, breakpoints get activated in  the attached debug item and program code can
be debugged.

27.2. PERFORMANCE METER

Performance meter can be used to evaluate performance of the entire configura-
tion or its part running within a  debug item of any type. You may measure use
frequency for specific code areas and execution speed, specify code to be executed
on the server or the client and select code lines that have initiated server calls. If
there are several methods of solving a task, you may try all methods and then
select the fastest.
Please remember that you need to perform the comparison in  the same conditions.
For example, if CPU resources are used up by another application during task
execution, this may influence the comparison reliability. Other circumstances may
also influence the comparison results. Therefore, when you compare two methods
of task solution with similar performance, it  is  recommended to perform several
measurements for each method to determine possible variance.
Use the Debug  – Performance Meter command to measure performance. When
you run this command again, the measurement stops and the measurement results
window opens. Enabling and disabling the performance meter affects all debug
items currently attached to the debugger.

27.2.1. Available Options

If you need to measure configuration performance, including the startup section,
first run the Debug – Performance Meter command and then launch 1C:Enterprise.
The  time between the start of measurement and the commencement of work is  not
considered in  the measurement results.
Chapter 27. Debugging and Testing of Application Solutions 2-1053

If you do not want to include the startup section in  the measurement, first launch
1C:Enterprise and prepare it  for execution of the required part. Then switch to the
Designer and turn performance meter on.
If you want to include 1C:Enterprise shutdown section into measurement, you have
to exit 1C:Enterprise and switch to the Designer regardless of the option used to
start the measurement. In  this case you do not have to stop the meter manually.
When measurement results are ready, they are displayed.
If you do not want to include the 1C:Enterprise shutdown section in  the measure-
ment, it  must be finished to view the measurement results. For example, if you
want to analyze the posting procedure for a  document, run 1C:Enterprise, open the
document, fill it  in, switch to the Designer mode, turn the meter on, then switch to
the 1C:Enterprise mode, post the document, switch to the Designer mode and end
the measurement.

27.2.2. Measurement Results

Measurement results contain references to specific module lines that specify the
frequency and length of execution. They are displayed as a table box with the
following columns:
„„ Module – contains the module name;
„„ Line number – module line number;
„„ String – module line text;
„„ Usage count – number of line calls during measurement;
„„ Time (net) – total execution time (in seconds) for this line during measurement;
„„ %(Time) (net) – percentage of the total execution time for this line in  relation to
the total measurement time (total measurement time equals the sum of all time
periods when the configuration code was executed). The  code execution time
on the client is  taken as 100%.

Fig. 414.  Performance Meter Icons

2-1054 1C:Enterprise 8.3. Developer Guide

„„ Client – this icon (see fig. 414) marks code lines executed at the client;
„„ Server – this icon (see fig. 414) marks code lines executed on the server;
„„ Processing by server – these icons mark code lines that initiate server calls:
○○ server was called at the platform level or procedures and functions executed
on the server were called directly (Direct server call on fig. 414);
○○ local call of procedure/function executed on the client where the server call
was executed at the platform level or procedures/functions executed on the
server were called directly (Nested server call on fig. 414).
Execution time for each line in  execution measurement results is  made up of time
of operator line execution (net time) and of procedure (function) call time if they
are in  the line. Use Include execution time for procedure and function calls check
box to select which time to indicate: full time (as a  sum of call time and net time)
or net time of execution.

Fig. 415.  Measurement Result

If the line contains at least one procedure (function) call, execution time contains
operator line execution and procedure (function) call time.
If the check box is  selected, procedure (function) call time is  included in  the full
execution time.
If this check box is  deselected, measurement results include only execution time
for code lines, but not execution time of procedure (function) that is called by
this line. In  this case the total execution time for this line (in Time column) is  not
the same as the actual time spent by the system in processing this line. Please
remember that execution of called procedure (function) may be time-consuming
and this time is  not included in  the result (net time).
The check box is  selected by default and its state is  recorded between sessions.
If the state is  changed, names of time columns are also change.
Chapter 27. Debugging and Testing of Application Solutions 2-1055

If the Client check box is  selected, results of code execution measurement on the
client are displayed.
If the Server check box is  selected, results of code execution measurement on the
server are displayed.
If the Client and Server check boxes are selected, results of code execution meas-
urement on the client and on the server are displayed.
The check boxes are displayed only during server infobase debugging. The  check
boxes are available only during server debug item debugging.
If there are several open windows with performance measurement results, when
you place the mouse pointer onto the results column, you can see a  tooltip with the
URL of the file reflected in  this column.
When you double click the mouse on the column with the performance measure-
ment results, the module editor moves to the appropriate string in  the file with the
performance measurement results.
In addition to the special window, measurement results can also be viewed in  the
module source code window. If a performance meter window is opened in the
debugger, the module windows contain a  column that shows the total number of
calls for the current line and the percentage of its work in  relation to the total time.

Fig. 416.  Measurement Results in  Module Text

Icons are used to indicate code execution on the client or server as well as server
calls (similar to the measurement results window; for a  description see fig. 414).
Double-click a line in the measurement results window to switch to the corre-
sponding line in  module window.
If several measurements are opened at the same time, the module text windows will
contain the corresponding number of columns.
Close the measurement results window to remove the columns with the number of
calls and work time percentage from modules.
2-1056 1C:Enterprise 8.3. Developer Guide

27.2.3. Sorting Measurement Results

Measurement results can be sorted by any column in  the report.
Sorting can be done by clicking on the header of one of the columns. Clicking
Module or Line number sorts the results by line number, Usage count – by the
number of line calls, Time (net) or %(Time) (net) – by work time. If performance
measurement has been performed on both the client and the server, sorting by these
columns is  also available.
27.2.4. Selective Summarization of Measurement Results
Summaries may be useful for the purpose of results analysis. If you mark several
lines in  the results window, their summaries (total number of calls, total working
time in  seconds and percentages) are displayed in  the bottom part of the window.
Use the Include execution time for procedure and function calls check box to select
one of two methods for approximate tracking of nesting levels for summarization. If
the current module has a  line that calls a  procedure and a  line with the procedure
text, then you should not mark both since it  can cause double count of runtime.
If you still have to select them (e.g., when it  would take too much effort to track
these duplicate items), you may uncheck this option to avoid duplicate accounting.
However, if all called procedures are external to the module, it  is  better to turn this
option on. In  this case the total execution time includes execution time of external
procedures providing more accurate results.
27.2.5. Performance Meter in  Client/Server Base Operation
When performance is  measured, results for the 1C:Enterprise script code executed
for the same connection number on both the client and the server are summarized.
In this case the results indicate which code lines have been executed on the
client or the server; which lines have called procedures or functions executed on
the server or have made system calls (to the platform, e.g., Execute operator for
a  query or database object write operator) on the server.
As the user views the results, he/she can select what should be displayed: meas-
urement for client, measurement for server, measurement for client and server
combined. The  mode is  selected by setting/unsetting check boxes in  the bottom
right corner of the performance measurement results window.
For server calls, time of server call execution on the server is accounted for.
The  entire procedure can be compared to execution time of nested procedure and
function calls for a  client application.

27.2.6. Saving Results

Measurement results can be saved in  a file using the File – Save and File – Save As
commands. Select directory and specify file name in  the standard save dialog box.
The  results file has a  *.pff extension.
Chapter 27. Debugging and Testing of Application Solutions 2-1057

A measurement file can be opened using the File – Open command. To filter meas-
urement files use the Performance analyzer (*.pff) filter.

27.3. SERVER CALL DELAY IMITATION

This mechanism aims to imitate application solution operation with significant
delays in  interaction with the server.
NOTE
This mechanism can only be enabled in  the thin client or the thick client in  man-
aged application mode.
The mechanism can imitate delays that can occur in  the following cases:
„„ Server call delay: in  seconds per server call;
„„ Send data to server delay: in  seconds per 1 KB (1024 bytes) of data sent to the
server.
„„ Get data from server delay: in  seconds per 1 KB (1024 bytes) of data received
from the server.
The mechanism can be enabled through appropriate setup of Designer parameters
(see page 2-1154) or by using the command line key /SimulateServerCallDelay
[-CallXXXX] [-SendYYYY] [-ReceiveZZZZ] where:
„„ Call – parameter that specifies the server call delay in  seconds; 1 s is  used if
none specified.
„„ Send – specifies the delay in  seconds per 1 KB of data sent to the server. 1 s
is  used if none specified.
„„ Receive – specifies the delay in  seconds per 1 KB of data received from the
server. 1 s is  used if none specified.
Example:
/SimulateServerCallDelay -Call2.1 -Send1.3 -Receive1.2

NOTE
The maximum delay value can be 9.99 s. 0 means delay is  not applied.
Server call delay imitation can also be enabled in  the 1C:Enterprise mode. To do
this, use the Tools – Options dialog box. Setup of server call delay imitation in  the
1C:Enterprise mode is  only valid in  the current session and is  not preserved.

27.4. DISPLAY OF SERVER CALLS

This mechanism is  used to debug client/server system and assess the amount of
data passed between the client and the server.
The mechanism can be enabled through appropriate setup of Designer param-
eters (see page 2-1157) or by using the command line key /DisplayPerformance.
2-1058 1C:Enterprise 8.3. Developer Guide

Performance display can also be enabled in  the 1C:Enterprise mode by selecting
the Show performance indicators check box in the Tools  – Options dialog box.
By default the mechanism is  disabled.
If this mode is enabled, 1C:Enterprise displays performance indicators in the
performance indicator panel at the bottom of the main application window.

Fig. 417.  Performance indicator panel

If the delay simulation mode is  enabled when a  server is  called, the picture in  the
window showing server calls will look differently.

Fig. 418.  Server Calls in  Slow Connection Imitation Mode

If you have not yet opened or have already closed the main application window of
an applied solution, the performance indicator window looks like this:

Fig. 419.  Server Calls

If the server delay simulation mode is  enabled, the performance indicator window
looks like this:

Fig. 420.  Delay simulation during server call

The current server call status (in progress, completed, none) is  displayed as an icon
in  the top left corner of the window. Size and position of the performance indica-
tors window are saved between the sessions.
Chapter 27. Debugging and Testing of Application Solutions 2-1059

When data displayed in  the server call window is  changed, it  is  highlighted with
red color.
By default the window displays two counters, Current сalls and Accumulated calls:
„„ Current calls – shows statistics of server calls since a certain point in time:
engine start time or the last user action not followed by any other user action
within 0.2 s.
„„ Accumulated calls – shows statistics of the server calls since the engine start or
its last forced reset triggered from the context menu.
This is  done using the Performance indicator settings. You can open this dialog by
clicking the button in  the performance indicator panel and selecting Settings in  the
menu.

Fig. 421.  Settings menu

You can specify the following parameters in  the settings dialog:
„„ Periodicity group – indicates the period to display counter values for;
„„ Indicators group – defines which indicators are to be displayed in  counters.

Fig. 422.  Performance Indicators Settings

The context menu of this window also includes the following commands:
„„ Clear accumulated – clears the accumulated calls counter.
„„ History of current – opens the history window for the current calls counter.
2-1060 1C:Enterprise 8.3. Developer Guide

„„ History of the accumulated  – opens the history window for the accumulated
calls counter.
The settings are shared by all users and all infobases of the current computer.
Setup of server call display window in  the 1C:Enterprise mode is  only valid in  the
current session and is  not preserved.
The user should be aware of the following peculiarities of this mechanism:
„„ In the file mode version (direct infobase connection) the amount of data
is  displayed without compression as compression is  not used in  this case.
„„ In the client/server or file mode version with Web server connection or in  the
SDC traffic compression mode, indicator values can be affected by actions
sequences since previously transferred data are used in  compression.
This mechanism has peculiar features in  the web client:
„„ Only synchronous calls are taken into account.
„„ The amount of transferred data is displayed in characters instead of bytes.
Measurement results can be used to compare various call options in  the web
client; it  is  not recommended to use the results to compare the amount of trans-
ferred data for different client types.
„„ Performance indicators are only displayed after the main application window
opens, and indicator values add up. After the main application window
is  displayed, you can see the relevant results from running the web client.
„„ The indicators window is  bigger than in  other clients and does not appear on
top of other windows.

27.5. AUTOMATED TESTING OF APPLIED SOLUTIONS

27.5.1. General Information
Automated testing comprises the simulation of interactive user actions and
checking up action results.
CAUTION!
Automated testing is  only supported for managed applications.
The automated testing scenario is a program written in the 1C:Enterprise
script. The scenario describes a sequence of actions and the results checkup.
The  1C:Enterprise script has special objects that allow you to simulate interactive
actions in the tested application and provide access to the logical model of the
client application interface and managed form items.
CAUTION!
Automated testing is  not supported by the Taxi interface.
Chapter 27. Debugging and Testing of Application Solutions 2-1061

Two systems participate in  the testing process: the testing manager and testing
client. The  testing manager handles the following:
„„ Connection to the testing client in  order to run the testing scenario (test connection)
„„ Execution of the testing scenario
„„ Evaluation of test results (if necessary)
The testing client handles the following:
„„ Execution of testing scenario commands received from the testing manager
„„ Transfer of data required for test results evaluation to the testing manager
You can use the thick or thin client as the testing manager, and you can use the
thick, thin or web client as the testing client. A single testing manager can be simul-
taneously connected to multiple testing clients, whereas a  testing client can only
be connected to one testing manager. The  testing manager and the testing client
communicate using a direct TCP/IP connection via a specific port (that has to
be open). The  testing manager and the testing client represented by a  web client
communicate via the 1C:Enterprise server (for client-server version of the tested
application) or a  web server (for file mode version). Testing does not require any
changes to be made to the tested application.
The testing scenario can be stored either in the tested applied solution or in a
separate applied solution. It  does not affect how the testing manager and the testing
client communicate.
Please note that the testing manager (and the testing scenario you execute) has
no direct access to the tested application. In  other words, the testing scenario can
access all features of the application where the scenario is  run (testing manager) as
well as the logical model of the tested application interface and forms.
If you launch a client application in the testing client mode, it does not affect
its performance nor any other characteristics; however, any testing manager can
connect to this application if it  knows the computer name (or IP-address) and the
port used for communication.
The system also allows you to write interactive user actions to an XML file. You
can use this file later for automated testing. To write this file, you should launch the
tested application in  a special run mode. You can also manage interactive action
write operations via the 1C:Enterprise script.

27.5.2. Running the Testing system

For the testing scenario to run, both the testing manager and the testing client
must be running. You can launch them in  any order. It  is  important that, before
you execute the testing scenario, the testing client is  running and available at the
address used for connection by the testing manager.
You can use either the command line (this method is  discussed below) or Designer
for startup. The application you start from Designer can be assigned either role
2-1062 1C:Enterprise 8.3. Developer Guide

(testing manager or testing client), depending on the settings specified in the

Designer settings dialog (for a detailed description of the settings, see page
2-1148).

27.5.2.1. Running testing client

You can run the testing client using the TestClient command-line parameter for
client application startup. You can also specify the number of the TCP port to be
used for testing manager – testing client communication. To do this, use the TPort
option of the TestClient parameter. If no value is  entered for this option, 1538
is  used. This  option must be specified if multiple testing clients run on a  single
computer.
So startup command line for the client application that is  to be used as the testing
client looks as shown below:
1cv8c ENTERPRISE /IBName "Test Application" /TestClient -TPort 1843

In this example, the thin client (1cv8c) is  used as the testing client for the Test
Application infobase, and TCP-port 1843 is used for communicating with the
testing manager.
Therefore, if you want to connect to the testing client represented by the thin or
thick client, you should know two parameters: the IP-address (or computer name)
where the testing client is running, and number of the TCP-port to be used for
communicating.
Running a web client is a little more complicated. In addition to the
TestClient option, you should specify another startup command-line option: the
TestClientID<ID> that contains a  unique identifier for the tested client applica-
tion. If the web client is  used, unique identification of the testing client requires
three parameters:
„„ Address of the web server where the tested application is  deployed. You do not
have to know the infobase address.
„„ The number of the TCP-port to be used by the web server to transfer data
between the testing manager and the testing client.
„„ The identifier of a specific instance of the tested application running on the
web client.
In other words, a single web server can work with multiple infobases and with
multiple connections to a single infobase (also for testing purposes), but for
the web server you have to specify which TCP-ports are to be used for commu-
nicating with the testing manager. You can do this in  the testcfg.xml file stored
in the web server extension settings directory. For details about this file, see
"1C:Enterprise  8.3. Administrator Manual".
Chapter 27. Debugging and Testing of Application Solutions 2-1063

27.5.2.2. Running testing manager

To be able to run a testing scenario, run your client application in the testing
manager mode. Use the TestManager command-line parameter to run the client
application. The  web client cannot be used as the testing manager.
So the startup command line for the client application that is to be used as the
testing client looks as shown below:
1cv8c ENTERPRISE /IBName "Test Manager" /TestManager

27.5.2.3. Running client applications for recording the user action log
If you want to run your client application to record the interactive action log, you
can use either the UILogRecorder command-line parameter or a  special command
in  Designer menu: Tools – Run to record user actions log.
You can also specify the number of the TCP port to be used by the testing manager
to control recording to the interactive action log. To do this, use the TPort option
of the UILogRecorder parameter. If no value is entered for this option, 1538
is used. You can also select the location where the system saves the log file.
To do this, use the File option of the UILogRecorder parameter. If this option
is  not specified, after the file is  recorded the client application opens a  text docu-
ment window containing the written log.
So the startup command line for the client application that is  to generate an interac-
tive action log looks as shown below:
1cv8c ENTERPRISE /IBName "Test Manager" /UILogRecorder

With this startup option, the right-hand top corner of the main client application
window displays a  special command panel that manages log recording.

Fig. 423.  Testing command panel

To start recording user actions, click the only available button on this panel.
This  changes the panel appearance (all buttons become available).
2-1064 1C:Enterprise 8.3. Developer Guide

Fig. 424.  Testing command panel during recording

You can use the command panel to stop interactive action recording. This  opera-
tion writes an action list to the file (if the File option is  specified) or opens a  text
document window with a list of actions. You can also interrupt or pause and
restart log recording.

27.5.3. Description of features

In terms of the testing scenario, the tested application is  a set of objects that can
simulate interactive actions in the tested application and provide access to the
logical model of the client application interface and managed form items:

Fig. 425.  Outline of the tested application

In the sections below objects shown in  the above figure are discussed in  greater
detail.
Chapter 27. Debugging and Testing of Application Solutions 2-1065

TestedApplication
You can use this object to do the following:
„„ Connect to the tested application.
„„ Disconnect from the tested application.
„„ Get an active window.
„„ Get a  list of tested application windows.
„„ Get current information about an error.
„„ Find an object with specified parameters in the subordinate object hier-
archy.
„„ Wait until an object with specified parameters is  displayed on the screen.
„„ Manage interactive user action logging in  the tested application.
TestedClientApplicationWindow
This object describes the client application window and provides methods of
window management:
„„ Get a  collection of subordinate objects for the window.
„„ Search for an object with specified parameters in the subordinate object
hierarchy for the client application window.
„„ Get the command interface of the tested client application.
„„ Work with user messages.
„„ Close the tested form.
„„ Execute a  command using a  navigation link.
TestedWindowCommandInterface
This object describes the command interface for the tested form of the applied
solution. It  has three subordinate TestedCommandInterfaceGroup objects:
„„ Sections panel
„„ Navigation panel
„„ Actions panel
For auxiliary windows, the command interface of the form only has the form
navigation panel.
TestedCommandInterfaceGroup
This object describes the command interface group and allows you to get
a  collection of subordinate objects for the group as well as search for an object
with specified parameters in  the subordinate object hierarchy.
2-1066 1C:Enterprise 8.3. Developer Guide

TestedCommandInterfaceGroup can comprise items of two types:

„„ TestedCommandInterfaceGroup
„„ TestedCommandInterfaceButton
TestedCommandInterfaceButton
This object describes a  command of the command interface and can be used to
simulate a  button click.
TestedForm
This object describes the tested application form and provides methods of form
management:
„„ Get a  collection of subordinate objects for the form.
„„ Find an object with specified parameters in the form subordinate object
hierarchy.
„„ Get the current active item of the form.
„„ Get the default button.
„„ Get the Modified attribute.
„„ Get the command panel of the form.
„„ Change the current form item to the next/previous item based on the form
item tab order (the item list in  the managed form editor).
TestedFormField
This object describes a text box in the form and provides methods for
managing this form item:
„„ Get a  collection of subordinate objects for the form field.
„„ Find an object with specified parameters in  the subordinate object hierarchy
for the form field.
„„ Define form item appearance.
„„ Simulate interactive actions for the following types of managed form fields:
○○ Text box
○○ Label field
○○ Picture field
○○ Radio button field
○○ Checkbox field
○○ Calendar field
○○ Spreadsheet document field
„„ No simulation of interactive actions is  available for the following types of
managed form fields:
○○ Progress bar field
Chapter 27. Debugging and Testing of Application Solutions 2-1067

○○ Track bar field

○○ Text document field
○○ HTML document field
○○ Geographical schema field;
○○ Formatted document field
○○ Chart fields (all types)
○○ Graphical schema fields
„„ If the object is associated with a text box, the following capabilities are
available:
○○ Get text being edited in  the text box.
○○ Simulate clicking the Clear button.
○○ Simulate clicking the Select button.
○○ Simulate clicking the Open button.
○○ Simulate opening a  choice list.
○○ Simulate selecting a  line in  the choice list.
○○ Simulate clicking slider buttons.
„„ If the object is  associated with a  checkbox field, the following capabilities
are available:
○○ Simulate changing checkbox status.
„„ If the object is  associated with a  radio button field, the following capabili-
ties are available:
○○ Simulate selecting a  radio button value.
„„ If the object is  associated with a  calendar field, the following capabilities
are available:
○○ Simulate setting a  selected date.
○○ Simulate date selection.
○○ Simulate moving a  month or a  year forwards and backwards.
„„ If the object is  associated with a  spreadsheet document field, the following
capabilities are available:
○○ Get the current region address.
○○ Get the current region text.
○○ Simulate the start of editing the current region.
○○ Simulate the conclusion of editing the current region.
○○ Get current editing mode for spreadsheet document.
2-1068 1C:Enterprise 8.3. Developer Guide

TestedFormTable
This object describes a form table and provides methods for managing this
form item:
„„ Get active table item.
„„ Get table cell text.
„„ Navigate through table rows and columns.
„„ Select a  row.
„„ Add or remove a  row.
„„ Get current table editing mode.
„„ Navigate through hierarchical list levels.
„„ Collapse or expand node for hierarchical lists.
„„ Check the state of the hierarchical list node (whether it is collapsed or
expanded) and the expandability of current row in  hierarchical list.
TestedFormButton
This object describes a  form button and can be used to simulate a  button click.
TestedFormGroup
This object describes a  group of form items and provides methods for group
management.
TestedFormDecoration
This object describes form decoration and can be used to simulate clicking
a  hyperlink or image.

27.5.4. Sample Testing Scenario

Below is  a simplified sample that creates a  new item in  the Goods catalog in  a
configuration. It  is  important that the main form contains a  field with the Name
header and a  button with the Write and close title.

// Connect to the tested application

TestedApplication = New TestedApplication ("localhost");
TestedApplication.Connect();
// Find main window
MainTestedApplicationWindow = TestedApplication.FindObject(Type("TestedClientApplicationWindow"));
MainTestedApplicationWindow.Activate();
// Execute command of item creation in  the Goods catalog
MainTestedApplicationWindow.RunCommand("e1cib/command/Catalog.Goods.Create");
TestedApplication.WaitForObjectDisplayed(Type("TestedForm"), "Good*");
TestedForm = TestedApplication.FindObject(Type("TestedForm"), "Good*");
TestedForm.Activate();
// Set name for a  new item
Chapter 27. Debugging and Testing of Application Solutions 2-1069

FormItem = TestedForm.FindObject(Type("TestedFormField"), "Name");

FormItem.Activate();
FormItem.InputText("New item");
// Write item
FormItem = TestedForm.FindObject(Type("TestedFormButton"), "Write and close");
FormItem.Click();

27.5.5. Service Options

27.5.5.1. Recording user action log
You can run the client application in  the mode that supports logging interactive
actions. This log can later be saved to a file. For a detailed description of this
mode, see page 2-1063.

27.5.5.2. Converting the user action log into an automated testing

scenario
You can convert a  saved user action log into 1C:Enterprise script code for subse-
quent use. You can perform this conversion using a  special tool located on site
http://1c-dn.com/developer_tools/user_action_log_conversion/).
Using this tool, you can do the following:
„„ Convert both the log file (e.g., a  file saved earlier) and the text entered manu-
ally (in the log format).
„„ Specify the script variant for the resulting code written in the 1C:Enterprise
script.
„„ Add code to implement the connection to the testing client.
„„ Indicate whether long sequences of actions should be split into procedures, each
working with a  single tested window of the applied solution.
The code resulting from the conversion can, for example, be used for multiple auto-
mated executions of the converted set of actions.
2-1070 1C:Enterprise 8.3. Developer Guide
Chapter  28

COMPARE AND MERGE

CONFIGURATIONS

You can use the configuration comparing and merging mode to compare two
configurations in  detail and to merge them. Selective merging based on compar-
ison results is  also possible.
You can use the merging mode, for example, when one configuration is  developed
by several persons at the same time. Sometimes they need to merge the results of
their work (or merge all results at the end of development).
The configuration comparing and merging mode can also be used to compare two
configurations without merging.
And finally, in  situations when you need to load changes to the source configura-
tion, you should review and evaluate them using the configuration comparing and
merging mode.
This mode compares both common properties of configuration objects such as cata-
logs, documents and journals and individual object and tabular section attributes.
Object forms (modules, description texts and templates) are compared separately.
You can view comparison results in  detail as well.

28.1. CONFIGURATION COMPARISON CONDITIONS

When the comparison mode is  activated, the program analyzes the configurations
and maps objects.
Objects without a match can be either new or deleted objects or they may be
objects from the same category but named differently in  different configurations.
You can specify interactive mapping for these objects (see page 2-1077).
When you set automatic mapping, the program analyzes configuration objects
with the same names. For example, Catalog.Goods in one configuration and
2-1072 1C:Enterprise 8.3. Developer Guide

Catalog.Goods in  another configuration are treated as one and the same catalog;
they are considered a  match and are compared.
Objects with different names are compared by internal IDs assigned by the
Designer during their creation. Internal IDs are required to simplify mapping of
configuration objects and make it automatic. For example, this situation occurs
when the object name changes during configuration development. If object names
are different while their internal IDs match, these objects are automatically mapped.
Form mapping is  done in  a special way. A form can contain several pages. First
forms are analyzed by names; then pages with different names are analyzed by (non-
empty) headers; and then pages with different headers are analyzed by pictures. If
pages match, their controls are compared and merged. If pages do not match, they
are considered different and the final form (after merging) contains all these pages.
Pages that have none of the three properties set (Internal ID, Header and Picture) are
merged by pairs in  accordance with the selected sequential order.

28.2. LAUNCH OF CONFIGURATION COMPARING

AND MERGING MODE
As you will see below, although compared configurations are generally equal
(i.e. you can set any of these configurations as a  priority configuration), in  some
aspects the current configuration is considered as the master configuration as
it is supplemented by all non-damaging changes from the loaded configuration.
Therefore, it is recommended to select the master configuration. The selected
configuration becomes the master configuration when 1C:Enterprise system
is  launched with it  in  the Designer mode.
Before comparing and merging the loaded configuration with the master configura-
tion, you have to save it  to a  file first (see page 1-49).
To load the second configuration, use the Configuration – Compare and Merge with
Configuration from File command. The  standard Select a  configuration file dialog
box will open. Find and open the file of the loaded configuration (*.cf) in this
dialog box.
If the master configuration is  empty (the configuration process has not begun yet),
the Designer asks the user to load the configuration completely. If the user confirms
this operation, the specified configuration is  loaded completely and the Configuration
window opens. If the operation is  cancelled, the configurations are compared.
The process of loading a configuration and comparing the loaded configuration
with the current configuration is  described by messages in  the status bar of the
Designer. These messages show configuration objects that are being currently
compared. The  status bar also shows a  comparison progress indicator.
Loading and comparing can take a lot of time depending on the size of the
compared configurations.
Chapter 28. Compare and Merge Configurations 2-1073

28.3. COMPARE CONFIGURATIONS

In addition to the master configuration comparing and merging mode described
in the previous section (when one of the compared configurations is always
selected as the master configuration), the Designer can be used to compare two
arbitrary configurations (e.g., configuration files) or repository configuration (any
version) and vendor configuration, etc.
Configurations to be compared can be selected in the Configuration  – Compare
Configurations menu.
The following dialog box is  displayed:

Fig. 426.  Compare Configurations

This dialog box contains two sections used to select configurations for comparison.
Techniques used in  both sections are the same.
You can choose configurations from the master configuration, database configura-
tion, configuration in  a file, storage configuration and vendor configuration (if the
current configuration is  supported).
If a file or storage is selected, the file or storage version selection combo box
is  added to the corresponding section of the dialog box.
If the compared configurations are not descending from each other and it  is  impos-
sible to match them by internal IDs, you should check the Determine Match By
Object Names box. Click OK to start the comparison process. The  Designer will
compare the specified configurations and will display results in the Compare
Configurations window. Techniques used in  this window are the same as described
in the Compare and Merge Configurations section. The only difference is that
in  the comparison mode you can only view the selected objects and obtain a  report
on differences.
2-1074 1C:Enterprise 8.3. Developer Guide

28.4. COMPARE PREDEFINED DATA

When predefined data are compared, their items are mapped only by internal IDs.
A unique ID (within a metadata object) is assigned to a predefined item when
it  is  created. This  ID remains intact during any movement of the predefined data
between configurations when the configurations are merged or copied. This  way ID
behavior is  different from the behavior of the corresponding metadata object ID.
Therefore, if you create predefined data items with the same name in  two configu-
rations, these items are considered different during comparison. The  only way to
obtain identical predefined data in  two configurations is  to use merging or copying.
When a database configuration is updated, predefined items are mapped with
existing database objects. Internal ID consistence ensures a correct association
between the predefined data item and its mapped database object when they are
moved between configurations. Replacement of mapped objects is  done in  accord-
ance with priority configuration selection.
Since mapping is  based on internal IDs, predefined data for hierarchical structures
can be merged even if they are located at different hierarchy levels. The  merging
result (the hierarchy level that will contain the merged item) depends on the
configuration priority.

28.5. COMPARE AND MERGE CONFIGURATIONS WINDOW

The Compare and Merge Configurations window is  opened when the comparison
procedure has finished. This  window can be used to do the following:
„„ learn which objects in  the two configurations are different
„„ select objects that require a  detailed review of differences
„„ open specified objects for viewing and editing
„„ select objects to be used for merging
„„ map objects
„„ specify configuration merging modes (for the entire configuration or for each
specific object)
„„ specify the order of subordinate objects (for the entire configuration or for each
object)
„„ generate a  report on the configuration differences
„„ initiate the configuration merging procedure
The window (see fig. 430) contains a  table box that consists of three columns if the
configurations are not linked with each other (for more information about linked
configurations see page 2-1075). The  first column contains information about the
master configuration (the infobase that is opened in the Designer), the second
column contains information about the loaded configuration and the third column
is  used to set the comparing mode and the order of subordinate objects.
Chapter 28. Compare and Merge Configurations 2-1075

The object mapping status is  indicated with the row background color. Possible
statuses are shown below the table box.
The Filter combo box is  located below. You can use this box to enable the change
view mode. When the Comparison window is  opened, Show configuration differ-
ences filter is enabled. You can select other modes to examine configuration
differences or matches.
Click the Actions button to open the context menu.
Use the Set Mode For All command to open merging mode setup dialog box (see
page 2-1078) and order settings (see page 2-1082) for all objects.

Fig. 427.  Setting Modes for All Objects

Check against … subsystems item can be used to turn on filtering by subsystems.

Use the Configuration Comparison Report menu item to obtain a report on
comparing two configurations with the required detail level.

28.6. CONFIGURATION COMPARISON SETTING

Click the Settings button to open the Setting the Configuration Comparison dialog.

Fig. 428.  Configuration Comparison Setting

2-1076 1C:Enterprise 8.3. Developer Guide

You can select the configuration comparison mode in  this dialog box. Mode for
comparing different (non-linked) configurations is  used by default.
If configurations are linked, please select the link type. When you close the setting
dialog box (by clicking OK), a  special column is  added to the Compare and Merge
window. The  object changes history is  shown in  this column with special icons.
The special column is  added to the File column if the loaded configuration is  a
descendant of the master configuration or to the Base configuration column if the
master configuration is  a descendant of the loaded configuration.
Help information for status drill down of the object history Statuses group is  also
added to the window.
If the configuration uses multiple languages, selective comparison by languages
is  available. To do this, set the Use selective comparison by the following languages
option and specify one or more languages for comparison.

Master Configuration Objects Group

When configurations are merged, objects of the master configurations can be
deleted. By default this feature is  only enabled in  the vendor configuration update
mode. If it is required in other modes, set the Allow base configuration object
deletion check box.
The following rules apply to setting deletion marks for vendor objects by default.
If the user has modified a  vendor object as compared to the previous version of
vendor configuration, the object is not marked for deletion by default; if the
object is  identical to its previous version, it  is  marked for deletion. If an object
has been marked for deletion (automatically or manually), clicking the Execute
button results in  reference integrity check. If unresolved references to a  deleted
object have been found, they are displayed in  a separate window; however, unlike
the case of unresolved references resulting from a  cancelled copy operation for an
object of vendor configuration (or any other configuration included in  the merge
operation), the user cannot continue merging (and delete the object).

Loaded Configuration Objects Group

When configurations are merged, by default objects missing in  the master configu-
ration are added together with IDs assigned to them in  the loaded configuration.
Setting the Copy Objects Mode (internal object identifiers are not saved) check box
means new objects can be added according to the rules from the previous platform
versions: when objects missing in  the master configuration are added, news IDs
are always generated for them.
When you click OK, configurations are compared again according to the specified
settings.
Chapter 28. Compare and Merge Configurations 2-1077

28.7. OBJECT EDITING

When the Merge Configurations window is  opened in  the standard mode (storage
is not used and support is not provided), you can view and edit objects of the
master configuration.
To edit object properties specify the required object in  the column of the master
configuration and correct the value in  the properties palette. If the edited object
is  a form, template, interface or another complex object, it  can be opened using
the Open Form (Template/Interface) command of the context menu. Objects of the
master configuration can also be selected for editing in  the Configuration window.
Objects of the loaded configuration are available only for viewing. The  procedure
for accessing loaded configuration objects is  similar to the procedure for accessing
master configuration objects.
In case any changes have been made, the Execute button becomes unavailable and
all objects are assigned the Undefined status (displayed in  grey). Click the Refresh
button to keep working in the Compare and Merge Configurations window.
The Designer compares the configurations again (taking into consideration the
changes made) and maps objects.

28.8. DISTRIBUTED DEVELOPMENT AND SUPPORT – EDITING

In the distributed development mode, you can only edit objects of the master
configuration that are captured from the storage in the Compare and Merge
Configurations window.
Read-only objects can only be viewed. You cannot merge these objects (no option
to check).
A lock icon to the left of the object icon indicates that the object is read-only.
In  addition to that, object status is  shown below the table box. The  status contains
a  text message that indicates that the object is  read-only.
The Compare and Merge Configurations window behaves similarly if the configu-
ration is  supported. If you set the vendor rule that forbids changes for a  specific
object, this object is available only for viewing. These objects can only be
compared and cannot be merged.

28.9. OBJECT MAPPING

When configurations are compared, the program automatically maps objects of
the two configurations. Since objects are mapped based on their names, object
names can be identical in  the configurations being compared. However, objects of
the same name may in  fact be different. On the other hand, objects with different
names might be the same. In  such cases you must define object mapping manually.
To cancel mapping select an object and choose the Clear Object Mapping command
from the context menu. The status of these objects changes to Undefined.
2-1078 1C:Enterprise 8.3. Developer Guide

Click Refresh when mapping is  cancelled for all these objects. The  Designer will
again compare the configurations.

Fig. 429.  Compare/Merge Configurations Main Window

Objects of the master configuration have a  beige background (only in  the master
configuration), while objects of the loaded configuration will have a  green back-
ground (only in  the loaded configuration).
To enable mapping select an object and choose Find Objects Relationship from the
context menu. The  system displays a  list of objects for which mapping is  enabled.
The  list includes objects of the same type and objects which have not yet been
mapped. Select an object and click OK.

28.10. MERGING MODE

You can enable the merging mode for each merged object. There are two types of
merging:
„„ Use from file (the merging mode name may vary depending on the loaded
configuration);
„„ Merge. In  this case configuration priority is  usually specified during merging.
Chapter 28. Compare and Merge Configurations 2-1079

If you choose Use from Loaded Configuration, then the configuration object
is added (if it is new) or replaced (if it is modified). The entire object struc-
ture, modules, forms and descriptions are moved. The loaded configuration has
maximum priority.
When you pick the Merge method, merging behavior depends on the specified priority.
If you need to take only new items from the loaded configuration and to preserve
the old configuration as much as possible, choose the Merge Prioritizing Master
Configuration option. Only new objects are added in  this mode.
Texts are merged as follows:
Text Priority Result
Deleted (exists in  the master Master configura- Remains in  the text
configuration, but doesn't exist in  the tion priority
loaded configuration)
New (exists in  the loaded configura- Added
tion, but doesn't exist in  the master
configuration)
Modified Added as comments from the loaded config-
uration. Contents of the master configuration
remain unchanged
Deleted Loaded configura- Turns into comments
New tion priority Added
Modified Changes in  the master configuration are
turned into comments; changes in  the
loaded configuration are added

Priority selection for a  form module can be illustrated as follows.

Text in  the master configuration module:

Procedure SpecifyStatus(Item)
// Insert handler contents
Message("Message from the master configuration");
EndProcedure

Text in  the loaded configuration module:

Procedure SpecifyStatus(Item)
// Insert handler contents
Message("Message from the loaded configuration");
EndProcedure

Result of merging when the master configuration has the priority:

Procedure SpecifyStatus(Item)
// Insert handler contents
//{{MRG[ <-> ]
Message("Message from the master configuration");
//{{MRG[ <-> ]
//{{MRG[ <-> ]
2-1080 1C:Enterprise 8.3. Developer Guide

// Message("Message from the loaded configuration");

//{{MRG[ <-> ]
EndProcedure

Result of merging when the loaded configuration has the priority:

Procedure SpecifyStatus(Item)
// Insert handler contents
//{{MRG[ <-> ]
Message("Message from the loaded configuration");
//{{MRG[ <-> ]
//{{MRG[ <-> ]
// Message("Message from the master configuration");
//{{MRG[ <-> ]
EndProcedure

The table below shows the dependence of merging results on the priority and value
availability for objects that have property values specified in  the properties palette
(e.g., Synonym, Comment).
Value in  Master Value in  Loaded Result (value
Configuration Priority
Configuration Configuration is  taken from…)
Specified Specified Master configuration priority Master
Specified Not set Master
Not set Specified Loaded
Specified Specified Loaded configuration priority Loaded
Specified Not set Master
Not set Specified Loaded

If a  property of an object can represent the result of a  composite value of objects

from the two configurations (e.g., Base On property), the result is  determined by
simple merging or selected from the loaded configuration.
If the configuration uses multiple languages and selective language comparison
is  enabled in  the settings, such objects are compared and merged by the specified
languages.
The following procedure is used for template merging: the resulting template
consists of the template of the master configuration and the template of the loaded
configuration separated by a  row with yellow background. The  priority configura-
tion template is  listed first in  the resulting template and the other template follows
after the separator. Final merging should be done manually after comparing.
NOTE
The Template Type property is not displayed in the Compare and Merge
Configurations window. During merging this property is  merged in  the same way
as the Template property.
When managed forms are merged, visualization of differences in the Compare
and Merge Configurations window is  not supported, but form comparison results
Chapter 28. Compare and Merge Configurations 2-1081

can be displayed in the text format in a report on object comparison. Mapping
is  performed according to the following rules when forms are compared:
„„ Module texts are compared by procedure names.
„„ Form elements are compared by element type and name.
„„ Form options are compared by name.
„„ Commands are compared by name.
„„ Attributes are compared by name.
„„ For the command interface, comparison is  performed by command type (auto-
matic or custom) and command name.
Elements with the same names will be replaced in  the master form (the properties,
size and dimensions will be specified) if the loaded configuration has priority, but
they will be left unchanged if the master form has priority. Some form element
properties can be merged (e.g., a  selection list, titles in  different languages, etc.).
Form merging mode can be configured both for the whole form – for managed and
ordinary forms, and for the form and the module form – for managed forms only, as
shown in  the fig. 430.

Fig. 430.  Configuring module merging

From the Form joining setup window, you can also open the module comparison
window (see page 2-1083) by clicking the button with the magnifying glass in  the
right side of the Module: field.
For some objects (object attributes) it may be impossible to pick the merging
mode. Thus, for attributes with primitive type (e.g., Number), only the Use from file
merging mode is  available.
For some objects it  may be impossible to select priority. For example, for Subsys-
tems property you can select the Use from file and Merge merging modes. If you
2-1082 1C:Enterprise 8.3. Developer Guide

choose the Merge mode, then the specified subsystems of the two configurations
are simply merged.
For rules of merging predefined data see page 2-1074.

28.11. SETTING ORDER OF SUBORDINATE OBJECTS

In some cases the order of objects in  their group is  important for objects that can
have an unlimited number of subordinate objects (e.g., Attributes, Forms, Templates,
Tabular sections and other subordinate objects of catalogs and documents).
If the Designer has mapped objects within a  group while merging configurations,
but has determined they are listed in  a different order in  different configurations,
you can specify the required order in  the Merge Mode and Subordinate Objects
Sequence column.
To specify the order select any subordinate object and, in  the third column, select
the order setting option: Order from base configuration or Order from file.
The selected ordering method is  applied to all subordinate objects of this type.
If subordinate objects for the selected object are changed and listed in  a different
order, you can only pick the order in the third column. You can specify the
merging mode in  the context menu for higher-level objects. For example, in  both
configurations there are several subordinate documents of the Forms type for Bill
document. These forms and their order has been changed. To pick the merging
mode select a  higher-level object (Forms or Bill) and choose the required merging
mode in  the context menu.

28.12. VIEWING DIFFERENCES

You can view differences between configuration objects before merging.
To do this, you can use the properties palette. Open the properties palette and choose
the required object of the master or loaded configuration. You can open forms or
templates for viewing. If they are compared with a standard configuration file
which is  not a  distribution file (see page 2-1121), you can make corrections to the
loaded configuration data in  addition to viewing. If corrections have been made, the
Designer offers the user to save all changes made in  the loaded configuration.
To view differences between modules choose Show Module Differences without
Structure from the context menu.
When you pick this item, the Difference Between:… window is opened. If the
compared texts are large, several seconds may pass before the window opens.
For details on how to view differences see page 2-1175.
The Merge Modules mode (see below) is  used for selective module comparison.
Choose Show Template Differences from the template context menu to view differ-
ences between templates.
Chapter 28. Compare and Merge Configurations 2-1083

The comparison window opens.

Fig. 431.  Merge Templates

Spreadsheet documents are compared by cells. If cells differ (any properties except
Details Parameter), the difference is  shown in  color. The  color legend is  shown
at the bottom of the comparison window.

28.13. MODULE COMPARISON

During configuration merging you can configure merging of procedures and func-
tions of any module (application module, common modules, object modules and
form modules).
To do this, select the line that corresponds to the merged modules in  the Merge
Configurations window and activate the selected ordering type in  the Merge Mode
and Subordinate Objects Sequence column (click the cell). Ordering and merging
selection buttons will be shown to the right of the cell. Click the magnifier button.
The Compare Modules window will open.

Fig. 432.  Module Comparison

2-1084 1C:Enterprise 8.3. Developer Guide

The top of the window contains a  table box that corresponds to the table box from
the Merge Configurations window. The  only difference is  that the column content
is  taken from the names of module parts: variable declaration area, procedures and
functions section and main program area (henceforth, the objects). Any of these
sections can be missing.
The contents of the table box are determined by the currently set filter (Filter
attribute).
Select differing objects that need to be merged in the first column. You can
customize the merge settings for the selected objects.
Comparison is  done separately for each section. Only objects that are mapped are
compared. Auto-mapping by name is  performed as an initial step.
You can clear any mapping of procedures and functions. To cancel mapping select
the line with the object from the list and choose the Clear Object Mapping command
from the context menu.
If object names in  the compared modules have changed, but objects still have the
same contents and need to be compared, you have to map the objects manually.
To map the objects choose any object for which the setting is to be made and
choose Set Object Mapping from the context menu.
The Test() procedure of the main configuration on the figure above corresponds
to the ShowHeader() procedure of the loaded configuration. The  Merge Modules
window shows differences between these objects after manual mapping (see
below).

Fig. 433.  Merge Modules

Differences between the objects are shown when the Display Result option
is  unchecked. If this option is  checked, the merging result is  shown with consid-
eration for the merging mode.
Chapter 28. Compare and Merge Configurations 2-1085

Module object ordering is  determined based on the Order attribute.

To view comparison results for modules without consideration for structure, click
Actions  – Show Module Differences without Structure. The  Differences Between
window will open. For details on how to view differences see page 2-1175.
To view preliminary module merging results click Actions – Show Merge Results.
After mapping ordering and specifying the merging mode click OK to save the
merging settings. Click Cancel to discard the changes.
When the module merging procedure completes, Custom Setting is  displayed in  the
Merge Mode and Subordinate Objects Sequence column of the Merge Configurations
window. If you select another mode from the list, the settings are lost.
Modules are merged based on these settings only for the entire configuration.

28.14. FILTERING OBJECTS AND ACTIVATING MERGING

To generate a  list of merged objects set the check boxes to the left of the master
configuration object icons. Checking or unchecking higher-level objects checks or
unchecks all subordinate objects. Check boxes indicate the selected objects of the
two configurations will be merged.
Object check box is  set to Undefined if some of its subordinate objects are checked
and some are unchecked.
When you open the Merge Configurations window, the Designer adds all valid
objects to the list of merged objects.
Click the Execute button for the Designer to analyze the checked configura-
tion data. If there is nothing to prevent merging, configurations are merged.
The  merged configuration is  automatically saved.
If you perform selective merging and select objects referencing other objects that
are not checked for merging, the Designer displays a  list of unresolved references.
For example, if one of the attributes of a  checked object is  a reference to another
object of the loaded configuration that is  not checked for merging, this reference
is  considered unresolved (see fig. 434).
The window contains two table boxes. The  upper table box contains a  hierarchical
list of all found objects that are linked with checked objects in  the Merge Configu-
rations window. The  lower table box contains a  hierarchical list of objects that use
the object from the upper list.
This window can be used to examine links between the selected objects and to
decide whether it is necessary to include these objects in the list of merged
objects.
Use the Mark All for Merge button to check all objects that should be checked for
adequate merging. When you click this button, the window closes and all required
objects in  the Merge Configurations window are checked.
2-1086 1C:Enterprise 8.3. Developer Guide

Fig. 434.  Unresolved References

Use the Continue button to merge only the checked objects without consid-
eration for unresolved references. In  this case the specialist who performs merging
is  responsible for merging results.

28.15. LOADING CONFIGURATION FROM FILE

If the entire configuration needs to be replaced while running 1C:Enterprise, you
need to load the new configuration from file.
Use the Configuration – Load Configuration from File command of the main menu to
load changes.
Find and open a  new configuration file (1Cv8.cf by default) in  the standard open
file dialog.
If the current configuration is not empty, the following message is displayed:
Configuration is  not empty. Loading the configuration will completely replace the
current configuratuion with the new one, without comparison or merger. Continue?
If you click Yes, differences between the old and the new configuration structures
are analyzed and the required changes are made. The system asks you whether
it  is  necessary to update the database configuration.
You can also load a  configuration from file to create a  new configuration based on
the loaded configuration.
Chapter  29

DISTRIBUTED
CONFIGURATION
DEVELOPMENT

This chapter describes Designer features designed to enable distributed configura-

tion development.
To undertake successful distributed configuration development developers can
agree on conventions governing modification of configuration objects, make these
changes and then integrate the results. However, this mode introduces a risk of
accidental changes to various objects; it is therefore critical for participating
developers to understand all modification processes and relationships between
objects. In this case configuration merging should be completed by a senior
specialist who can effectively steer the direction of development effort.
This chapter explains how to reduce probability of errors, increase performance and
simplify the development process through distributed configuration development as
described herein.
In a distributed environment workgroup, a development effort is conveyed
through changes to a  configuration object that can be made only by the developer
who has previously locked the object.
A configuration repository is created for distributed development purposes.
The  Designer places the configuration into this repository. Developers are granted
access to the configuration repository: either through the local network or using
remote access through a  Web server. After the repository is  created, a  Repository
Administrator is appointed. This role is responsible for creating a list of users
who can access the repository. Administrative permissions can be assigned to other
users as well.
2-1088 1C:Enterprise 8.3. Developer Guide

In the distributed development environment configuration is treated as a set of

read-only objects. In  order to make changes to an object the developer has to lock
it  first. An object can be locked only by one user at a  time. A user may lock any
number of objects that are not locked by other users.
Techniques for working with locked configuration objects are in  no way different
from the regular environment. The  user can edit properties of the locked object as
well as add and remove subordinate objects.
To add an object the user first has to lock the parent object. For example, to add
a  constant the user needs to lock the root configuration object. To add an attribute
or object form the user needs to lock the object itself.
To delete an unlocked object the user needs to lock the object itself, its parent
object and all of its subordinate objects.
When you are done working with the locked objects, the result of their modifica-
tion can be stored in  the configuration repository. On the other hand, if any of the
unlocked objects have been changed, you can receive updated objects immediately
after they are placed in  the configuration repository by the author of the changes.
Configuration repository activities can be viewed in  the configuration repository
history. You can open configuration versions stored in  the configuration repository
to view and compare them with the current configuration, database configuration as
well as different repository versions.
Configuration objects are closely interrelated. Therefore, the configuration reposi-
tory ensures metadata integrity when objects are locked or stored in  the repository.
In this way, the distributed development method ensures synchronization of
configuration modifications by a  group of developers.

29.1. CONFIGURATION REPOSITORY ADMINISTRATION

29.1.1. Creation of Configuration Repository
Configuration repository is created to provide shared access to configuration
objects.
To create a  configuration repository select Configuration  – Configuration Reposi-
tory – Create Repository. The  following dialog box is  displayed:

Fig. 435.  Creation of Configuration Repository

Chapter 29. Distributed Configuration Development 2-1089

In the Repository location (files directory or remote repository address) field, enter
the directory where the configuration repository is to be created. This directory
should not be registered as a storage place for another configuration repository.
Click Next >.

Fig. 436.  Selection of Configuration Repository Administrator

Enter name and password for the configuration repository administrator.

The  configuration repository administrator creates a  list of users with access rights
in  the configuration repository.
When you click OK, the Designer analyzes the data, generates the structure of
objects and records the data in  the specified directory. This  process can take some
time (depending on the configuration size). When the configuration repository has
been created, the Designer prompts the user to open the configuration repository.

Fig. 437.  Open Configuration Repository?

If the specified directory is  already holding a  registered configuration repository,

then the Designer displays a  warning that it  is  unable to create a  configuration
repository in  this directory.

29.1.2. Open Configuration Repository

To open the configuration repository select Configuration  – Configuration Reposi-
tory – Open Repository.
If the current configuration has not been connected to the configuration repository, then
before connection the Designer reports that the current configuration will be replaced
by a  configuration from the repository and requests confirmation for connection.
IMPORTANT!
Configuration received from the repository replaces the current configuration and
is  saved to disk without additional warnings.
2-1090 1C:Enterprise 8.3. Developer Guide

After confirmation the connection dialog box appears:

Fig. 438.  Open Configuration Repository

Enter username and password, if any.

If this username is not registered in the configuration repository, the following
warning appears: Configuration repository authentication error. Check whether the
user name and password are entered correctly.
Each user can connect only one configuration to the repository. Therefore, the
Designer must first perform a  login credentials check for the user.
If the username is registered in the configuration repository and no infobase
is  connected to the configuration repository for this user, then login is  performed
and the link is established: information on the configuration and its location
is  recorded in  the configuration repository for this user.
If user configuration has already been connected and the link has not changed, then
the configuration window appears and the user can start working with the configu-
ration objects.
If a connected configuration for this user is currently open, then the Designer
displays an authentication warning.
If an infobase for the given user is  not currently open, but the location informa-
tion is  different (e.g., the configuration is  in  a different directory or a  connection
is  made from a  different workstation), then the Designer displays the following
message: Configuration bound to this configuration repository already exists for this
user. Continue? Pressing the Yes button in  this dialog box creates a  new connec-
tion, the current configuration replaces the configuration from the repository and
a  new link is  established between the current configuration and the repository for
this user.
After logging in  the Designer opens the Configuration window (see fig. 439).
The status of configuration objects is  indicated by icons arranged along the right
border of the Configuration window. Icons of the parent and child (subordinate)
objects are of different sizes (child objects are smaller) and appearances (child
objects have an image of a  tree branch).
Possible object status are shown on fig. 440.
Chapter 29. Distributed Configuration Development 2-1091

Fig. 439.  Configuration Connected to Repository

Fig. 440.  Object Icons

If an object has been locked by another user (see fig. 440), it  can be modified only
by the user who has locked it. The  metadata object tooltip that appears above the
current object status icon in  the configuration repository contains the name of the
user who has locked the object, lock date, name of the computer used to connect the
user to the configuration repository and location of the infobase.
2-1092 1C:Enterprise 8.3. Developer Guide

Newly created objects that have not yet been checked in  the configuration reposi-
tory and objects that have been deleted from the repository but still exist in  the
local configuration are represented by an icon in  the form of a  red mark.
Upon the first login the Designer stores the connection parameters (the configura-
tion repository directory and username) for the given infobase. The  next time the
user opens the configuration, the Designer requests to connect to the configuration
repository before displaying the Configuration window.
If an incorrect username or password is  entered when logging into the configu-
ration repository or if a user with this name is already connected to the given
repository at that moment, then the following message appears: Configuration
repository authentication error. Check whether the user name and password are
entered correctly.
If there is an attempt to bind a configuration not previously connected to the
configuration repository by entering a username for which there is a registered
connection (established link) to the repository, but for another infobase (which
is not open at the moment), then the Designer displays the following message:
Configuration bound to this configuration repository already exists for this user.
Continue? After an affirmative response the configuration is loaded from the
configuration repository (the current configuration is completely replaced and
saved to disk) and a  new infobase and configuration repository link is  established.
In  this case the former link is  dropped (the infobase which was connected earlier
to the configuration repository cannot be joined to this user without reconnecting).
If there is a login attempt to the configuration repository and the configuration
is  currently open, the Designer displays an error message showing the username
for the attempt.

29.1.3. Maintaining the Configuration Repository Users List

To create a  new configuration repository user select the Configuration – Configura-
tion Repository – Repository Administration menu item and choose Actions – Add on
the Users tab. A window for editing user information will appear. Use the General
tab to enter username and password to access the configuration repository.

Fig. 441.  Configuration Repository User Parameters

The Rights tab displays access rights for this user.

Chapter 29. Distributed Configuration Development 2-1093

Fig. 442.  Configuration Repository User Rights

Administrative tasks – user has privileges to create, delete and disconnect users,
cancel locks, change the repository compatibility mode and run the optimization
procedure.
Change version structure – the user has the right to roll back and delete old versions
(for details see page 2-1102).
Lock objects – the user with this right can lock and make changes to the configu-
ration of the configuration repository. If this right is not set, the configuration
repository objects for this user are read-only.

29.1.4. Configuration Repository Administration

Configuration repository administration is  done through the administration window
which is  available via the Configuration  – Configuration Repository  – Repository
Administration menu item.
It displays a  dialog box (see fig. 443).

Fig. 443.  Configuration Repository Administration

The Users tab contains controls which manage the list of configuration developers
(hereinafter referred to as "users" in  this chapter). All users can change their own
login credentials (username and password), but they cannot change their access
rights. Names of users that are currently connected to the configuration repository
are shown in  bold. On fig. 443 it  is  Jones.
2-1094 1C:Enterprise 8.3. Developer Guide

IMPORTANT!
Only users with administrative permissions can add, delete and change user rights.
The Connections tab lists users logged into the configuration repository.

Fig. 444.  Connected Users

You can disconnect any user who is  not currently working with the configuration
repository from the repository by pressing the Disconnect button.
IMPORTANT!
The Disconnect button is  accessible only to users with administrative permissions.
You can release object locks for a  particular user by using the Release locks tab.

Fig. 445.  Release of Object Locks

The user would be unable to store any changes he or she has already made to the
locked objects in  the configuration repository.
IMPORTANT!
This button is  accessible only to users with administrative permissions.
Chapter 29. Distributed Configuration Development 2-1095

The Other tab contains parameters that manage the repository operation.

Fig. 446.  Configuration repository parameters

The Repository data optimization group can be used to perform optimization for
a repository that is not compatible with version 8.3.2 (the compatibility mode
is set to Do not use). Optimization results in higher repository performance.
You should only perform optimization if the system prompts you to do so.
A user with administrative privileges can enable a  prompt for optimization after
performing each repository operation (adding objects, rolling back or merging
versions). To do this, select the Prompt for optimization after performing repository
operations checkbox on the Other tab of the repository administration dialog. If this
option is  selected, after a  repository operation is  complete, the following dialog
may be displayed to the user:

Fig. 447.  Prompt for repository optimization

If the user (repository administrator) chooses to skip optimization when the prompt
is  displayed, optimization can be run later. To do this, open the repository admin-
istration dialog, go to the Other tab and click the Optimize button. You should
click the button if the optimization prompt is  displayed to the right of the button.
Repository optimization can take a  long time (see fig. 448).
We recommend that you do not work with the repository during optimization.
You can also run optimization using the following Designer startup command-line
option: /ConfigurationRepositoryOptimizeData.
2-1096 1C:Enterprise 8.3. Developer Guide

Fig. 448.  Optimization recommended

29.1.5. Repository Backup Configuration

The backup procedure depends on the compatibility mode selected for the reposi-
tory.
CAUTION!
When you run configuration repository backup, no connections to the repository
are allowed.
If the repository is  in  compatibility mode (the Compatibility mode property is  set
to Version 8.3.2), create a  repository backup file by copying the 1Cv8ddb.1CD file.
If the repository does not use the compatibility mode (the Compatibility mode
property is set to Do not use), create a repository backup file by copying the
1Cv8ddb.1CD file and the entire data directory located in  the same directory as
the 1Cv8ddb.1CD file.

29.2. WORKING WITH CONFIGURATION REPOSITORY

Locking, retrieving and storing objects in  the configuration repository as well as
other actions with repository objects can be done in  the Configuration Repository
window. To open it  choose Configuration – Configuration Repository – Repository
(see fig. 449).
The Configuration Repository window contains a  toolbar and table box. The  first
column of the latter contains a  hierarchical structure of configuration repository
objects or a  list of objects depending on the view mode (Type menu).
If deleted objects are set to be available for viewing (Type submenu), then deleted
items are displayed in  the list in  a lighter font.
Chapter 29. Distributed Configuration Development 2-1097

Fig. 449.  Configuration Repository

In the second column, the status of locked objects is shown by icons. Objects
locked by the current user are represented by an icon with a  red checkmark. In  the
User column, the user who has locked the object is  shown. In  the Date column,
the lock date (if the object is  currently locked) or the date of the last update for
this object is  shown. In  the Computer column, the name of the user's computer
is  shown and in  the Infobase column, the name of the local infobase directory on
the user's computer is  shown.
IMPORTANT!
Newly created objects that are not yet stored in  the configuration repository do
not appear in  the configuration repository window.

29.2.1. Configuration Repository Filter

To simplify working with the configuration, you can customize the objects view
in the Object column of the Configuration Repository window. The  filter is  acti-
vated through the Actions – Filter menu. The  following window is  displayed:

Fig. 450.  Filter Configuration Repository Objects

The meaning of the controls is  self-explanatory.

2-1098 1C:Enterprise 8.3. Developer Guide

29.2.2. Locking Configuration Repository Objects

The object lock is  a way of acquiring the exclusive ownership of the modification
of a configuration repository object. The locked object becomes inaccessible to
other users to make changes (you can only view and retrieve a  copy of the changed
object for use).
To lock objects select the object (multiple selection is  allowed) in  the Configura-
tion Repository window and click the Actions – Lock in  Repository command.

Fig. 451.  Lock Objects In  Configuration Repository

If this object is  linked to other objects, then these objects are also included in  the
list. In  this case the selected object is  displayed in  bold. You can only lock selected
objects when these objects are also retrieved from the configuration repository.
The list also includes objects that are not directly linked to the chosen object, but
have an indirect link.
To retrieve these objects select the check box in  the first column of the list. If you
need to not only retrieve, but also lock these objects, select the check box in  the
Lock column. If not all objects required for the lock are marked for retrieval, the
Designer displays the following message: This  operation requires the following
objects to be retrieved. The message is followed by a list of required objects.
Locking in  this case does not occur.
If the objects contain subordinates that need to be locked, select the Retrieve Recur-
sively check box.
If you need to retrieve data of objects that are already locked, select the Allow to
Retrieve Locked check box.
IMPORTANT!
If the Allow to Retrieve Locked check box is  selected, changes made in  locked
objects are lost when re-retrieving occurs.
Locked objects are marked by a  special icon.
Chapter 29. Distributed Configuration Development 2-1099

Before you can add new objects to the configuration, you must lock the parent object.
For example, to create a  new catalog lock the root object of the configuration and to
create a  new form or attribute for the catalog lock the catalog object itself.
After the parent object has been locked, subordinate objects can be created.
Then every new object, along with the locked parent object, should be placed
in  the repository.

29.2.3. Object Placement in  Configuration Repository

The modified object can be stored in the configuration repository so that other
users can refresh it  in  their configurations. This  can be done with the Actions  –
Store in  Repository command. The  following dialog box is  displayed:

Fig. 452.  Object Placement in  Configuration Repository

Select the check boxes for objects to be stored in  the configuration repository.
Changes made to the objects can be entered into the multiline Comment field.
This  text can be viewed in  the configuration repository history.
If the objects contain subordinate objects that need to be stored in  the configura-
tion repository, select the Retrieve Recursively check box.
Select the Allow to Retrieve Locked check box if the specified objects should remain
locked.
In the case when objects linked to other configuration objects are stored in the
configuration repository, the entire list of these objects appears in  the dialog box.
To store new objects in the configuration repository choose an object in the
Configuration window and select Store in  Repository from the context menu.
The  window for storing objects in  the configuration repository appears.
Other objects linked to the given object can also be included in  the list. In  this case
the selected object appears in  bold in  the object list. An object cannot be stored
in  the configuration repository without updating these objects as well.
2-1100 1C:Enterprise 8.3. Developer Guide

29.2.4. Object Retrieval from Configuration Repository

To get objects changed by other users select the necessary objects in  the list of
configuration repository objects and choose the Actions – Retrieve from Repository
command. The  following dialog box is  displayed:

Fig. 453.  Object Retrieval from Configuration Repository

In the list of objects, select the check box for those objects that must be retrieved
from the configuration repository.
If the objects contain subordinate objects that need to be retrieved, select the
Retrieve Recursively check box.
If the selected object is  already locked, then selecting the Allow to Retrieve Locked
check box causes changes made to the object to be lost. In  this case the object data
are restored using data from the configuration repository.

29.2.5. Release of Object Locks

If it  is  not necessary to save the changes made to a  configuration repository object
or to render the given object to another user for modification, the object can be
released. To do this, select the Actions – Undo Lock in  Repository command.

Fig. 454.  Release of Object Locks

Chapter 29. Distributed Configuration Development 2-1101

In the second column of the list, the icon shows the difference between the configu-
ration and the configuration repository objects. If the icon is  not shown, then the
objects are identical.
If objects contain subordinate objects that need to be released, select the Retrieve
Recursively check box.
After the locks have been released, the objects are retrieved from the configuration
repository.

29.2.6. Update of Configuration Repository Object Statuses

If you need to update information about objects in  the configuration repository,
choose the Update Status command. This command updates information about
object locking and releasing as well as about any new objects in  the configuration
repository.

29.2.7. Comparison of Configuration Repository

and Current Configuration
You can compare the current configuration with the configuration repository
at any time. To do this, choose Configuration – Configuration Repository – Compare
and Merge Configuration with Repository. It  displays a  comparison dialog box (see
page 2-1073).

29.2.8. Comparison of Configuration Repository Objects

and Current Configuration Objects
Sometimes it is necessary to compare a specific object in the configuration
repository and the current configuration. To do this, choose the object in the
Configuration Repository window and select the Actions – Compare with configura-
tion object menu item.
The following question appears on the screen: Show configuration comparison
results? If the answer is  Yes, configuration comparison is  carried out, the configu-
ration comparison window appears, the line with the selected object is  activated
and the report setup dialog appears on the screen.
If the answer is  negative, the configuration comparison window is  not displayed
and no comparison is  performed.
If compatibility with version 8.3.2 is  disabled for the repository (see page 2-1093),
you can run a  selective comparison of two configuration objects without needing
to compare the entire configurations. However, selective comparison is  only avail-
able for versions of objects placed in  the repository using 1C:Enterprise 8.2.9 or
earlier. To run selective comparison, choose the Perform selective comparison with
the repository object or Perform selective comparison with the configuration object
commands from the context menu, depending on where you run the comparison
from: the configuration tree or repository history window. If you run a  selective
2-1102 1C:Enterprise 8.3. Developer Guide

comparison from the configuration tree, the object is compared with the latest
object version stored in the configuration repository. If selective comparison
is  unavailable, the platform informs the user of this through a  diagnostic message.
You can run a selective comparison for the following configuration objects:
module, template, image, WS reference, schedule, register aggregates, exchange
plan contents, style, start page working area, flowchart, form, help content, prede-
fined items, command interface fragment and role rights.

29.2.9. Save Configuration Repository as Configuration

The configuration repository can be saved as a  configuration using the Configura-
tion – Configuration Repository – Save Repository Configuration to File command.

29.2.10. Disconnection from Configuration Repository

To disconnect from the configuration repository choose the Configuration – Config-
uration Repository – Unbind from Repository command.

29.2.11. Configuration Repository History

The system of distributed configuration development supports a  history of configu-
ration object changes. The  history logs the results of object placement.
You can view every object change, compare with the current state, compare
configuration versions and retrieve the configuration of the given version from the
configuration repository.
To open the configuration repository history window, select Configuration – Config-
uration Repository – Repository History.

Fig. 455.  Configuration Repository History

A chronological list of configuration versions appears in  the table box in  the left
part of the window.
Below the list of versions is  a field to enter comments for the version.
A list of objects that have been changed, added or deleted in  the chosen version
appears in  the table box located in  the right section of the window.
Chapter 29. Distributed Configuration Development 2-1103

Multiple selections are allowed in  the version list. In  this case comments on all
chosen versions appear in  the Comment field and a  list of all objects in  the given
versions appears in  the list of objects.
You can open each object from the list in  the Repository History window to view
the history of changes and compare it  with the object of the current configuration.
This  is  done using the context menu of the object list.

29.2.11.1. Working with Configuration Repository Version

Each version of the configuration repository can be opened for viewing, loaded
in place of the current version, compared with the current version or saved to
disk. You can also compare the version of the configuration repository with the
configuration stored in  the file. Version tracking operations are carried out using
the Actions menu in  the Repository History window.
There is  a special report designed to collect information about the configuration
repository history. To create this report select Actions  –Repository History Report
in the Repository History window. The  window to enter report parameters appears.

Fig. 456.  Parameters of Configuration Repository History Report

Select the type of information grouping in the report in the Report by group.
In  each group, information is  arranged in  alphabetical order.
To group information by version number select Repository versions. To group
information by objects, select Objects. To group information by comments in  the
configuration repository history, select Repository versions comments.
Select the type of report layout (text or spreadsheet document) in  the Create as group.
Additional report parameters can be specified in  the Options group.
To exclude comment lines starting with "//", select the appropriate check box.
2-1104 1C:Enterprise 8.3. Developer Guide

To specify objects to report on as well as a date range, click the Filter button.
In  the window that opens, set the filter criteria.
To start the report generation process click OK.

29.2.11.2. Rollback to Previous Versions

Should already published versions in  the configuration repository become unneces-
sary, you can roll back to the version that you need. To do this, choose the version
which you want to roll back to in  the list of versions and select Actions – Rollback to
Version. The  following warning is  displayed: Rollback will delete information about
rolled-back versions without the possibility of recovery. Continue? Upon confirma-
tion, a  rollback is  performed which literally means that all versions stored in  the
configuration repository after the selected one are deleted from the repository.

29.2.11.3. Deletion of Old Versions

Should early versions of the configuration repository become unnecessary, they
can be deleted from the repository. To do this, choose the version up to which you
want to delete the older ones in  the list of versions and select Actions – Delete Old
Versions. The  system displays the following warning: This  operation will perma-
nently destroy information about previous versions. Continue? If the answer is  Yes,
all versions placed in  the configuration repository before the selected version are
deleted.

29.2.11.4. Merging Versions

The user can merge several consecutive configuration repository versions. To do
this, select the versions to be merged in the Repository History window (as you
select them, a  summary statement combining all comments for the selected versions
appears in  the Comment section and all objects affected by any activity in  these
versions are displayed in  the list of objects) and choose Actions – Merge Versions.
As a result a single version comprising all the changes combined from merged
version is  created in  the configuration repository history.

29.2.11.5. Assign Version Labels

Each configuration version can be labeled in the Repository History window.
To do this, select the version and choose Change in the context menu.
The  following dialog box is  displayed (see fig. 457).
Enter the label value. As you type the first symbol, the Label сomment field
becomes accessible. You can enter the label description in this field. Labels
primarily serve to mark completion of certain stages or activities (e.g., a new
configuration version release, preparation for distribution, etc.).
Chapter 29. Distributed Configuration Development 2-1105

Fig. 457.  Configuration Repository Version

29.2.11.6. Filter
A filter dialog box for the Repository History list is different from the standard
filter dialog box.

Fig. 458.  Version Filter

Versions can be filtered within a time range, range of configuration repository

versions (or combination of the above), by a  list of configuration repository users
who have placed versions in the repository, by configuration objects and by
configuration versions. You can also specify whether or not to include versions
with labels as well as only filter versions with labels.
2-1106 1C:Enterprise 8.3. Developer Guide

The left section of the Repository History window contains a  list of objects which
have been added, modified or deleted for every selected version. This  list is  always
complete for the given version (it does not depend on filter criteria). If specific
configuration objects are selected in  the filter criteria (not the entire configuration),
then the objects in  the list that meet the selection conditions are highlighted by
a  different background color.

29.2.11.7. Comparison of Configuration Repository Versions

In some cases the user might need to compare configuration repository configu-
ration versions. To do this, select two versions to be compared in  the Repository
History window (hold down the Ctrl key) and choose Actions – Compare Configura-
tion Versions or Actions – Perform selective comparison of object versions For more
information on selective comparison see page 2-1101.
The selected configuration versions are compared and the configuration comparison
window appears.

29.2.12. Object History

To view the history of object changes in  the list of configuration repository objects
or in  the Configuration window, select the object and choose Object History in  the
context menu.
The Filter Object History dialog box appears.

Fig. 459.  Filter Object History

Select the necessary filter parameters and click OK.

The object history window appears.

Fig. 460.  Object History

Each object change can be viewed, compared with the current object or compared
between the versions (you need to select two versions in  the list to do this).
Chapter 29. Distributed Configuration Development 2-1107

For every object version, you can view comments and labels in  the same way as
for configuration versions (see above) as well as retrieve the configuration of the
given version from the configuration repository.
You can filter the object version list. The  filter is  applied in  the same manner as
the configuration repository history filter described earlier in  this chapter. The  only
difference is  the selection and marking of the current object in  the list of objects.
If you need to go to the configuration repository history window, choose Configura-
tion Repository History from the Go To menu within the object history window. If
you need to open the configuration repository history window and set a  filter by
the current object, select Configuration Repository History by Object.

29.2.13. Actions with Configuration Repository without

Connection
Some actions can be performed without connection.
If the configuration is not connected to the repository, connection with the
repository must be established first. To do this, select any item from the Configu-
ration  – Configuration Repository group. The connect-to-repository dialog box
appears.

Fig. 461.  Open Configuration Repository

Specify the connection credentials and click OK.

When the connection is  established, the user is  not prompted for login credentials
again for any of the other menu items.
In the connection mode users can do anything within their rights, including viewing
configuration storage data and comparing objects and configurations as well as full
administration of the configuration storage (for users with administrative permis-
sions). Actions related to retrieving objects from the repository are not available.
When the connection is  active, users with administrative permissions can do all
operations available with the configuration repository history.
2-1108 1C:Enterprise 8.3. Developer Guide

29.3. REMOTE WORK WITH CONFIGURATION REPOSITORY

The mechanism for working remotely with the configuration repository enhances
the distributed configuration development potential:
„„ Configuration repository can be located on a  PC under Windows or Linux.
„„ Configuration repository can be accessed by both LAN users (tcp) and Internet
users (http).
For application designers there is  no difference between working remotely with the
configuration repository and working with the configuration repository located at
a  shared network resource, except for some features covered by on page 2-1119.
NOTE
The mechanism of remote working with the configuration repository is  mainly
intended for high-bandwidth connections. It  should also be taken into account
that if remote access is  used, operations with a  significant data exchange volume,
e.g., getting a  full version of the configuration repository, may last considerably
longer.

29.3.1. Architecture Overview

Working remotely with the configuration repository is supported by a special
application – the configuration repository server. The  PC where the configura-
tion repository server application (crserver.exe for Windows or crserver for Linux)
runs is  also called the configuration repository server. Depending on the access
protocol (TCP or HTTP), various patterns may be used for remote interaction
between the client application and the configuration repository. At the same time
concurrent work with configuration repository is supported, both remote and
local – as with a  shared file resource.

Fig. 462.  Remote Configuration Repository

Chapter 29. Distributed Configuration Development 2-1109

29.3.1.1. General Flowchart for Working with Configuration Repository

Generally, 1C:Enterprise supports concurrent work with the configuration reposi-
tory by means of all access protocols: file access, TCP protocol and HTTP protocol.

Fig. 463.  Interaction with Remote Configuration Repository

The same configuration repository server provides clients with the possibility of
working with different configuration repositories. The only limitation is that all
configuration repositories have to be located in  the same root directory.

Fig. 464.  Location of Various Repository Files

2-1110 1C:Enterprise 8.3. Developer Guide

29.3.1.2. TCP Interaction

When TCP is  used, the client application interacts with the configuration repository
server, while the latter, in  turn, interacts directly with the configuration repository.

Fig. 465.  TCP Interaction

29.3.1.3. HTTP Interaction

When HTTP is used, chain interaction takes place: client application – web
server – configuration repository server – configuration repository.

Fig. 466.  HTTP Interaction

29.3.2. Configuration Repository Server Installation

Configuration repository server installation is described in detail
in  "1C:Enterprise 8.3. Administrator Guide".
After the configuration repository server is  installed, the user on whose behalf the
configuration repository server is  operated must have write and read rights for the
Chapter 29. Distributed Configuration Development 2-1111

directory where the configuration repository is located (1Cv8DDB.1CD file and

data directory).

29.3.3. Web Server Setup for Work

with Configuration Repository
If remote interaction with configuration repository via HTTP is planned, then,
in addition to setting the configuration repository server, the Web server also
should be set up for interaction with the 1C:Enterprise system and the configuration
repository server. The  following actions must be taken to set up the web server:
„„ record the web server extension modules
„„ record the virtual application on the server
„„ publish the configuration file for working with the configuration repository
server
NOTE
The web server must have ISAPI extension support installed.
Publication of the configuration file for working with the configuration reposi-
tory server implies placing the 1ccr file in  the virtual directory of the web server.
For instance, the name of such a configuration can be storage.1ccr (for a file
description refer to "1C:Enterprise 8.3. Administrator Guide") and it  can have the
following content:
<?xml version="1.0" encoding="UTF-8"?>
<storage connectString="tcp://RepServ"/>

Administrator’s rights are required to set up the web server.

NOTE
The repository server is  a 32-bit application, so when working through the server
you should either use 32-bit operating systems and web servers or allow the
Microsoft Internet Information Services web server to execute 32-bit modules.

29.3.3.1. For Microsoft Internet Information Services web server

This section describes the settings for different versions of the Microsoft Internet
Information Services web server (hereinafter "IIS").

For IIS version 5.1, 6.0

You should create a  virtual directory. To do this, use the virtual directory crea-
tion wizard from the Default Web Site context menu item (Internet Information
Services  – <Name of computer that runs the web server>  – Web Sites  – Default
Web Site). Select the New – Virtual directory context menu item.
2-1112 1C:Enterprise 8.3. Developer Guide

Fig. 467.  Defining the virtual directory name

The name specified in  the Alias field will be used in  generating URL access to the
repository. Then specify the name of the folder with the files of the directory that
you are creating.

Fig. 468.  Specifying the directory

The next step is to specify which actions should be permitted with regard to
working with the directory. You should allow Read and Execute (such as execu-
tion of ISAPI applications or CGI). Other rights should be disabled.
Chapter 29. Distributed Configuration Development 2-1113

Fig. 469.  Setting permissions

The next step is  to click the Finish button. This  completes the process of virtual
directory creation. Then you should set up the directory created and record the web
server extension for this directory. To do this, open the properties of the virtual
directory created and click Setting in  the dialog that opens.

Fig. 470.  Recording web server extension

The IIS web server extension can be the wsisapi.dll dynamic library located in  the
bin directory of the specific 1C:Enterprise version.
2-1114 1C:Enterprise 8.3. Developer Guide

TIP
To record the web server extension, use either a short path ("format 8.3") or
install 1C:Enterprise in  the directory that does not contain spaces or directory
names exceeding 8 characters.
You can specify either a  specific extension (.1ccr), or a  mask of all files (*) as the
extension (the Extension: field in  the dialog in  fig. 470).
The last step is  to restart the web server.

For IIS version 7.0, 7.5

You should create a  virtual application. To do this, use the virtual application crea-
tion wizard from the Default Web Site context menu item (<Name of computer with
web server> – Sites – Default Web Site). Select the Add Application… context menu
item.

Fig. 471.  Creating the virtual application

The name specified in  the Alias field will be used in  generating URL access to the
repository.
Then add the handler for .1ccr files. To do this, select <Name of computer that runs
the web server>  – Sites  – Default Web Site  – storage  – Handler Mappings  – Add
Script Map.
The IIS web server extension can be the wsisapi.dll dynamic library located in  the
bin directory of the specific 1C:Enterprise version being used.
You can indicate either a  specific extension (.1ccr) or a  mask of all files (*) as the
extension (the Request path: field in  the dialog in  fig. 472).
The last step is  to restart the web server.
Chapter 29. Distributed Configuration Development 2-1115

Fig. 472.  Adding the handler

29.3.3.2. For Apache web servers

To setup the Apache web server to work with the configuration repository, take the
following actions:
„„ Include the loading of the web server extension module into the web server
configuration file (httpd.conf). Names of extension modules vary depending on
the web server version and the operating system used:
○○ For Windows:
□□ For Apache 2.0: wsapch2.dll
□□ For Apache 2.2: wsap22.dll
○○ For Linux
□□ For Apache 2.0: wsapch2.so
□□ For Apache 2.2: wsap22.so
The identifier of the web server extension module is _1cws_module.
To load the module, you must enter the following string of the LoadModule
_1cws_module <path to web server extension module> type in  the
configuration file.
Example for Windows:
LoadModule _1cws_module "C:\Program Files\1cv8\8.3.1.100\bin\wsap22.dll"
2-1116 1C:Enterprise 8.3. Developer Guide

Example for Linux:

LoadModule _1cws_module /opt/1C/v8.2/i386/wsap22.so

„„ Create a  virtual directory on the web server to provide access to the configura-
tion repository and record the file handler for the virtual application directory.
The  identifier of the handler being recorded is  1c-application.
Sample virtual directory for Windows:
Alias "/repos" "C:\www\repos\"
<Directory "C:\www\repos\">
AllowOverride None
Options None
Order allow,deny
Allow from all
SetHandler 1c-application
</Directory>

Sample virtual directory for Linux:

Alias "/repos" "/var/1C/www/repos"
<Directory "/var/1C/www/repos">
AllowOverride None
Options None
Order allow,deny
Allow from all
SetHandler 1c-application
</Directory>

„„ Add the *.1ccr file to the folder with the virtual directory files and specify the
address of the configuration repository server in  this file (tcp scheme).
.1ccr sample file:
<?xml version="1.0" encoding="UTF-8"?>
<repository connectString="tcp://192.168.0.12"/>

„„ Restart the web server

29.3.4. Launch of Configuration Repository Server

In the Windows environment, the configuration repository server can be launched
as an application or installed as a  service.
In the Linux environment, the configuration repository server can be launched as
a  process or a  daemon.
Chapter 29. Distributed Configuration Development 2-1117

29.3.4.1. Windows OS
The configuration repository server is  launched via the command line:
crserver.exe -instsrvc | -rmsrvc -usr <user> -pwd <password>
- start | -stop
-port <port> -d <directory>

If server storage is  installed as a  service, it  is  called 1C:Enterprise 8 Configura-
tion Repository Server.
IMPORTANT!
The option name and its value should be separated by a  space.

-start
Start server repository service.
-stop
Stop server repository service.
-instsrvc
Register server repository as a  service.
-rmsrvc
It removes registration of the server as a  service.
-usr
Name of the user registering the service. This  user should be assigned the Log
on as a  service right. Additionally the user must have read access rights to the
executable files directory in  the relevant 1C:Enterprise version and full access
rights to the configuration repository root directory (%APPDATA%\1C\1cv8\ by
default or the directory indicated by the -d switch).
-pwd
Password of the user registering the service.
-port
Operation port of the configuration repository server. 1542 is  used by default.
-d
Root directory for configuration repositories. %APPDATA%\1C\1cv8\ is used
by default.
2-1118 1C:Enterprise 8.3. Developer Guide

29.3.4.2. Linux OS
The configuration repository server is  launched via the command line:
./crserver -daemon -port <port> -d<directory>

IMPORTANT!
Parameter name and value should be separated by a  space.

-daemon
The server is  launched as a  daemon.
-port
Operation port of the configuration repository server. 1542 is  used by default.
-d
Root directory for configuration repositories. /home/usr1cv8/.1cv8 or ~/.1cv8
is  used by default.

29.3.5. Connection to Configuration Repository Server

Client connection to the configuration repository for remote work is similar to
the connection procedure for working with the configuration repository located at
a  shared network resource. The  only difference lies in  the method of specification
for the configuration repository directory. Depending on the protocol, a  configura-
tion repository directory can be specified in  two ways:
For TCP protocol:
tcp://<configuration repository server name>/<relative path to configuration repository>

For HTTP protocol:

<Web service description file address>/<relative path to configuration repository>

Example:
tcp://RepServ/MyConfRep

Or:
http://www.MyCompany.ru/VirtualFolder/storage.1ccr/MyConfRep

„„ RepServ – configuration repository server name;

„„ http://www.MyCompany.ru – the Web server address where the Web service
description file is  published;
Chapter 29. Distributed Configuration Development 2-1119

„„ http://www.MyCompany.ru/VirtualFolder/storage.1ccr – full HTTP Web service

description file address;
„„ MyConfRep – relative path to the configuration repository.
The relative path starts from the default directory ((%APPDATA%\1C\1сv8\) if the
directory has not been specified explicitly or from the directory specified in  the
-d switch when launching the configuration repository server. If the relative path
to the configuration repository is not specified, then connection to the default
configuration repository is  established (maincr directory).
If you work with a  configuration repository server, the repository server and the
Designer versions should match. The  repository will be unavailable for work if the
designer and configuration repository server versions mismatch.

29.3.6. Creation of Configuration Repository

The default directory for configuration repository placement is  created during the
first launch of the configuration repository server. The default directory name
is  maincr. If no -d switch has been used when launching the server, then the config-
uration repository is  located in  the default directory, i.e. %APPDATA%\1C\1сv8\
maincr.
For a new configuration repository, create a configuration repository from the
client application in  the Designer mode and assign the required new directory as
a  configuration repository directory.
For maximum performance, the recommended placement for the configura-
tion repository root directory is on the configuration repository server.
The 1C:Enterprise system supports the placement of configuration repository
directories at network resources accessed by the configuration repository server.
However, using this option may lead to lower performance.

29.3.7. Remote Work with Configuration Repository

(Special Features)
No automatic object status update is performed in the configuration repository
during remote work with the configuration repository. To update details for objects
placed in  the configuration repository run the Actions – Update Status command.
Active users working with the configuration repository remotely are not shown
in  bold in  the configuration repository user list.
2-1120 1C:Enterprise 8.3. Developer Guide

29.4. RECOMMENDATIONS ON HOW TO USE CONFIGURATION

REPOSITORY
Distributed development is  done best when developers leave comments on their
work and maintain a  list of changes so that other developers can understand the
changes.
A simple way to leave comments on the changes is to create a text report
describing the difference between the current working configuration and the reposi-
tory configuration (only on objects placed in  the repository) and store this report
in  an accessible place.
The configuration repository administrator should periodically back up the reposi-
tory data and change the reports created by the developers (the timeframe depends
on the development progress).
If a  configuration comparison window is  open, performing group operations with
the repository (obtaining objects, placing objects, etc.) and disabling configuration
support are not recommended.
Chapter  30

CONFIGURATION
DISTRIBUTION AND SUPPORT

Standard configurations are periodically modified. It  may be caused by changes

in  legislation, addition of new features or modifications of the program. Therefore,
the configuration support method is  very important for users of standard configura-
tions.
Distribution, support and distribution kit terms are used to describe support mecha-
nisms.
Distribution. There are two types of distribution – full distribution and update
distribution. Full distribution is  a specially organized configuration file using the
*.cf format. An update distribution is  a file that contains only updates. It  uses the
*.cfu format.
Support. Configuration support means the capability of the Designer to update
the configuration using distribution files. The  support mechanism should provide
protection of the logical integrity of a  configuration. The  description also uses the
supported configuration term.
Distribution kit. A distribution kit contains the setup.exe installation program and
distribution files in  the 1cv8.efd archive. The  distribution language is  the same as
the Designer language (localized distribution resources are located in  a subdirec-
tory named after a  language in  the distribution directory).
Developers of typical configurations may use the Designer to prepare distributions
of new configuration versions and to enable support of these configurations consid-
ering modifications in  user configurations.
2-1122 1C:Enterprise 8.3. Developer Guide

30.1. DISTRIBUTE CONFIGURATION

30.1.1. Distribution Set Options
To configure a  distribution you have to specify vendor rules for the configuration
object modification by the developers that support the end user configurations.
Use the Configuration – Distribute Configuration – Distribution Options command to
configure rights. The  distribution setup dialog will open:

Fig. 473.  Distribution Set Options

Only the first level objects are available in  the hierarchical list of configuration
objects.
You have to specify a  modification rule for each object. To do it  select an object
and click the Edit button. To change the rules for a  group of objects, select a  group
and click the Change Subordinate button.

Fig. 474.  Vendor Rules Setup

Chapter 30. Configuration Distribution and Support 2-1123

You may make multiple selections in  the object tree. In  this case a  new setting
is  applied to the selected objects.
The following rules can be specified:
„„ Changes allowed – all user configuration changes are allowed.
„„ Changes not recommended – user configuration changes are not recommended.
„„ Changes not allowed – all changes are forbidden. This  right makes it  impos-
sible to modify supported objects. It is impossible to disable support for an
object with this rule. To modify such an object the user would need to disable
support for the entire configuration.
„„ Inclusion in  configuration not recommended – when support is enabled by
merging with a  provider configuration or updating with a  new provider config-
uration, the object with this rule is by default not prompted to be included
in  the user configuration.
By default the Designer uses the Changes allowed rule.
Check the Include source texts of object modules to distribution option if the distri-
bution contains only the compiled module text. In  this case the functionality will
not change, but module text will not be available for viewing.
Uncheck the Include source texts of object modules to distribution option if the
distribution contains only the compiled module text. In  this case the functionality
will not change, but module text will not be available for viewing. Exclusion of
source texts is  not supported for the following modules:
„„ managed application module
„„ form modules
„„ command modules
„„ modules containing preprocessor instructions
„„ common client modules in  the managed mode (thin client, web client and thick
client's managed mode).
NOTE
If the Include source texts of object modules to distribution checkbox is  unchecked for
the root configuration element, the normal application, external connection and
session modules will be distributed without source texts.
Check the Distribution file can be used for updates option for a  distribution file if
it  is  intended for a  regular configuration update. Uncheck this option if you plan
to use this distribution file as an intermediary in  cases when a  sequence of updates
is needed.
For example, if you change an attribute directly, this may cause data loss for some
users. Therefore, it  is  often necessary to use an intermediate version where a  new
attribute is  added without deleting the old attribute. Usually only the update file
is prepared. Data conversion is performed by a special handler. Then another
configuration update is  applied where the name of a  new attribute is  changed to
2-1124 1C:Enterprise 8.3. Developer Guide

the name of the old attribute. The  second version is  used only as an intermediate
procedure and it  cannot be used as an independent update.
Click the Close button after specifying the relevant rights.

30.1.2. Creation of Distribution Files

Use the Configuration – Distribute Configuration – Create Distribution Package and
Configuration Update File command to create distribution and update files.
The Vendor and Version properties in  the Development category must be config-
ured before you can create a  distribution.
Vendor – name of the configuration vendor.
Version – configuration version (line).
TIP
The recommended structure of the version number is: <version>.<subversion>.
<release>.<build>, where items of the structure are decimal numbers. This  struc-
ture simplifies identification of the configuration version during sequential
development and creation of distribution files (kits).
The lists of configuration templates and updates are sorted by configuration version
number based on the number structure.
If a configuration or a database is modified, the Designer requires saving the
configuration and refreshing the database configuration.
The distribution creation window will open (see fig. 475).

Fig. 475.  Distribution Creation

Click Distribution files directory to create a  directory for creating new distribution
directories. The  version directory name is  the same as the version number.
Check Create distribution file to create a  distribution file. A default distribution file
name will be suggested.
Chapter 30. Configuration Distribution and Support 2-1125

Check Create configuration update file to create an update file. A default update file
name will be suggested.
If you check the Create configuration update file option, you have to include
previous updates in  this file. Use the Add from Previous Versions command and
choose previous versions of distribution files to include previous updates to the
new update.
Click Run to create the specified files.
A distribution kit generated in  Windows OS is  not fully functional in  Linux OS,
since the Windows file system does not support setting the Run (X) attribute for
the setup file intended for Linux. This  means that, to be able to launch the setup
application, you need to set this attribute for the setup file either after you copy
the installation kit to a  computer running Linux or when you create a  setup disk
image. You should set the Run attribute in Linux. The installation program for
Linux (setup) can be launched in  both a  32-bit version and 64-bit version.
Text files of the distribution kit are to be encoded in  UTF-8.
These files are passed to developers responsible for the end user configuration
support.

30.1.3. Preparing Distribution Kits for Standard Configurations

To create a  distribution kit you have to generate a  kit description (stored in  a file)
and create a  distribution kit based on this description.

30.1.3.1. Distribution Kit Description

Use the Configuration – Distribute Configuration – Distribution package command to
create a  distribution kit description.
It will display a  dialog box (see fig. 476).

Fig. 476.  Distribution Package Description Selection

Select the description entry mode in  this dialog box.

Check the Open distribution package description option if you want to edit an
existing description. Enter the name of the description file into the text box.
Check the Create new distribution package description option to create a new
description.
2-1126 1C:Enterprise 8.3. Developer Guide

Creation of New Distribution Kit Description

Description wizard window will open:

Fig. 477.  istribution Kit Description Wizard

Specify the distribution kit name and vendor name. Click Next >.
Specify template parameters at the next step.

Fig. 478.  Creation of Distribution Kit Description

By default (the Determine Options Based on Current Configuration box is  checked)
parameters are selected from the corresponding configuration properties. If this
option is  not checked, you may edit these parameters.
The Path parameter specifies a  directory where a  manifest file will be created.
Template parameters are recorded in  the manifest file which is  a part of the distri-
bution kit. For information about manifest file structure see "1C:Enterprise 8.3.
Administrator Guide".
Specify template parameters at the next step (see fig. 479).
Mark the template files that should be included in  the distribution kit description.
Specify a  directory for additional files in  the kit. All files in  this directory and its
subdirectories will be included in  the distribution kit.
Chapter 30. Configuration Distribution and Support 2-1127

Fig. 479.  Setting Template Parameters

Click Done to create the description. The distribution kit description editing

window will open.
Editing Distribution Kit Description
The distribution kit description editing window is opened when you create
a  description (see above) or when you choose the edit mode (see page 2-1125).

Fig. 480.  Distribution Kit Description Editor

The distribution kit description editing window is used for distribution creation
purposes.
Description represents a  tree that consists of four main branches:
„„ configuration templates
„„ distribution options
„„ home directories
„„ languages
You may add, modify or delete any data at any branch. Use the Actions menu to
manage the description tree. Use the properties palette to edit properties.
2-1128 1C:Enterprise 8.3. Developer Guide

Configuration Templates
Configuration templates are the main items of the distribution kit. Configuration
templates consist of files and file groups.
Files may include arbitrary files (or file sets that are determined based on a  mask)
and configuration files or data dumping files obtained from the current infobase.
Each template is  placed in  the template directory. All files and file groups are also
placed in  the template directory based on the manifest file address (file groups are
represented as subdirectories).
The manifest file contains only configuration files and data dumping files.
The  other files are placed in  the configuration template directory.

Templates
To set up template properties choose a  template and specify its properties.
Current configuration – when you check this option, the data (vendor, name and
version) are picked from the current infobase. If this option is  not checked, you
may edit these properties.
„„ Vendor – configuration vendor (the same as the Vendor configuration property).
„„ Name – configuration name (the same as the Name configuration property).
„„ Version – configuration version (the same as the Version configuration prop-
erty).
„„ Location of manifest – relative path to the template manifest file in  the template
directory.
Files and File Groups
To add a  file pick a  template and run the Actions – Add command. The  file selec-
tion dialog will open.

Fig. 481.  Add File to Template

Location of the template item to be added is  specified in  the dialog box.
The file can be located in  the current configuration, in  the current infobase, in  a
separate file or may be a set of files in a specified directory picked based on
a  mask (subdirectory files may be included).
Chapter 30. Configuration Distribution and Support 2-1129

To configure file properties select a  file and specify its properties:

„„ Description – file description.
„„ Data – data source for a  file (file, current configuration or current infobase).
„„ Home Directory – home directory for file reference.
„„ File/Directory – relative (for home directory) or absolute path to a  file.
„„ Place on support? – enable support for a  configuration file or data dumping
file.
„„ Include in  manifest – include configuration file or data dumping file in the
manifest file.
„„ Name in  template – name in  template directory. The  name is  localized to all
languages supported by the installation kit.
„„ Location – default directory for the infobase.
„„ Name for updates – use name of the file in  template directory as a  source for
naming updates.
To add a group of files select a template and run the Actions  – New Folder
command. Specify the group name in  the properties palette.
If you select a  group and use the Actions – Add command, a  file will be added to
this group. A group may contain an unlimited number of files.
You may create embedded groups of files.

Distribution Options
Distribution options contain different combinations of distribution files. Such
a  combination may be used for different distribution contents (e.g., full distribution
vs. update distribution).
„„ Description – name of distribution option.
„„ Distribution files – set of distribution files. By default a  full version containing
all files is  created. If you specify several options, you may specify a  set of files
for an option using the Edit link in  the properties palette. Check the files that
will be added to the selected distribution option.
„„ Distribution description file – description that is  shown to user when the product
is installed.
Home Directory and Directory – these
parameters specify location of distribu-
tion kit or distribution files. If you
specify these directories, they are auto-
matically added in  the prompting dialog
box for kit creation.

Fig. 482.  Creation Option

2-1130 1C:Enterprise 8.3. Developer Guide

Home Directories
Home directories are used to specify the distribution files that are moved between
different computers.
You may specify an environment variable or directory name as the home directory.
Then you may specify the distribution file name as a combination of the home
directory and relative path from the home directory.
„„ Description – name of the home directory.
„„ Home – can have one of two values:
○○ Environment variable;
○○ Directory.
„„ Environment variable/Directory – contains name of environment variable or an
absolute path to a  directory depending on the value of the Home property.
Languages
Languages are used to show localized names of template items.
To display the names correctly it is necessary to create languages in accord-
ance with the directory names in the 1C:Enterprise platform containing the
corresponding localized interfaces. One of the languages is  considered a  default
language (a localized line in  the default language shall be used if no line corre-
sponding to the current platform language is  available).
„„ Name – language name.
„„ Resource directory – language resource directory for this language.

30.1.3.2. Creation of Kit

Use the Actions – Create Package command to create a  kit. A distribution kit for
the selected distribution option will be created.
Use the Actions  – Create package files command to create a kit of distribution
files. Distribution files (unpacked) will be created for the selected distribution
option without an installation program.
The Designer offers to save the kit description if it  has not been saved yet.
If you specify more than one option, the option selection dialog box is  opened.
Select one option from this dialog box.
New update kit files have to be placed in  the resource directory specified in  the
Update directory address property (see page 2-1136).
In addition to licensing with dongle protection where the total number of seats
is  limited and the configurations in  use are not controlled, electronic licenses can
be applied which are issued per seat and allow you to control the use of specific
configurations listed in the license. Software licenses are available from 1C
Company licensing center and are stored in  the user's computer.
Chapter 30. Configuration Distribution and Support 2-1131

NOTE
To create a  distribution kit for a  configuration distributed via licensing per
user seat, the -DigiSign option is implemented for CreateDistributionFiles and
CreateDistributive command-line keys, allowing you to specify a  file with licens-
ing parameters. The  creation and distribution of configurations supporting per-
user-seat licensing can be enabled for a  partner based on a  separate agreement
with 1C Company.

30.2. CONFIGURATION SUPPORT

You may obtain a  new version of the configuration as a  distribution file (a distri-
bution file of the new configuration version and/or update).
User configurations that may be updated with received distribution files have to be
supported.
You may change the object support mode if you disable full support first.
The  ability to set user rules (for object modification) depends on rules stipulated
by the vendor and on current locks in  the user configuration.
The following features are available for a supported configuration: comparison
with distribution, comparison of a new distribution with an earlier one and
comparison of the current configuration state with its initial one.
If the configuration is  supported, objects in  the Configuration window are marked
with special icons located at the right side of the objects near the window border.

Fig. 483.  Support Mode Icons

Icons for various support modes are shown on fig. 483.

2-1132 1C:Enterprise 8.3. Developer Guide

30.2.1. Setting Configuration Support

When a  standard configuration is  installed, configuration support is  automatically
turned on for this configuration.
If the configuration is  not supported, use the Configuration – Compare and Merge
with Configuration from File command and select the distribution file as a  file for
comparison to turn on configuration support.
In this case the Designer offers to turn on the support for the configuration.
A dialog box with the Possible merger with enrollment for support detected message
is  opened. This  dialog box contains main parameters of the vendor configuration.
The  system asks the user whether support should be turned on.
If you click the Yes button, the configuration comparison and merging window will
open.
Click Execute after specifying merge conditions and modes. Configurations are
analyzed object-by-object to determine compliance of vendor rules with merging
rules.
If vendor rules for any objects conflict with merging rules, a  list of these objects
is displayed in a separate window. Use the comparison window to adjust the
settings to eliminate all conflicts and repeat merging.
If there are no rule conflicts, configurations are merged and support is  turned on
for the current configuration.
When vendor configuration change is enabled, enabling support and updating
vendor configuration with enabled changing functionality, there is an ability to
configure default support rules in the details for objects with different support
rules.
If the current configuration is connected to the configuration repository,
it is required that all configuration objects (which should all be taken from the
vendor configuration) and the root configuration object are locked in  the repository
when a  configuration is  set for support.

30.2.2. Support Setting

Support setup consists of setting user rules for each configuration object.
Use the Configuration  – Support  – Support Options command for support setup.
The  support rules setting window will open (see fig. 484).
In the upper line of the window, the Designer displays the current support state for
the current configuration.
Below is  the configuration name, vendor and current configuration version.
The Object Support Rules Settings section contains the object tree, vendor support
rules and user rules for each object.
Chapter 30. Configuration Distribution and Support 2-1133

Fig. 484.  Support Setting

Vendor support rules cannot be changed. Only user rules can be changed (if the
configuration is  not under full support). You may make multiple selections in  the
settings window to configure the same support rules for selected objects. Use the
context menu in  the support rule columns to change the support rules.
A distribution file may contain information in  several languages. Use the support
language selection feature to specify the languages that are used in the current
configuration. Click the Support Language button to open the language selection
window.

Fig. 485.  Selection of Configuration Support Languages

2-1134 1C:Enterprise 8.3. Developer Guide

30.2.2.1. Full (Automated) Support

If you see This  configuration is  under support in the status bar of the support
setting window, it  means that all objects of this configuration are supported and
may not be modified (edited). In  this case you may refresh the configuration auto-
matically.
To update the current configuration automatically:
„„ Select Configuration – Support – Update Configuration.
„„ Select a  support file.
The update is  performed automatically and the Compare and Merge window is  not
opened.
In this state it is impossible to change user rules for any configuration objects
regardless of vendor rules.

30.2.2.2. Support with Updates

Often it is necessary to change the standard configuration to meet the require-
ments of a  specific user. In  such cases support of some objects has to be cancelled
completely (the vendor object is not supported) or partially (the vendor object
is  editable with the possibility of support).
To access user support rules, click Enable modification in the support setting
window.
After clicking this button, you will see the following warning: If you change the
mode you will not be able to perform complete configuration update automatically.
Continue? If you click Yes, you are prompted to select support rules for objects
with different distribution rules.

Fig. 486.  Support rules configuration

When you specify support rules and click OK, the configuration status is  changed
and it  will be supported with the ability to make changes. In  the result, all config-
uration objects will be locked from random changes regardless of the distribution
Chapter 30. Configuration Distribution and Support 2-1135

rules set by the provider. Now, to change the object you need to explicitly enable an
ability to change the object or its subordinate objects (see page 2-1135).
If you do not need to change the support mode (the actions were performed by
mistake), close the configuration without saving.
After canceling full support, you can turn it  on again for the entire configuration
only as follows:
„„ disable support for the configuration (select the root configuration object in  the
settings window and use the Actions – Cancel Support command);
„„ run the Configuration – Load Configuration from File command;
„„ select a  distribution file.

Change of Object Support Rules

To change support rules you have to select an object in the object tree of the
settings window and pick the Set Support Rule command from the context menu.
Select the required user rule out of three available user rules:
„„ vendor object is  not editable;
„„ vendor object is  editable, support is  enabled;
„„ vendor object is  not supported.
Availability of these rules depends on the vendor support rules.
If the vendor support rule Changes allowed is  turned on, you may use any vendor
rules.
If the vendor support rule Changes not recommended is  turned on, setup of any
vendor rule is  available, but if you modify this rule, a  warning is  displayed.
If the vendor support rule Changes not allowed is  turned on, you may not set up
any vendor rules.
IMPORTANT!
Please remember that when you turn on the Support cancelled for cendor object rule,
you may not "return" to the Vendor object changes not allowed rule.
If the selected object contains several subordinate objects, check the Apply to all
subordinate objects option to modify the support rules for these objects as well.
Completely disabling support. To disable support for all configuration objects,
use the Actions – Cancel Support command. You will see the following warning:
Removal from support will make it  impossible to obtain update from vendor.
Continue? Click Yes to disable support. The configuration will no longer be
supported. If this action has been performed by mistake, close the configuration
without saving.
IMPORTANT!
You may update the configuration using the comparison and merging method
even when support is  disabled.
2-1136 1C:Enterprise 8.3. Developer Guide

Compare and Merge with Vendor Configuration

The user can perform comparison and merging of the current configuration with the
original (previous) distribution file in  the support setting window. To do this, click
the Compare, merge button. The  comparison and merging window will open.

Fig. 487.  Compare and Merge with Vendor Configuration

For more information about comparison and merging see page 2-1057.
Unlike the "standard" configuration comparison and merging mode, the comparison
window contains a  line for vendor and user rules and the Edit button for changing
user rules.
When you compare the current configuration with the distribution file, the current
configuration is  always a  descendant of the vendor configuration. Therefore, the
configuration setup mode selection button is  not available.

30.2.3. Configuration Update

Use the Configuration  – Support  – Update Configuration command to update
a  supported configuration.
The update wizard will open.

Fig. 488.  Update Wizard

Chapter 30. Configuration Distribution and Support 2-1137

At the first screen, the user may select a  separate update file for the configuration
update or search possible locations of update files.
If you select a  separate update file, you have to choose it  on the next step.

Fig. 489.  Update File Selection

When you click Ready, a  dialog box with main parameters of the current configu-
ration and vendor configuration (see below) will open.
If you select the update search option, click Next > to specify possible update loca-
tions in  the update wizard.

Fig. 490.  Update Locations

Possible update locations include:

„„ current template directory;
„„ removable disks (the v8updates directory is  added for CD-ROM disks);
„„ address specified as the update directory address in  the configuration.
Selected directories are searched for updates as follows:
„„ Specified local directories and subdirectories are searched for update files and
template list files. Found template list files should describe the template directo-
ries and should be located at the root of these directories.
2-1138 1C:Enterprise 8.3. Developer Guide

„„ Specified remote directories are searched for template list files. Other directo-
ries (subdirectories) are not searched.
If the Update directory address configuration property contains an address that
can be used to obtain the configuration update, clicking Next  > invokes the user
authentication procedure.

Fig. 491.  Internet Resource Access Authentication

You have to enter the username and password to access the server with update set.
You also have to enter the username and password for the proxy server if required.
At the third step, you will see updates for which templates have been found. Files
that most probably can be used for configuration updates are marked in  bold.

Fig. 492.  Update Selection

If you pick an update in  a remote directory, this update is  copied to the current
template directory (if it  is  local).
Click Finish to finish searching for update files.
A dialog box with main parameters of the current configuration and vendor
configuration will open.
Chapter 30. Configuration Distribution and Support 2-1139

Fig. 493.  Update Parameters

Click OK to continue.
The Designer compares the configurations and opens the Update Configuration
window.

Fig. 494.  Update Configuration

For more information about comparison and merging see page 2-1071.
In addition to standard fields for comparison and merging, this table box contains
two more columns that show the object history status. The  status icon drill down
is  provided in  the lower part of the window. The  icons can be used to easily find
out what changes have been made and to determine the affected configuration.
2-1140 1C:Enterprise 8.3. Developer Guide

For example, the figure demonstrates that the Address and Phone attributes have
been added to the Competitors catalog in  the main configuration, while attributes
of the Nomenclature and Units of Measure catalogs have been changed in the
vendor configuration. The  Address and Phone attributes have also been added to
the Competitors catalog, but their order differs from that in  the main configuration.
Pick an object in  the table box to view vendor rules. The  rule is  displayed in  an
attribute below the table box.
To analyze configuration changes it  is  convenient to use a  special filter that can
be called using the Filter button. The  settings window will open:

Fig. 495.  View Filter Settings

You may use a  filter to examine the configuration changes by selecting objects for
comparison and specifying difference display modes.
The main (current) configuration, the new vendor configuration and the old vendor
configuration may be used as comparison objects. Therefore, the filter setting
window consists of three sections with similar attributes. Each section is  used to
configure the comparison mode for any pair of configurations.
You may use a  filter to configure the differences display mode for all configura-
tions.
You may use a  filter template for more convenience. A template contains the most
commonly used settings.
The user makes the decision regarding merging based on the information on
changes and support rules.
Chapter 30. Configuration Distribution and Support 2-1141

30.2.4. Template Directory Description File

If configuration templates (updates included) are located at HTTP(S) or FTP
resources, the user is  required to specify a  list of configurations for each resource.
This  can be done in  the template directory description file, v8cscdsc.lst. This  file
is  stored in  the root template directory for configuration located at HTTP(S) or
FTP resources.
It is  used to determine whether updates are available at a  resource when Configu-
ration – Support – Update Configuration is  selected.

Fig. 496.  Creation of Template List File

Select Configuration – Support – Configuration and Update Templates to create and

edit a  template directory description file.
The Directories table lists template directories obtained from the file 1CEStart.
cfg (for details on 1CEStart.cfg see "1C:Enterprise 8.3. Administrator Guide").
The  Templates table lists templates from the selected template directory.
Editing configuration template directory involves deleting template items (or entire
templates along with their items) and adding configuration templates from other
directories.
Select Add in the command bar of the Templates table to add templates to the
directory. A wizard for choosing a  directory and template items will open.
Choose the source directory and items missing from the current directory.
Select Delete in the command bar of the Templates table to delete templates
from the directory. The  deletion dialog box will appear. Select the required dele-
tion method (only specified items or entire templates that contain these items)
and click OK.
2-1142 1C:Enterprise 8.3. Developer Guide

To create template directory description file use the Create Template List File
command in the command bar of the Templates table. You have to run this
command to save changes in  the template directory description.
After this move the template directory (and the directory description file) to the
required external resource.
The following approach is generally applied to work with templates located at
HTTP(S) or FTP resources:
1. A directory that will store templates published at external resources is  created
on the local drive.
2. All templates to be placed in  external resources are added to this directory.
3. The Designer (Configuration template directories window, see above) adds the
template directory created on step 1 to the Directories: list.
4. Template directory description file is created in the Configuration template
directories window (Create Template List File button). To do this, place the
cursor over the template directory added on step 3.
5. Then move the template directory (and the template directory description file)
from the local directory to the HTTP(S) or FTP resource.
Chapter  31

SERVICE FEATURES

1C:Enterprise has abundant service features and modes. They are described in  this
chapter.

31.1. WINDOW MANAGEMENT

31.1.1. State (Window Placement Mode)
31.1.1.1. Setting Window Placement Mode
Windows can be placed on the screen in  various ways, including:
„„ normal location in  which a  window is  displayed only inside the working area
of the program;
„„ floating location in  which a  window can freely move around the screen (not
only inside the work area of the program);
„„ docked location in which a window is "pinned" to the borders of the work
area of the program;
„„ auto-hide location.
To change the window placement mode select the desired mode from the context
menu of the window header.
Floating windows are always displayed on top of windows in all other modes.
If there are several windows in Floating mode, the active window is always
displayed on top of other windows.
In the MDI and Floating modes, you can attach windows to each other. If a  pair of
windows in  the same state have the Dockable property turned on (in the context
menu of the window header), these windows can be attached to each other.
To attach windows in  the MDI state to each other, press the Shift key when moving
the windows. You can also dock windows that are already docked to each other.
2-1144 1C:Enterprise 8.3. Developer Guide

If the Dockable property is  not turned on, you cannot select the Docked or Autohide
modes.
For the Docked and Autohide modes, the Dockable property is  always turned on
and cannot be disabled.
The Docked mode requires special discussion. In  this mode a  window may be:
„„ attached (docked) to one of the borders of the Designer window;
„„ attached (docked) to any border of any other window with the Docked property
turned on;
„„ displayed above any other docked window (stacked windows).
If the Docked mode is  turned on for a  window, this window is  attached to one of
the borders of the work area or to another window in  Docked mode.
To modify the size of a  docked window, move the mouse cursor to a  free border
(turned to the work area) and drag the border with the mouse.
If the window is  in  Floating mode and you drag its border close to a  work area
border or another Docked window, the window borders may change abruptly. If
you release the mouse button at this time, the window attaches to a  new border and
its status is  changed to Docked.
You can change the status of docked windows by moving them with the mouse.
To move a  window left click and hold the window header and drag the window to
another location. The  window state is  changed to Floating.
There are several ways to attach multiple docked windows to the Designer window
or another window border. Windows can be arranged in  layers when each window
occupies the entire width of the work area of the Designer window or a  different
window. It is possible to place windows in sequence so that each window
is located in one layer along the border of another window. If there are more
than two windows docked, you can arrange some of them in  layers and the others
in sequence.
To arrange one docked window above another (create stacked windows), please do
the following:
„„ grab the window header with the mouse;
„„ move the window so that its header fits over the header of another docked
window. The  dragged window should have a  tab contour at the bottom;
„„ release the mouse button.
Now tabs will show up at the bottom of the docked window. The  tab text will be
the same as the window header text. The  tabs contain stacked windows.
Click a  tab to open the corresponding window.
The Close command can only close an active tab in  this case.
To separate stacked windows grab the appropriate tab with the mouse and drag
it  away (you can control the contour of the window you move).
Chapter 31. Service Features 2-1145

If the mouse pointer remains in  the tab area, you can change the tab order in  this
way.
If some windows are docked to each other, you can attach more windows to them
by dragging new windows to the tab area instead of the header. You can specify the
tab order in  this way.
You can also arrange windows in the Autohide mode. If the Autohide mode
is selected, an additional line appears on one side of the work area. This line
contains window tabs, including a tab for the current window attached to this
side of the work area. Location of this line is  determined by the window location
in  Docked mode. In  this mode a  window remains on the screen while it  is  active.
Once a window is activated, the previous window becomes hidden. To open
a window move the mouse cursor over the tab for this window (do not click).
When the mouse is  moved away from the window, the window is  automatically
hidden.
For docked windows you can also specify a  mode other than stacked. For example,
the Autohide mode is  very convenient. In  this case an additional line will contain
only tab icons. Move the pointer over the tab icon to restore a  hidden window and
display its name in  the additional line.

31.1.1.2. Restoring Window Position

You can change window position, size and status as described above. When
a window is closed, the latest window display options are saved and when
a  window is  re-opened, the most recent display options are used.
To restore the original position, size and status of a  window, select the Restore
Window Position command in  the context menu of the window header (or window
bar header). The  saved display options are reset and the original parameters are
restored. The  window is  closed and re-opened with the new display options.

31.1.1.3. Selection of Window Mode for Object Forms

You can specify the window state mode for object forms when they are first opened
in  the 1C:Enterprise mode. For this purpose you can use the Window properties
category for each object form.
Window State specifies the window state when it is first opened. If the Normal
option is  selected, the window state cannot be modified for this window.
Dockable Window shows that it  is  possible to attach this window to other windows.
Window Location – if Auto is  specified, the window position is  determined based
on the state and dimensions of the work area. If you specify the Center option,
the window is placed in the center of the work area when it is first opened.
If Dont Overlap Owner is selected, location of a subordinate window is deter-
mined so that it  does not overlap the owner window or control (if the work area
2-1146 1C:Enterprise 8.3. Developer Guide

has free space). If there is  no place to display it, the subordinate window attempts
to expose the left part of the owner window provided that 50% of the owner width
can be unclosed.
Window Dock Location defines position of a  docked form window relative to the
work area.
Change Size permits or forbids changing the size. The  DontChange option does
not affect the ability to change the size of a  window in  the Docked and Autohide
modes.

31.1.2. Window Settings Dialog Box

This dialog box is  used to work with the list of open windows. It  can be used to
switch to a  selected open window, save changes, manage window location or close
one, several or all open windows.
Use the Windows – Windows command to open this dialog box. It  contains a  list
of currently open windows. Only windows with Normal status are included in  the
list.
If the contents of an open window have been modified, this window is marked
with a  "*" character appearing to the left of the window name.
All actions are performed with one or several windows in  the list. You can select
or deselect multiple lines in  the standard way.
Actions that can be performed with one or several open windows are described
in  the table below.
Button Action Number of Selected Windows (Condition)
Activate Makes selected window active One
Save Saves all changes for certain Any
document types (e.g., text and
spreadsheet documents) that have
this option
Close windows Closes all selected windows Any

Arrange Arranges selected windows on the More than one

screen.
Horizontally  – arranges selected
windows from left to right.
Vertically  – arranges selected
windows from top to bottom.
Cascade  – arranges selected
windows in  a cascade.
Combine Attaches two windows to each Attachment permitted
other
Separate Detaches combined windows
OK Closes the Windows dialog box Any
Chapter 31. Service Features 2-1147

31.1.3. Use of New Window Mode

Use the Windows – New Window command to make a  copy of any form editor, text
editor or spreadsheet editor window. A new window instance, an exact copy of the
current one, opens in  the work area of the program. Its contents are the same as the
contents of the source window. The  window instance number is  displayed in  the
header.
This mode is convenient for viewing, comparing and editing information in a
window. Any changes in any window instance are displayed in all window
instances.
It is  recommended that this mode be used if the window is  a configuration object
form with items distributed across several pages and you need to view these pages
at the same time or view the module and form dialog box simultaneously. Similarly,
this mode makes it  possible to edit long texts or templates. One window instance
can be used to view one part of a  text or template and the other window instance
can be used to view another part.

31.1.4. Service Windows

When the user is  working with the Designer, service windows are used to provide
various support information to the user. These windows include:
„„ message window
„„ search results window
„„ text template window
„„ Syntax Assistant
The first two types of windows are automatically displayed on the screen if needed
(the text template window and the Syntax Assistant window are displayed upon
user request).
The purpose of each of these windows is described in the corresponding parts
of this guide. This section describes general principles of working with such
windows.
To manage windows you can use context menus from the window title bar and the
inside of the window. The  first option manages the window itself (for details see
page 2-1143), while the second option operates the window contents.
The contents of the message window are not automatically cleared. To clear the
window select the Clear command from the context menu.

31.1.5. Closing Windows

Any window can be closed with the mouse (by clicking the Close Window button)
or with the keyboard using the Shift + Esc or Ctrl + F4 shortcuts.
2-1148 1C:Enterprise 8.3. Developer Guide

31.1.6. Window Navigation History

The history of navigation between windows is  stored only during a  session. You
can use this tool, for example, to return to the original window when moving to the
place where variables, procedures and functions are defined.
To move back within the history, select the Windows – Move back item. To move
forward within the history, select the Windows – Move forward item.

31.2. SETTING DESIGNER PARAMETERS

Use the Tools – Options menu command to specify various Designer parameters.
The Options window is organized as a card file. All possible parameters are
combined in  groups. To access controls of a  specific group, click the appropriate
window tab.

31.2.1. General
This tab contains a  single parameter that defines operation mode and interface for
Designer – Edit configuration for startup modes.
The parameter can have one of two values:
„„ Managed application. In  this case the system hides interface items used to edit
properties and objects in  the ordinary run mode.
„„ Managed and ordinary application. In  this case no interface items are hidden
and the user can edit the configuration in  both ordinary and managed mode at
one time.

Fig. 497.  General Options

This parameter is stored and can be set up for each particular infobase.
By default the parameter is  set to the managed mode; however, if the user loads
a configuration with Default run mode property set to Ordinary application
Chapter 31. Service Features 2-1149

(or if this property can be changed interactively), the parameter is assigned the
Managed and Ordinary Run Mode value.
The following Designer interface items are hidden when the parameter is  set to the
managed mode:
„„ Styles metadata tree branch
„„ Interfaces metadata tree branch
„„ Default Interface configuration property
„„ selection of default interface in  the user's editing dialog box
„„ Forms tab in  the Designer parameters
„„ Default run mode dropdown list on Modules – Check tab
„„ Use managed forms in  ordinary applications configuration property
„„ Use ordinary forms in  managed applications configuration property
„„ Interfaces tab in  metadata editing windows
„„ Open ordinary application module configuration context menu item
„„ flag of managed form creation in  the form wizard
„„ Report Generator commands
„„ Client (ordinary application) common module property
„„ Additional tab on the Forms tab of the configuration object editing window
„„ Interactive Activation Data processor and Before Execute Interactively event
handlers for a  business process route point of the Activity type

31.2.2. Texts
Texts tab controls are used to configure the text document editor.
Drag and drop text. You can use the drag & drop mode to copy and move text
blocks in  the text editor.

Fig. 498.  Text Editing Parameters

2-1150 1C:Enterprise 8.3. Developer Guide

Allow cursor beyond end of lines. If the option is  enabled, the cursor can be posi-
tioned after the line end. Otherwise the cursor position is  limited to the line break
symbol.
Show spaces and tabs. If enabled, space and tab symbols are displayed in the
text. This  option is  used to verify text formatting. With the Show spaces and tabs
enabled, the Space and Tab properties allow you to specify the display characters
representing spaces and tabs:
„„ Space – specifies the symbol used to display spaces;
„„ Tab – specifies the symbol used to display tabs.
Replace tabs with spaces when typing. If this option is turned on, tabulation
symbols are replaced with the number of spaces specified in  Tab width.
Tab width. It  defines the number of characters that corresponds to a  tab symbol
during text input.
Autoindent. It  sets or removes automatic indentation when the line break symbol
(the Enter key) is  entered.
Font. It specifies the font to be used for text input. It is recommended using
a  fixed-width font for module code (e.g., Courier New).
Autoreplace. If this option is  turned on, the entered text that corresponds to the
text in  the Automatically replace string attribute of the template is  automatically
replaced with template text. If this option is  set to Enable with Prompt, the template
text is  displayed after a  short pause while the text to be replaced is  being entered.
If this option is  set to Prompt Only, template text is  shown after a  short pause, but
the text is  not replaced.
To replace input text with template text, press Spacebar or Enter after typing the
string.

31.2.3. Modules
The Modules tab controls are used to configure color highlighting of module code
syntax, auto-indentation and tabulation step sizes for modules and to set up groups.
Settings are combined in  two sections, each located on a  separate tab.

31.2.3.1. Setting Editing Parameters

Use the Edit tab to configure color syntax highlighting, auto-indentation and tabula-
tion step size in  the module code (see fig. 499).
Syntax highlighting. It  is  much easier to recognize module text if certain syntactic
constructs (constants, names, operators, comments, etc.) are color-coded. Color
coding is  also used to check whether module text has been entered correctly. If an
operator is  entered incorrectly, it  is  not displayed in  the required color. You can
specify a  different color for each construct (constant, name, operator, comment,
etc.).
Chapter 31. Service Features 2-1151

Fig. 499.  Setting Module Text Editing

Disable color highlighting. If set, module text is  displayed as ordinary text and the
color highlighting setting is  unavailable.
Autoreplacement. If this option is  turned on, the entered text that corresponds to
the text in  the Automatically replace string attribute of the template is  automati-
cally replaced with template text. If this option is  set to Enable and show tooltips,
the template text is displayed after a short pause while the text to be replaced
is  being entered. If this option is  set to Show tooltips only, tooltip text is  shown
after a  short pause when you type the replaceable text.
To replace input text with template text, press Spacebar or Enter after typing the
string. If the Autoreplacement option is  set to Disable or Show tooltips only , these
actions are not performed.
Use Autoreplacement in  comments. If this option is  set, template text is  displayed
when the user enters matching text into comments.
Replace tabs with spaces when typing. If this option is turned on, tabulation
symbols are replaced with the number of spaces specified in  Tab width.
Tab width. It  specifies the number of Space characters equivalent to one tab character.
Autoindent. It  sets or removes automatic indentation when the line break symbol
(the Enter key) is entered. If the Use syntax rules value is selected, text entry
proceeds taking the current syntactic construct into account.
Font. It specifies the font to be used for text input. It is recommended using
a  fixed-width font for module code (e.g., Courier New).
2-1152 1C:Enterprise 8.3. Developer Guide

31.2.3.2. Setting Module Check Parameters

The Check tab can be used to set module check modes.

Fig. 500.  Module Syntax Check Settings

Use the module check settings to select a  suitable environment for compilation.
Execution environment includes common modules with an appropriate flag and
special modules used in  a particular execution mode (managed application module,
session module, etc.). If execution environment compilation is successful, the
module that has initiated syntax check is verified. The number of check passes
(including execution environment compilation) is  defined by the number of check
boxes selected in  the dialog box. Modules that do not exist in  the selected check
mode are not verified; e.g., application modules are not checked if the Thin client
check mode has been selected.
Availability of the Default run mode dropdown list in  the form depends on the Edit
configuration for startup modes parameter (see page 2-1148). If the parameter value
is  Managed application, the dropdown list is missing from the form; the Thick
client (ordinary application) parameter is  also hidden in  this case. When the dialog
box is  opened, the parameter value always matches the Default run mode configu-
ration property value.
If the Default run mode dropdown list is  available in  the form, the user can select
check modes for each run mode. If the Ordinary application mode is  selected, only
the Thick client (ordinary application) check box is  set by default; if Managed appli-
cation is  selected, Thin client and Server are checked. The  user can specify a  new
set of check boxes for each run mode and click Apply or OK. When the Edit configu-
Chapter 31. Service Features 2-1153

ration for startup modes parameter changes value (see page 2-1148), the Designer
restores the required set of check modes.
The selected run mode determines preprocessor instructions:
Check Mode Preprocessor Instruction
Thick client (ordinary application) Client, AtClient, ThickClientOrdinaryApplication
Thin client ThinClient, Client, AtClient
Web client WebClient, Client, AtClient
Server Server, AtServer
External connection ExternalConnection

If the Check automatically check box is selected, module text is automatically

checked for syntax errors (when recording or closing). When the Perform extended
check checkbox is selected, calls to object properties and methods via a period
(".") are verified for a  limited number of types. Also, the system checks whether
the parameters specified by a  string are correct for a  limited number of methods.
For more details on verification types, see page 2-1025.

31.2.3.3. Setting Group Parameters

The Grouping tab is used to specify modes for grouping and collapsing various
syntactic constructs. The  table below lists syntactic construct types by row.

Fig. 501.  Group Settings

If the Group column is  checked, this syntactic construct is  automatically grouped.
Please note that only syntactic constructs at the second level of nesting can be
grouped.
If the Collapse column is checked, this syntactic construct is automatically
collapsed when a  module is  opened.
2-1154 1C:Enterprise 8.3. Developer Guide

31.2.3.4. Context Tip Settings

The Context help tab is  used to launch context tip for module texts.

Fig. 502.  Context Help Settings

If the Automatic hint when "." is  typed option is  checked, context tip is  displayed
automatically when the user types ..
If the Automatic hint when "=" is  typed option is  checked, context tip is  displayed
automatically for system enumeration value selection when the user types "=".
The Automatic hint when a  quotation mark is  typed checkbox enables context tips
for the options of some methods, if an option is  set by a  string.
The Automatic hint when "(" or "," is  typed checkbox enables context help for the
parameters of system procedures and functions, including procedures and functions
of the applied solution with comments using a  special format (see page 2-951).
If the Include templates in  the list of hints option is  checked, templates with auto-
replace strings defined are also listed.
If the include keywords in  the list of hints option is  checked, all keywords (e.g.,
If, Procedure, Do, Return, etc.) are included in  the list.

31.2.4. 1C:Enterprise Startup

31.2.4.1. Main Parameters
Use this tab to specify application to be started up and user selection method for
1C:Enterprise startup (see fig. 503).
The Application group defines the client to be launched upon 1C:Enterprise mode
startup in  the Designer.
Chapter 31. Service Features 2-1155

Fig. 503.  1C:Enterprise Launch Parameters

If it  is  set to Select automatically, the system selects the client type depending on
the Default run mode configuration property value and Run mode property value
for the user starting up 1C:Enterprise. If no particular value is specified in the
configuration and user properties, the following criteria are applied:
„„ If Default run mode is  Ordinary application, the system runs thick client in  the
ordinary mode.
„„ If Default run mode is  Managed application, the system runs thin client.
If the user wants to pick a  specific client to run when 1C:Enterprise is  started up
in the Designer, it has to be done manually (items below Select automatically).
If the web client has been selected to run, the Web browser to be used can also be
indicated:
„„ Default
„„ Microsoft Internet Explorer
„„ Mozilla Firefox
„„ Google Chrome
„„ Safari
When the web client is  launched from the Designer, the system checks version of
the platform that has had an infobase previously published. If versions differ, the
2-1156 1C:Enterprise 8.3. Developer Guide

user is  prompted to run publication again. Affirmative answer initiates an infobase
publication dialog box (for details see "1C:Enterprise 8.3. Administrator Guide").
The User group determines the user on behalf of whom 1C:Enterprise is  started
when it  is  started in  the Designer:
„„ Current – from the user list.
„„ Name – a  specific user is  designated (same as the /N command line option).
There is  the ability to select a  user from the list. The  "..." button in  the right
side of the field is  used for this purpose.
„„ Use operating system authentication – if this option is  checked, user is  selected
using OS authentication (same as the /WA command line switch).
Data split – specifies separator values as they are specified for the -Z option (for
more details see page 2-911). A string specified in this field should match the
rule of specifying separator values, but it  should not include quotes around values
when they are specified in  the /Z option. For example, when the following option
is  specified in  the command line: /Z "-1,+4", in  the Data split you should specify
-1,+4. The system remembers different variants of separator values entered and
allows you to switch between them.
Startup option – launch parameter (same as the /C command line switch) that can be
edited via the LaunchParameter global context property.
Slow connection – enables or disables low speed connection mode when launching
thin client. The  check box status is  saved for a  specific infobase. If run mode with
low connection speed is  not set for an infobase in  the infobase list, the check box
is  displayed as unset. If the check box is  selected, 1C:Enterprise runs with low
speed.
If run mode with low connection speed is  set for an infobase in  the infobase list,
the check box is  displayed as grey. If the check box is  not selected, 1C:Enterprise
runs with normal speed. The  check box has the same function as the -O command
line switch.
Emulate delay on server calls – this check box enables imitation of thin client
operation with significant delays in interaction with the server. By default
it is unchecked.
Call delay (seconds) – defines delay duration for each server call by the client
application.
Data sending delay (seconds/Kb) – defines delay duration for data transfer to the
server. The  time value is  indicated per 100 bytes of transferred data.
Data receiving delay (seconds/Kb) – defines delay duration for data retrieval from
the server. The  time value is  indicated per 100 bytes of retrieved data.
NOTE
Default values allow emulating GPRS connection.
Chapter 31. Service Features 2-1157

Server call delay mechanism can also be enabled using the command line: -Emula-
teServerCallDelay [-CallXXXX] [-SendYYYY] [-ReceiveZZZZ], where:
„„ -EmulateServerCallDelay – command line switch that enables the delay imita-
tion mechanism for server calls;
„„ -Call – parameter indicating delay duration for a server call in milliseconds
(if no value is  specified, the delay is  100 ms);
„„ -Send – parameter indicating delay duration for data transfer (if no value
is  specified, the delay is  100 ms);
„„ -Receive – parameter indicating delay duration for data retrieval from server
(if no value is  specified, the delay is  100 ms).

31.2.4.2. Additional Parameters

This tab lists additional parameters that can help the user in  application solution
development (e.g., in  debugging).

Fig. 504.  Additional 1C:Enterprise Launch Parameters

Service messages file – if it  is  necessary to auto-save service messages to a  file,
specify its name in  this parameter (same as the /OUT command line switch).
Do not clear file before startup – if the check box is  set, at the next startup messages
will be added to the file specified (same as the /OUT command line switch with the
NoTruncate key).
2-1158 1C:Enterprise 8.3. Developer Guide

System interface language – specifies the interface language (same as the /L

command line switch).
Session localization code – specifies session locale code (same as the /VL command
line switch).
Do not warn on startup – if this option is  checked, the following launch warnings
are suppressed:
„„ Configuration being edited differs from database configuration. Continue?
„„ Your computer's capabilities are inadequate to edit configuration help, you must
install Microsoft Internet Explorer version 6.0 or higher.
„„ Your computer's capabilities are inadequate to edit HTML documents, including
help sections. To edit HTML documents, you must install Microsoft Internet
Explorer version 6.0 or higher. HTML document editing will be unavailable during
this session (same as parameter passed through the /DisableStartupMessages
command line switch).
Enable debugging mode – if checked, debugging is  enabled when launching the
system in  1C:Enterprise mode (same as the /DEBUG command line switch).
Begin debugging on startup – if checked, connection is  performed automatically
when launching 1C:Enterprise.
NOTE
If 1C:Enterprise is launched from the Designer by pressing F5 (or using the
Debug  – Start Debugging menu item), the debugging mode is  enabled automati-
cally (regardless of Enable debugging mode and Begin debugging on startup check
boxes).
Display performance indicators – if this check box is selected, 1C:Enterprise
launch adds a  special button to the Favorites and History panel. Clicking the button
displays a window with current statistics on interaction with the 1C:Enterprise
server (same as the /DisplauserverCalls command line switch).

Fig. 505.  Show Server Calls

For a  detailed description of the server call display mechanism see page 2-1057.
Display All Functions command – displays the Main Menu – All functions menu item
(see fig. 506). Invocation of this command displays a  form with a  list of all appli-
cation objects available to the user (used in  managed mode of thick client as well
as thin and web clients). By the default this menu item is  disabled (it is  the same
as the /DisplayAllFunctions command line switch).
Chapter 31. Service Features 2-1159

Fig. 506.  Tools – All Functions Menu

NOTE
Forms opened from the All functions window always appear in  an auxiliary appli-
cation window.
The All functions window also provides access to Standard functions used for
standard procedures: viewing the list of active users, deleting marked objects, etc.
For a  detailed description of standard functions see "1C:Enterprise 8.3. Adminis-
trator Guide".
The Automated testing group defines the role (in terms of automated testing; for
details, see page 2-1060) for the client application launched from Designer:
„„ Do not use – the launched client application is not included in automated
testing;
„„ Run as testing manager – the launched client application is  used as the testing
manager (the TestManager command-line parameter is  used);
„„ Run as testing client – the launched client application is used as the
testing client (the TestClient command-line parameter is used); the port
specified in the Port number for thin and thick clients parameter is used for
communicating with the testing manager (TPort option for the TestClient
command-line parameter). For the web client, the ID specified in  the Identifier
for web client option is  used (TestClientID command-line parameter).

31.2.5. Help
Use this tab to configure the viewing mode of the Help content (see fig. 507).
Help content can be displayed in one window or split into several independent
windows (Display in  a single window/Display in  multiple Windows parameters).
The Syntax Assistant window can be placed horizontally or vertically (Arrange
horizontally/Arrange vertically parameters) and use two languages for terms (Use
both languages parameter).
2-1160 1C:Enterprise 8.3. Developer Guide

Fig. 507.  Help Content Display Settings

The user can set up filtering by object availability for tree contents and Syntax
Assistant index display for a particular 1C:Enterprise run mode. Thus, Syntax
Assistant sections can be displayed only for objects available in  the thin client.
This tab can also be accessed using a  command bar button in  the Syntax Assistant.

31.3. CALCULATOR
For help with calculator features see the "Calculator" section in  the User Manual.

31.4. CALENDAR
For help with calendar features see the "Calendar" section in  the User Manual.

31.5. TEXT TEMPLATES

The Designer can save frequently used text fragments for quick insertion into a  text
document or module code.
A template is a text fragment assigned to some character sequence serving as
a  short name to look up this text sequence when typing. If the automatic substitu-
tion mode is  turned on, the named text fragment is  automatically inserted into the
editor when the template name is  typed.
IMPORTANT!
Automatic substitution mode is turned on separately for modules and text on
different tabs of the Designer parameters window.
Chapter 31. Service Features 2-1161

31.5.1. Template List Maintenance

Templates are stored in  template files. Templates can be classified as standard
(i.e. shipped with 1C:Enterprise) and user (i.e. user-generated). Standard templates
are stored in the bin directory of the installation directory for a particular
1C:Enterprise version. User templates can be stored at any location on the hard
drive. The  list of attached templates is  saved and can be generated for individual
versions of 1C:Enterprise script. Standard templates are provided for both versions
of 1C:Enterprise script.
Templates can be configured in  the Text Templates window using the Tools – Text
Templates command.

Fig. 508.  Text Templates

To manage templates select Actions  – Template Setup in the Text Templates

window. The  Template settings window is  displayed.

Fig. 509.  Template Setting

2-1162 1C:Enterprise 8.3. Developer Guide

Use the Use standard templates check box to add standard templates. Deselecting
this check box disables standard templates altogether. Each 1C:Enterprise version
uses its own set of standard templates. User templates can be attached in addi-
tion to standard templates. To do this, click the Add button on the toolbar of the
Template Setting window and select the required template file.
TIP
It is recommended to store user templates in a directory different from the
1C:Enterprise installation directory. For example, templates might be saved in  a
special subdirectory of the My Documents directory.
Use the Move up and Move down buttons to rearrange files within the list.
To remove an unwanted template select it in the file list and click the Delete
current item button.

31.5.2. Editing Templates

Select Actions  – Change to edit an existing template file. The template editing
window will be displayed.

Fig. 510.  Template Editor

IMPORTANT!
Standard templates cannot be edited. They can only be viewed in  the template
editor.
Chapter 31. Service Features 2-1163

The Name attribute shows the name of a  template in  the list of templates. Use the
Automatically replace string attribute to specify the line sequence to be replaced
with template text when typing. Replacement is  initiated by hitting Spacebar or
Enter key.
Additionally when the user types in  a template name, a  tooltip with template text
is  displayed on the screen as shown below.

Fig. 511.  Use of Templates

The template editing window contains a  toolbar that can be used to create template
groups and separate templates, remove redundant templates and sort lists. The  left
part of the window contains a tree of templates. In the right part, you can edit
names of template groups and the template itself.
Templates can be grouped into folders for convenience. Use the Add Folder
command from the context menu or the appropriate toolbar button to create
a  group. Enter a  group name in  the Name attribute.
To create a  template select the group where it  is  to be located and use the Add
command from the context menu or the appropriate toolbar button. The  Name
attribute contains the template name (this name is  used to select a  template for
inserting into edited text). Use the Automatically replace string field to specify the
first part of the string that will be replaced with template text in  a text document
window (if automatic substitution is turned on). Automatic substitution occurs
when the user presses Enter or Spacebar after entering a  sequence of characters.
Use Template text multi-line field to enter text to replace the Automatically replace
string field value or to be inserted into a  document when a  template is  selected.
To make a  template available for interactive selection, check the Include in  context
menu option.
In this case a  template to be inserted in  text (module) can be selected from the list
of templates in  the context menu. Templates are placed in  the list if the Include
in  context menu option is  checked.

31.5.2.1. Template Control Directives

Custom Query
Description:
This is  used for entering any text. When using this kind of template, a  dialog
on context-dependent template entry appears on the screen.
2-1164 1C:Enterprise 8.3. Developer Guide

Syntax:
<?"Tooltip">
Parameters:
<Tooltip>
Explanatory label text.

Cursor Positioning
Description:
This construct is used for placing the cursor to the indicated location after
inserting text into the template.
Syntax:
<?>
Special Query
Description:
This construct is  used for entering configuration objects, predefined items and
other data.
Syntax:
<?"Tooltip",<Keyword>[, <Parameter1>[,<Parameter2>…]]
Parameters:
<Tooltip>
Explanatory text in  the entry query.
<Keyword>
Type of query.
<Parameter1>…
Query parameters.
Chapter 31. Service Features 2-1165

Special query descriptions are listed in  the following table:

English Variant Description
BusinessProcess Selecting a  business process type
VariantSelection <Tooltip 1>, When using this template a  list of lines to choose from is  shown
<String to insert 1>, … on the screen
, <Tooltip N>, <String to Each list line consists of a  tooltip and insertion text.
insert N> Example:
"Tooltip 1" – parameter describing text of the first list line;
"String to insert 1"  – parameter or text that will be inserted by
choosing the first line
TypeSelection Selection of type
Document Document type selection
DocumentJournal Document journal type selection
Task Task type selection
EnumValue Enumeration value selection
UserName User name entry
TypeDescriptionConstructor Type description wizard
UserFullName Full user name entry
ConfigurationStorageUserName Entry of full configuration repository user name
Constant Constant selection
FilterCriterion Filter criterion selection
DataProcessor Data processor selection
Report Report selection
Recalculation Recalculation selection
Enum Enumeration selection
ChartOfCalculationTypes Chart of calculation types selection
ChartOfCharacteristicTypes Chart of characteristic types selection
ExchangePlan Exchange plan selection
ChartOfAccounts Chart of accounts selection
ChartOfCalculationTypesPre- Selection of predefined data for a  chart of calculation types. First,
definedData a  chart of calculation types is  selected, then  – predefined data
value
C h a r t O f C h a r a c t e r i s t i c - Selection of predefined data for a  chart of characteristic types.
TypesPredefinedData First, a  chart of characteristic types is  selected, then – predefined
data value
ChartOfAccountsPredefined- Selection of predefined data for a  chart of accounts. First, a  chart
Data of accounts is  selected, then – predefined data value
MDObjectsSubset Metadata object selection. When creating a  template, a  dialog
box opens where you need to specify types of metadata objects.
When selecting a  template, a  selection dialog box appears on the
screen containing all metadata objects of the specified type.
Seq Sequence selection
AccountingRegister Accounting register selection
AccumulationRegister Accumulation register selection
CalculationRegister Calculation register selection
InformationRegister Information register selection
2-1166 1C:Enterprise 8.3. Developer Guide

English Variant Description

Catalog Catalog selection
CatalogPredefinedData Selection of predefined data for a  catalog. First, a  catalog
is  selected, then – predefined data value
QueryText Query text entry using query wizard
DateTime, <Format string> Entry of current date in  the format indicated in  the <Format
string> parameter
FormatString Format string text entry using format string wizard

31.5.2.2. Template Text Editor

Templates can contain a static (unchangeable) part and a dynamic part which
is context-dependent and cannot be specified in advance. For example, the If
operator of the 1C:Enterprise script has the following structure:
If <?"Condition 1"> Then
ElseIf <?"Condition 2"> Then
EndIf;
<?"Condition…">

These are context-dependent template parts.

To provide for universal use of a template, use the control directives insertion
mode. Control directives (character sequences which initiate some actions when
template text is  inserted) are inserted into the template text. For example, a  control
directive can be used to request information from the user and to add this informa-
tion to the text to be inserted.
Control directives can be inserted into templates manually or interactively through
a  special query.

Fig. 512.  Insert Control Directive

Place the cursor in the template area that contains a variable part and click the
<->Insert… button. The  Insert Control Directive dialog box is  displayed.
Chapter 31. Service Features 2-1167

The Tooltip attribute is used to specify a line of text that will be entered as an
explanation to an action that is performed when a context-dependent part of
a template is requested. Since a template can contain several control directives
that can be entered in  a sequence, this text explains the required actions and the
location of the variable part.
Click radio buttons to select the type of control directive for insertion.
Custom query is  used to enter free-form text. In  this case template text contains
a  control directive that looks like <?"Tooltip text">.
A Custom query control directive is used as follows. If the replacement text
contains a  <?"Tooltip text"> construct, a  request with tooltip text and a  text
box is  displayed before the replacement text is  inserted. Specify the text for inser-
tion in  the text box in  place of the <?"Tooltip text"> construct. There may be
several Custom query constructs in  a replacement text and some constructs may
have the same tooltip text. A specific text request is  provided for each construct
when replacement text is  inserted. There will be one common query for all iden-
tical constructs and the text in  the query will replace all identical constructs.
Specific query is used to select configuration objects. To place a configuration
object into the type selection control directive template using the Insert Control
Directive window, enter the query name in  the Tooltip field and select the directive
from the list (selection of configuration object, predefined configuration object item
or special directive), e.g., Catalog.

Fig. 513.  Specific Query

When such a  template is  used, a  list of possible configuration objects is  displayed
on the screen. The  name of a  selected object replaces the entered text. Position
of the selected line is  memorized and the list is  positioned on this line when this
template is  selected again.
Other possible values for a  specific query include a  switch. When a  template with
this type of query is  generated and you click OK, a  window with possible values
is displayed.
2-1168 1C:Enterprise 8.3. Developer Guide

Fig. 514.  Data for Selection

Use the Tooltip column to insert text to be placed in  the selection list when this
template is  used. Use the String to insert column to enter text for insertion into text
document.
The list can only be edited in  the template text. When directive insertion is  invoked
again, a  new directive is  added.
When you press OK, a  control directive is  inserted into the template text.

Fig. 515.  Template with Control Directive

Chapter 31. Service Features 2-1169

Select this template in  the template tree (or during automatic substitution).

Fig. 516.  Context Menu

In this case a  catalog type selection query is  displayed.

Fig. 517.  Enumeration Selection

The following text is  generated as a  result:

PredefinedValue("Enum.ProductTypes.Product")

Position cursor – is used for placing the cursor to the indicated location after
inserting text into template. The  <?> construct is  inserted into replacement text of
the template. This  construct specifies where the cursor is  moved to when replace-
ment text is  inserted. If there are several constructs of this type in  the replacement
text, the cursor is  placed into the first <?> construct.
When writing template texts, multiple occurrences of control directives as well as
use of existing templates is  allowed.
2-1170 1C:Enterprise 8.3. Developer Guide

31.6. SYNTAX ASSISTANT

Syntax Assistant is  a tool that facilitates module development. The  main purpose
of the Syntax Assistant is to provide the 1C:Enterprise configuration developer
with quick help on the 1C:Enterprise script.
Use the Help – Syntax Assistant command to invoke the Syntax Assistant.
The Syntax Assistant window is  divided into two parts. Division can be vertical or
horizontal.
A description of the selected 1C:Enterprise script section is  displayed in  the lower
(right-hand) part. Contents of the upper (left-hand) part are defined by the selected
tab.
This window contains three tabs: Content, Index and Search. The  first tab contains
a hierarchical list of 1C:Enterprise script items for the 1C:Enterprise operators,
control directives, procedures and functions, system constants, etc. The  second and
third tabs are designed for searching using 1C:Enterprise script item names and for
custom searching using description text, respectively.
If horizontal location has been selected for the Syntax Assistant, tabs are replaced
by buttons with the same names on the command bar.

Fig. 518.  Horizontal Location

The user can set up filtering by object availability for tree contents and Syntax
Assistant index display for a  particular 1C:Enterprise run mode.
Chapter 31. Service Features 2-1171

31.6.1. Syntax Assistant Settings

For a  description of Syntax Assistant settings see page 2-1159.
Command bar buttons of the Syntax Assistant are described on fig. 519.

Fig. 519.  Description of Command Bar Buttons

31.6.2. Content Tab of Syntax Assistant

For the sake of convenience, all items of the 1C:Enterprise script are grouped under
topics represented as a  tree with branches which is  displayed in  the upper part of
the Syntax Assistant window.

Fig. 520.  Syntax Assistant Window

2-1172 1C:Enterprise 8.3. Developer Guide

The Syntax Assistant window is  a standard hierarchical data window with a  tree
and you can work with it  in  a standard way. To open a  branch use the "+", "-" and
"*" keys of the numeric keypad. The  "+" key expands one level of a  branch, the
"-" key collapses a  level and the "*" key expands all child branches of the current
branch.
To get a  description select the name of a  1C:Enterprise script item in  the upper
part of the Syntax Assistant window. The item description is displayed in the
lower part of the window. This  description may contain links to descriptions of
referenced 1C:Enterprise script items.
The window contains a toolbar that can be used to view history of previously
selected descriptions.
To display location of the item whose description is currently displayed in the
lower part of the window in  the structure of the 1C:Enterprise script items, click
the Find current element in  the tree button in  the toolbar.

31.6.3. Copying 1C:Enterprise Script Items

The Syntax Assistant can copy selected 1C:Enterprise script items to the text editor.
To do this, select the desired item in  the tree and use the clipboard. A 1C:Enterprise
script item instance is  inserted at the cursor position in  the text editor window.
In addition to the clipboard, you can drag and drop instances of 1C:Enterprise script
items: you simply need to use the mouse to drag the selected item from the Syntax
Assistant window into the editor window.

31.6.4. Search in  Syntax Assistant

The Syntax Assistant can perform searches by the 1C:Enterprise script item name
and by arbitrary description text.
A search using the 1C:Enterprise script item name is  performed in  the Index tab
of the Syntax Assistant window. The upper part contains a text box where the
required 1C:Enterprise script item name has to be entered and a  complete list of all
item names.
When you enter a  name, the program performs a  special context search moving
to the first name on the list that begins with the entered text based on each entered
character.
To enable the context search mode select the Search in  Syntax Assistant command
from the context menu of the text editor. The  Index tab of the Syntax Assistant
window will open.
Chapter 31. Service Features 2-1173

Fig. 521.  Syntax Assistant Index

If the found item is  used in  several objects, the Select topic window will open.
This  window contains a  list of entries for the selected item.

Fig. 522.  Select Topic

Now, if you press the Show button, a  description of the found 1C:Enterprise script
item from the window of entries is  shown in  the Syntax Assistant window.
TIP
If the Select topic window contains a  lot of lines (see fig. 523), press Ctrl+F and
enter the name of the searched object in  the search dialog box. Thus, search of the
required topic can be accelerated.
2-1174 1C:Enterprise 8.3. Developer Guide

You can search for a  1C:Enterprise script item description in  the Syntax Assistant
during module editing. To perform a search place the cursor over the item for
which you need to find description or select a  text block and press Ctrl + F1.
If the word on which the cursor is placed or the selected text block is a
1C:Enterprise script item described in  the Syntax Assistant, the Syntax Assistant
window will open immediately with this item description.
If a  1C:Enterprise script item is  described in  several sections of the Syntax Assis-
tant, the Select topic window will open so that the required section can be selected.
If the selected word or text block is  not a  1C:Enterprise script item, the context
search window will open in  the Syntax Assistant when you press Ctrl + F1.
Each search is  memorized in  a list that can be called in  the Name text box.
To view a  topic select it  from the list and press Enter. Description of the selected
topic is  shown in  the lower part of the window.
Searches using random description text are performed in the Search tab of the
Syntax Assistant window. The  upper part contains a  box for entering the search
string and a  box with a  list of 1C:Enterprise script item description topics found.
To begin the search start typing the text. While you are typing, the system
searches for topics where the entered text is  present. Search is  not case-sensitive;
only whole words of the text are matched (unless the "*" operator is  used), with
morphology taken into account. Search operators are allowed (see page 2-1207).
While you enter the text, the program displays a list of corresponding topics.
If the entered text is not found anywhere, the program displays appropriate
message below the text box.

Fig. 523.  Search in  Syntax Assistant

Chapter 31. Service Features 2-1175

When you open a  topic, the program shows the description in  such a  way that the
first occurrence of the specified text is  visible.
To view a  topic select it  from the list and press Enter. Description of the selected
topic is  shown in  the lower part of the window.
When the chapter with the description of the 1C:Enterprise script item has been
found and the Syntax Assistant window is open, use the Find current element
in  the tree button in  the command bar to search for the chapter in  the description
tree.
If you select several pages for viewing, you can use the Go forward and Go back
commands to return to previously viewed pages.
For a  description of search expression syntax see page 2-1207.

31.7. FILE COMPARISON

In the file comparison mode, you can compare any two files. Use the File  –
Compare Files command to compare files. The file comparison dialog box will
open.

Fig. 524.  File Comparison

In the Compare and With fields, specify names of the files to be compared. File
names can be entered manually or selected from the dropdown list or from the
standard file opening dialog by clicking the selection button (…). You can specify
any type of source file in  the File Type field of the dialog box.
Use the As field to specify how the files are to be compared. You can compare text
and spreadsheet documents as well as external data processors. You can also use
binary comparison to compare files on the binary level. In  this case the results will
tell you whether or not the files are different from each other.
If files of different types are specified in  the Compare and To fields, the selected
files are cast to the type specified in the As field. Then the actual comparison
is  performed and comparison results are displayed.
Click OK to start the comparison process.
If you select Text document comparison type, the selected documents will be inter-
preted as text documents for comparison, although the Compare and With fields
2-1176 1C:Enterprise 8.3. Developer Guide

can contain non-text files (according to file extensions). If any of the specified files
cannot be interpreted as a  text file, binary comparison is  performed.

31.7.1. Comparison of External Data Processors

If you compare external data processors, use the standard external data processor
comparison procedure (for details see page 1-308).
Check the Match configurations by object names option to match objects first by
names and then by internal IDs. If this option is  not checked, objects are matched
based on internal identifiers.

31.8. BUILT-IN SYSTEM FOR HELP CONTENT RETRIEVAL

Help content can be used to obtain information on 1C:Enterprise system tasks
and specific objects and modes. You can invoke it any time by selecting Help
or pressing the F1 key. It  opens the help content section that corresponds to the
current mode operated by the user.
The Contents menu item and Shift + F1 keys allow you to access the Help Table of
Contents where you can obtain information on the Designer mode.

Fig. 525.  Help Content

Help content contains a  description of configuration sections, 1C:Enterprise script

and additional information.
At the top of the help content window, you can see the toolbar used for navigation
and search. The  help contents are shown below the toolbar.
Chapter  32

ADD-INS

1C:Enterprise is an expandable system. Its functionality can be enhanced by

add-ins.
The system uses two methods to create add-ins:
„„ using Native API;
„„ using COM technology.
These can be used to develop add-ins for Windows OS and Linux OS as well as
for web clients running in  Microsoft Internet Explorer version 6.0, 7 and 8 and
Mozilla Firefox version 3 (for Windows and Linux OS).
Add-ins designed for web client environment must be packed into a  ZIP archive
with special structure. This  file can also be used at the 1C:Enterprise server and
in  other clients.
If add-ins have been created using Native API, the following procedure should be
followed:
„„ Interface implements a  command that installs the add-in on the user's computer
(InstallAddIn() global context method). This  operation is  required in  thin
and web clients.
„„ The add-in is  attached via the AttachAddIn() method. Please remember that
attempting to attach a  non-installed add-in raises an error.
„„ Attached add-in can be used in  compliance with the provided interface.
TIP
It is  not recommended to combine codes for add-in installation and attachment.
Installation is  treated as a  one-time event and re-installation causes an interac-
tive exception.
If add-in is  packed in  to a  ZIP archive, its parameters (name of installation file,
type, architecture and Web browser to be used) are specified in  a special manifest
file generated by the add-in developer.
2-1178 1C:Enterprise 8.3. Developer Guide

Add-ins obtained from the configuration or infobase are saved and used in  subse-
quent connections without the need to retrieve them again (if an add-in is  used at
the server, it  is  only saved for the server working process lifetime).
NOTE
The external СОМ components connection using the LoadAddIn(), AttachAd-
dIn() methods and component object registration are performed "for user".
If "for user" registration fails, an attempt to perform "for computer" registration
will be made.
If an add-in is  enabled using the AttachAddIn() method, the parameter in  the
New() operator (of the created type name) includes the following:
„„ Addin. text
„„ Name specified in  the Name parameter of the AttachAddIn() method
„„ Name of the object implemented in  the add-in
If a Timer object is implemented in the add-in and the latter is attached using
AttachAddIn(URL, "MyName");, creating an object from the add-in requires
entering the following ID: New("Addin.MyName.Timer").

32.1. WORK IN  THIN AND THICK CLIENTS

When working in  thin and thick clients, add-ins developed with both COM and
Native API technologies can be used (represented as either separate files stored on
disk or special ZIP archives).
Add-ins can be updated by simple re-installation using the InstallAddIn()
method.
Add-ins are installed in the %APPDATA%\1C\1cv8\ExtCompT directory. Add-in
installation directory is  not treated as cache and is  not cleared when 1C:Enterprise
is invoked using the /ClearCache command line switch. The  InstallAddIn()
method is  required in  the thin client.

32.2. WORK IN  WEB CLIENT

When working in  web clients, add-ins developed with both COM and Native API
technologies can be used (packed in  special ZIP archives). COM add-ins can be
used only if the web client runs under Windows OS. When the add-in is  installed,
the system asks the user to confirm installation.
For details on Web browser setting for working with add-ins see "1C:Enterprise 8.3.
Administrator Guide".
Every add-in is  installed as a separate Web browser extension. Extension is  an
installation package designed for a  particular browser type.
Chapter 32. Add-Ins 2-1179

Add-ins are installed:

„„ Microsoft Internet Explorer – in 
%ALLUSERSPROFILE%\Application
Data\1C\1CEWebExt (%ALLUSERSPROFILE%\1C\1CEWebExt directory for
Windows Vista and later)
„„ Mozilla Firefox – the current browser’s user profile directory (created by the
browser)
„„ Google Chrome – in the directory of the current web browser user profile
(created by the web browser)
„„ Safari – as defined by the add-in developer
Add-ins can be removed:
„„ for Microsoft Internet Explorer browser – via Add/Remove Programs feature of
the Control Panel
„„ for Mozilla Firefox Web browser – via extension feature of the Web browser
„„ for Google Chrome web browser – via the mechanism used to work with web
browser plug-ins (navigate to chrome://plugins)
„„ for Safari web browser – using the standard method
IMPORTANT!
Attachment of add-ins from files stored on disk is  not supported in  Web browsers
for safety reasons.
Note that working with COM objects is available only in Microsoft Internet
Explorer and Windows. Also, the COMSafeArray type is  not supported as well as
an ability to call methods of COM objects that work with this type of value.
To update an add-in do one of the following:
„„ Remove the add-in as described above and re-install it  using the
InstallAddIn() method.
„„ Change the add-in object name in the add-in source file and manifest file
(the add-in file name does not have to change) and re-install the add-in using
the InstallAddIn() method.

32.3. WORK ON SERVER

When working on the 1C:Enterprise server, only Native API add-ins are allowed
(represented as either separate files stored on disk or special ZIP archives).
Use the AttachAddIn() method to attach an add-in (without the InstallAddIn()
method that is  unavailable on the server).
When working on the server, it  is  recommended to attach add-ins shortly before
use. Moreover, add-ins used on the server must support all architectures and
platforms. This  is  because server code can be generally executed in  various work-
flows (in different points in  time) on various computers. Computers can use both
different architectures and different OS.
2-1180 1C:Enterprise 8.3. Developer Guide

Add-in file is  saved by workflow until restart; therefore, re-attachment of add-in
(before workflow restart or switch to another workflow) takes less time than the
initial attachment.

32.4. EXAMPLES OF ADD-IN USE

32.4.1. Native API Technology
Native API add-ins can be attached in  both client applications and 1C:Enterprise
application server.
If an add-in runs on the server, the AttachAddIn() method has to be called every
time an add-in instance is  created since in  the most general case the user cannot
predict what server will execute the call (it can be Windows, Linux, 32-bit or 64-bit
OS).

32.4.1.1. Add-In Installation on Client

InstallAddIn("CommonTemplate.BarcodeReaderDriver");

32.4.1.2. Load from File on Disk

Add-in file must be located on the user's computer and be available in the OS
search path (PATH environment variable).
SysInfo = New SystemInformation;

If SysInfo.PlatformType = PlatformType.Windows_x86 Then

AttachAddIn("AddInCPP.dll", "MyName", AddInType.Native);

ElseIf SysInfo.PlatformType = PlatformType.Windows_x86_64 Then

AttachAddIn("AddInCPP64.dll", "MyName", AddInType.Native);

ElseIf SysInfo.PlatformType = PlatformType.Linux_x86 Then

AttachAddIn("libAddInCPP.so", "MyName", AddInType.Native);

Else

AttachAddIn("libAddInCPP64.so", "MyName", AddInType.Native);

EndIf;

AddInObject = New("AddIn.MyName.ComponentExtension");

NOTE
Please note how parameter in  the New command is  generated.
Chapter 32. Add-Ins 2-1181

32.4.1.3. Load Add-In from Template

SysInfo = New SystemInformation;

If SysInfo.PlatformType = PlatformType.Windows_x86 Then

AttachAddIn("DataProcessor.AddIn.Template.AddInWindows32", "MyName", AddInType.Native);

ElseIf SysInfo.PlatformType = PlatformType.Windows_x86_64 Then

AttachAddIn("DataProcessor. AddIn.Template.AddInWindows64", "MyName", AddInType.Native);

ElseIf SysInfo.PlatformType = PlatformType.Linux_x86 Then

AttachAddIn("DataProcessor.AddIn.Template.AddInLinux32", "MyName", AddInType.Native);

Else

AttachAddIn("DataProcessor. AddIn.Template.AddInLinux64", "MyName", AddInType.Native);

EndIf;

AddInObject = New("AddIn.MyName.ComponentExtension");

NOTE
Please note how parameter in  the New command is  generated.

32.4.1.4. Load from Infobase

Infobase must contain the AddIns catalog and attributes for specified names of the
ValueStorage type with add-in files.

Var Ref;

SysInfo = New SystemInformation;

If SysInfo.PlatformType = PlatformType.Windows_x86 Then

Ref = GetURL(Catalogs.AddIns.FindByCode("000000001"), "AddInWindows32");

ElseIf SysInfo.PlatformType = PlatformType.Windows_x86_64 Then

Ref = GetURL(Catalogs.AddIns.FindByCode("000000001"), "AddInWindows64");

ElseIf SysInfo.PlatformType = PlatformType.Linux_x86 Then

Ref = GetURL(Catalogs.AddIns.FindByCode("000000001"), "AddInLinux32");

Else

Ref = GetURL(Catalogs.AddIns.FindByCode("000000001"), "AddInLinux64");

EndIf;

AttachAddIn(Ref,"MyName", AddInType.Native);
AddInObject = New("AddIn.MyName.ComponentExtension");
2-1182 1C:Enterprise 8.3. Developer Guide

NOTE
Please note how parameter in  the New command is  generated.
Using examples for Native API add-ins the user can also attach COM add-ins for
Windows OS only.

32.4.1.5. Attach Add-In from ZIP Archive

The configuration must contain a  BarcodeReaderDriver common template of
the BinaryData type. This  template stores a  special ZIP archive with add-ins for
all the supported OS, browsers and CPU architecture.
AttachAddIn("CommonTemplate.BarcodeReaderDriver", "Reader");
AddIn = New("AddIn.Reader.BarcodeReader");

NOTE
Please note how parameter in  the New command is  generated.

32.4.2. COM Technology

32.4.2.1. Load Add-In
LoadAddIn("MyComponent.dll");
AddIn = New("AddIn.ComponentExtension");

32.4.2.2. Attach Add-In

AttachAddIn("AddIn.MyObject");
AddIn = New("AddIn.ComponentExtension");

NOTE
LoadAddIn() command is  used for compatibility with previous 1C:Enterprise
versions.
Chapter  33

SPECIFICS
OF CROSS-PLATFORM APPLIED
SOLUTION DEVELOPMENT

This topic contains recommendations on developing applied solutions operating

under Windows OS and Linux OS.

33.1. FILE SYSTEM SPECIFICS

When you work with files in  Linux, you should remember that file and directory
names are case-sensitive. For example, files named file.txt and File.txt are different
files that may be located in  the same directory.
In Linux the concept of drives, which is actively used in Windows, does not
exist. Linux has the root file system ("/") generally used to mount other file
systems located on other media (drives and partitions, flash drives, ISO-files, etc.).
The  most frequently used (though optional!) locations for mounting external media
are the mounting points (directories) /mnt or /media. When you mount external
media, they can be mounted as /media/<Partition label> or /media/<Device ID>.
Automatically mounting an external medium cannot be guaranteed.
Not assigning a  drive letter in  Linux may cause the following problems:
„„ Applied solution uses explicit paths oriented to Windows only;
„„ Applied solution uses path check mechanisms that verify drive letter assign-
ment, among other things;
„„ When you specify a path starting from the root directory, you should
remember that in Linux this path expressly identifies the directory or file
location, whereas in  Windows it  does not. For example, the path \temp\file.txt
2-1184 1C:Enterprise 8.3. Developer Guide

(/temp/file.txt in Linux) points to the exact file location and name in Linux:
it is a file named file.txt and located in the temp directory of the root file
system. In  Windows OS identification is  not unique. This  path indicates that
a  file named file.txt is  located in  the temp directory of the root directory on the
current drive. Moreover, the current drive may be different for two subsequent
launches of the same client application with the same infobase.
When you develop applied solutions, you should remember that Windows and
Linux use different path separators. Windows uses "\" ("back slash"), whereas
Linux uses "/" ("forward slash"). If you work with the 1C:Enterprise script methods,
you do not have to take this difference into account, since these methods work
correctly with any separator. However, if you need to pass the path to an external
application, you should enter the path separators used in the operating system
where 1C:Enterprise is running. You can obtain information on path separators
using the following functions: GetPathSeparator(), GetClientPathSepa-
rator(), GetServerPathSeparator().
In addition to using different path separators, Windows and Linux process
file masks differently. For example, the *.* mask indicates retrieval of all files
in Windows and retrieval of all files containing the period (".") in their names
in Linux. This difference may cause the 1C:Enterprise script methods Find-
Files(), DeleteFiles() and the FileDialog object to behave in unexpected
ways. The specifics of using file masks in different operating systems are
described in the Syntax Assistant for FindFiles() and DeleteFiles() func-
tions. You can obtain a  file mask retrieving all files using the following functions:
GetAllFilesMask(), GetClientAllFilesMask(), GetServerAllFilesMask().
In addition, in Linux you cannot access network resources using UNC notation
(in this case, an address would look like: \\server\folder\folder\file.ext). Therefore,
if you need to use an external network resource, you should first mount it  to the
root file system. You should also remember that you can use a  different mounting
point (directory) every time. You can also access external network resources using
special applications (such as smbclient), but you should remember that these appli-
cations may be missing in  the installation of Linux you are using.
For more detailed information about the Linux file system and how to use it, see the
Linux documentation or internet resources.

33.2. WORKING WITH EXTERNAL DEVICES

External devices are named (and accessed) differently in different operating
systems. For example, serial ports in Windows are named COM1, COM2, etc.
In  Linux (depending on the distribution kit and the device) ports may be named:
/dev/ttyS0, /dev/ttyS1, etc. or: /dev/ttyUSB0, /dev/ttyUSB1, etc. You
should keep this in  mind when you develop both add-ins working with devices and
add-in settings dialogs. For example, obtain a  list of ports that can be specified
in  a data processor directly from the add-in you set up using a  special method.
Chapter 33. Specifics of Cross-platform Applied Solution Development 2-1185

33.3. RIGHTS LIMITATIONS

In general, the super-user account (root) is  not used in  Linux. The  end-user can
only save files to the home directory and the temporary files directory. The  rest
of the file system may either be available in read-only mode or be unavailable
(whether the entire system or just certain directories). Therefore, at the develop-
ment stage you should take into account which access privileges will be granted
to the user who will run 1C:Enterprise for directories returned by global context
methods:
„„ DocumentsDir() – read and write access
„„ BinDir() – read access
„„ TempFilesDir() – read and write access
„„ UserDataWorkDir() – read and write access
To access external devices, the user might be required to join a  specialized group
(or groups). For further details, see the documentation for the operating system you
use.

33.4. FONTS
When you develop applied solutions, it is recommended you always use style
fonts without explicitly specifying the typeface. If required, you can use fonts
included in  Microsoft Core Fonts (http://sourceforge.net/projects/corefonts/). We recom-
mend that you do not use other fonts in  applied solutions, as these fonts may be
unavailable in  some operating systems, and the appearance of the applied solution
would be distorted.

33.5. HTMLDOCUMENTFIELD
In 1C:Enterprise running on Linux, WebKit is used to work with HTML.
In 1C:Enterprise running on Windows, the current version of Internet Explorer
is  used to work with HTML. Therefore, you should remember the following when
you work with HTML:
„„ An HTML document can be displayed differently in different operating
systems.
„„ If you access the DOM-model of an HTML document using the HTMLDocu-
mentField.Document property, you should only use properties and methods
available in  all web browsers that are supported by 1C:Enterprise. This  is  both
due to the use of various tools for displaying HTML documents in  client appli-
cations as well as due to the fact that web access may be used to work with the
applied solution, increasing the number of web browsers and their versions.
2-1186 1C:Enterprise 8.3. Developer Guide

33.6. COM, OLE, AND ACTIVEDOCUMENT MECHANISMS

In Linux these mechanisms are unavailable. Use alternative tools for integration,
such as file exchange in  XML format or web services.
If your add-ins are based on COM technology, we recommend that your redesign
them using NativeAPI.
Appendix  1

URL FORMATS

This Appendix describes link formats used in  1C:Enterprise. Links can be external
or internal. External links are used outside 1C:Enterprise, while internal links are
used internally (e.g., for placement into favorites list or operation history).

1.1. URL FORMAT OVERVIEW

A link includes two parts:
„„ Infobase host address – describes infobase location relative to client application.
This  part of the link can be retrieved via the GetInfoBaseURL() method.
„„ Internal link – describes location of requested information within the infobase.
There are several types of internal links:
„„ infobase object
„„ infobase object attribute
„„ infobase object tabular section attribute
„„ infobase register record attribute
„„ infobase register record
„„ report
„„ data processor
„„ section
„„ section command
„„ temporary storage
To create an external link add an internal link to the host address. If a  link opens
a  form or performs navigation in  the main window, the following rule is  used to
generate an external link:
<IB host address>#<internal link>
2-1188 1C:Enterprise 8.3. Developer Guide

These links can reference infobase objects, reports, data processors, sectionsections
or section commands.
If a  link designates a  resource, an external link is  generated as shown below:
<IB host address>/<internal link>

These links can reference infobase object attributes or information register entries
or temporary storage.
TIP
If multiple clients are used to work with the infobase, it  is  not recommended
to save external links to infobase objects as it  might render links created in  one
client inoperable in  other clients. For example, an external link created in  a web
client could fail in  a thin client directly connected to the 1C:Enterprise server.
It  is  recommended to save internal links.
If an external reference that has the e1cib signature in  its path is  passed to the
GotoURL() method or a  URL dialog, and the reference beginning does not match
with an infobase URL, internal reference is  extracted from the passed URL and
an attempt to go to the extracted part is  made. If the attempt fails, the full URL
is navigated.

1.2. HOST ADDRESS FORMAT

Depending on the infobase type a  host address string might look differently.
File Mode of Infobase
If UNC format is used for the database file path, host address looks like the
following:
e1c:/file/<UNC-path>

Example:
// Infobase file path
{0>\\dbsrvr\bases\mybase<}0{>\\dbsrvr\bases\mybase

// Host address
e1c:/file/dbsrvr/bases/mybase

If the file path includes the drive letter, host address looks like the following:
e1c:/filev/<Drive letter>/<Base path>

Example:
// Infobase file path
{0>s:\bases\mybase<}0{>s:\bases\mybase
// Host address
e1c:/filev/s/bases/mybase
Appendix 1. URL Formats 2-1189

Client/Server Mode of Infobase

For the client/server mode of infobase, link looks like the following:
e1c://server/<server name>/<infobase name>

Example:
// Infobase connection string
srvsr="srv1C";ref="mybase"

// Host address
e1c://server/srv1C/mybase

Use of Web Server (Thin Client or Web Client)

If Web server is  used to work with the infobase, link looks like the following:

httр://<host address>/<infobase path>

httрs://<host address>/<infobase path>

Example:
// Infobase connection string
http://localhost/mybase

// Host address
http://localhost/mybase

1.3. INTERNAL LINKS

In general, internal link format looks like the following:
e1cib/<type>/<path>?<parameters>

For a  more detailed description of type-dependent link formats see below.

1.3.1. Infobase Object Link

Format:
e1cib/data/<metadata path>?ref="<link ID>"

Where:
„„ Metadata path – type of object referenced by the link, e.g., Document.Go-
odsConsumption.
„„ Link ID – unique object identifier in  the infobase.
2-1190 1C:Enterprise 8.3. Developer Guide

1.3.2. Infobase Object Attribute Link

Format:
e1cib/data/<metadata path>.<attribute name>?ref="<link ID>"

Where:
„„ Metadata path – type of object referenced by the link, e.g., Document.
GoodsConsumption.
„„ Attribute name – name of infobase object attribute.
„„ Link ID – unique object identifier in  the infobase.

1.3.3. Infobase Object Tabular Section Attribute Link

Format:
e1cib/data/<metadata path>.<tabular section name>.<attribute name>?ref="<link ID>"&index="<tabular section row index>"

Where:
„„ Metadata path – type of object referenced by the link, e.g., Document.
GoodsConsumption.
„„ Tabular section name – name of metadata tabular section, e.g., Goods.
„„ Attribute name – name of infobase object tabular section attribute.
„„ Link ID – unique object identifier in  the infobase.
„„ Tabular section row index – index of tabular section row.

1.3.4. Infobase Register Record Link

Format:
e1cib/data/<metadata path>?<key field name>="<value>"[&<key field name>="<value>"]

Where:
„„ Metadata path – type of object referenced by the link, e.g., InformationReg-
ister.ProductInventory.
„„ Key field name – name of register dimension (Period dimension is  added for
periodic registers).
„„ Value is an internal presentation of a  filter value. A filter value is  coded as
described in  section 2.2. URL Character Encoding Issues compliant with the
RFC 1738 standard (http://www.faqs.org/rfcs/rfc1738.html) – with the help of the %
symbol and two hexadecimal characters.
Appendix 1. URL Formats 2-1191

1.3.5. Infobase Register Record Attribute Link

Format:
e1cib/data/<metadata path>.<attribute name>?<key field name>="<value>"[&<key field name>="<value>"]

Where:
„„ Metadata path – type of object referenced by the link, e.g., InformationReg-
ister.ProductInventory.
„„ Attribute name – name of record attribute.
„„ Key field name – name of register dimension (Period dimension is  added for
periodic registers).
„„ Value – internal presentation of filter value.

1.3.6. Report Link

Format:
e1cib/app/<metadata path>

Where:
„„ Metadata path – type of object referenced by the link, e.g., Report.Pro-
ductInventory.

1.3.7. Data Processor Link

Format:
e1cib/app/<metadata path>

Where:
„„ Metadata path – type of object referenced by the link, e.g., DataProces-
sor.OrderIssue.

1.3.8. Section Link

Format:
e1cib/navigationpoint/<section name>

Where:
„„ Section name – name of top-level subsystem referenced by the link, e.g.,
Goodsales.
2-1192 1C:Enterprise 8.3. Developer Guide

1.3.9. Link to the Navigation Point Created by

the Standard Command
Format:
e1cib/navigationpoint/<section name>/<command name>

Where:
„„ Section name – name of top-level subsystem referenced by the link, e.g.,
Goodsales.
„„ Command name – name of command. E.g. Catalog.Products.OpenList.

1.3.10. Temporary Storage Link

Format:
e1cib/tempstorage/<temporary value ID>

Where:
„„ Temporary value ID – identifier of temporary value.

1.3.11. Link to an External Data Source Table Record

Format:
e1cib/data/<metadata path>?<key field name>=<value>[&<key field name>=<value>]

Where:
„„ Metadata path describes an external data source table, for instance Exter-
nalDataSource.Receipts.Table.CheckHeaders.
„„ Key field name is  a key field name of an external data source table.
„„ Value is an internal presentation of a  filter value. A filter value is  coded as
described in  section 2.2. URL Character Encoding Issues compliant with the
RFC 1738 standard (http://www.faqs.org/rfcs/rfc1738.html) – with the help of the %
symbol and two hexadecimal characters.

1.3.12. Links to Global Command Interface Commands

Format:
e1cib/command/<command name>

Where:
„„ command name is  the command name:
○○ standard command is Catalog.Goods.Create;
Appendix 1. URL Formats 2-1193

○○ common command is CommonCommand.ObjectSearch;

○○ command is Catalog.Goods.Command.PrintBarcode.

1.3.13. Links to Lists

Format:
e1cib/command/<list name>

Where:
„„ list name is  the name of the list being opened, e. g. Catalog.Goods.Docu-
ments.GoodsConsumption.

1.3.14. Link to the start page

Format:
e1cib/navigationpoint/desktop

In compatibility mode with version 8.3.2 or later.

Format:
e1cib/navigationpoint/startpage

In compatibility mode with versions earlier than version 8.3.2.

2-1194 1C:Enterprise 8.3. Developer Guide
Appendix  2

RULES FOR GENERATING

STANDARD COMMANDS AND
AUTOMATIC FORM HEADERS

To ensure that object presentation can be overridden (or adjusted) in  the interface,
a  special set of properties has been introduced in  metadata properties.
(for register – record presentation)

(for register – record presentation)

Extended object presentation

Extended list presentation

Extended presentation

Object presentation

Object
List presentation

Explanation

Picture

Subsystems + +
Constants + +
Exchange Plans + + + + +
Filter Criteria + + +
Common Forms + +
Constants + +
Catalogs + + + + +
Documents + + + + +
Document Journals + + +
Enumerations + + +
2-1196 1C:Enterprise 8.3. Developer Guide

(for register – record presentation)

(for register – record presentation)

Extended object presentation

Extended list presentation

Extended presentation

Object presentation
Object

List presentation

Explanation

Picture
Reports + +
Data Processors + +
Charts of Characteristic Types + + + + +
Charts of Accounts + + + + +
Charts of Calculation Types + + + + +
Information Registers (subordinate) + + +
Information Registers (independent) + + + + +
Accumulation Registers + + +
Accounting Registers + + +
Calculation Registers + + +
Business Processes + + + + +
Tasks + + + + +

When generating presentation for standard commands (and their tooltips) the
system applies the following rules (Property1 → Property2 means that if Property1
is not specified, Property2 is used instead):
„„ Opening a  list:
○○ Command presentation: List presentation.
○○ Command tooltip: Explanation → Extended list presentation → List presen-
tation.
„„ Creating a  new object (record):
○○ Command presentation: Object presentation: Create or Record presentation:
Create.
○○ Command tooltip: Extended object presentation (Extended record presenta-
tion) → Object presentation (Record presentation).
„„ Creating a new folder:
○○ Command presentation: List presentation: Create Folder.
○○ Command tooltip: Extended object presentation → List presentation.
„„ Navigating to any subordinate list (Go To folder command in form navigation
panel):
○○ Command presentation: List presentation.
Appendix 2. Rules for Generating Standard Commands and Automatic Form Headers 2-1197

○○ Command tooltip: Explanation → Extended list presentation → List presen-

tation.
„„ Generating:
○○ Command presentation: Object presentation: Generate.
○○ Command tooltip: Extended object presentation → object presentation.
„„ Opening a  report or data processor:
○○ Command presentation: report or data processor presentation.
○○ Command tooltip: Explanation → Extended presentation.
„„ Opening a  common form:
○○ Command presentation: common form presentation.
○○ Command tooltip: Explanation → Extended presentation.
„„ Opening a  constant editing form:
○○ Command presentation: constant presentation.
○○ Command tooltip: Explanation → Extended presentation.
„„ Navigating to subsystem (in sections panel):
○○ Command presentation: subsystem presentation.
○○ Graphical presentation: Picture → standard picture of sections panel section.
○○ Command tooltip: Explanation.
NOTE
If none of the properties used (in presentation and/or tooltip generation)
is  specified, text presentation of metadata object is  used as it  is  returned by the
Presentation() method.
The following rules applies to placement of a  command in  form actions panel or
command bar: command group name (preceded by ":" character) is  removed from
the command text presentation if this combination finalizes command presentation.
For example, standard item creation command for a  Goods catalog that is  repre-
sented as Goods: Create is  displayed as Goods in  the actions panel. If the user
creates a  command with My Command: Generate presentation and places it  in  the
standard Generate group in the form command bar, the command presenta-
tion turns to My Command. At the same time, if this command is  placed in  the
Print group (created by the developer) in  the form command bar, its presentation
remains My Command: Generate.
Properties associated with object presentation (see table above) are also used
in form header generation if the Auto title property is set to True for the form.
In  this case the form header combines the Title property value and the auto-gener-
ated header. If this property is  set to False, form header is  derived from the Title
property with no transformations.
2-1198 1C:Enterprise 8.3. Developer Guide

When auto-generating form headers the system applies the following rules:
„„ List form header: Extended list presentation → List presentation.
○○ Form header for catalog, chart of accounts, chart of calculation types,
exchange plan, chart of characteristic types and task:
□□ Existing item: text presentation of object (Extended object presentation
→ object presentation), e.g.:
• Zinovyev Anton (Employee).
• 70.1 (Account).
○○ New item: Extended object presentation (Creation) → Object presentation
(Creation).
„„ Document or business process form header:
○○ Existing item: text presentation of object, e.g.:
□□ Receipt # 12001 from 05/12/2008 16:15:32.
○○ New item: Extended object presentation (Creation) → Object presentation
(Creation).
„„ Information register record form header:
○○ Existing record: Extended record presentation → Record presentation.
○○ New record: Extended record presentation (Creation) → Record presenta-
tion (Creation).
„„ Form header for catalog folder or chart of characteristic types:
□□ Existing folder: text presentation of object (Extended list presentation →
List presentation).
□□ New folder: Extended list presentation (Folder Creation) → List presen-
tation (Folder Creation).
„„ Report or data processor form header: Extended presentation.
NOTE
If none of the properties used in  header generation is  specified, text presentation
of metadata object is  used as it  is  returned by the Presentation() method.
Appendix  3

LIST OF AUTO-SAVED
SETTINGS

This appendix describes settings auto-saved in  the system storage by the platform.

Storage: Report Variants

Settings: Report Variants
„„ Object key – full report name.

An example of an object key:

Report.Sales

„„ Setting key – text ID of variant.

An example of an object key:

SalesByRegion

„„ Saved value type – DataCompositionSettings.

Storage: Report Settings

Settings: Report Settings
„„ Object key – text string including full report name, "/" character and variant
key.
An example of an object key:
Report.Sales/SalesByRegion
2-1200 1C:Enterprise 8.3. Developer Guide

„„ Setting key – text ID of setting.

An example of an object key:

MyClients

„„ Saved value type – DataCompositionUserSettings.

Form Data Storage

Settings: Form Field Values
„„ Object key – full form name.

An example of an object key:

DataProcessor.DataDump.Form.DefaultForm

„„ Setting key – text ID of saved values.

An example of an object key:

DumpToSberbank

„„ Saved value type – Map. Map key is path to saved data attribute and its
value is  attribute value.

System Repository
Settings: Current Report Variant Key
„„ Object key – text string including full report name and /CurrentVariantKey
string. An example of an object key:
Report.Sales/CurrentVariantKey

If the PurposeUseKey property is set for a form, an object key is gener-

ated as follows: the full report name, /, PurposeUseKey property value and
/CurrentVariantKey string.

An example of an object key:

Report.Sales/ForDiscountChargeForm/CurrentVariantKey

In this example the PurposeUseKey property is set to ForDiscountCharge-

Form.
„„ Setting key – empty string.
„„ Saved value type – any value containing the current variant key.
Appendix 3. List of Auto-Saved Settings 2-1201

Settings: Current Report Setting Key

„„ Object key – string value including full report name, report variant key
(represented as a  string) and /CurrentUserSettingsKey text.
An example of an object key:
Report.Sales/SalesByRegion/CurrentUserSettingsKey

If the PurposeUseKey property is  set for a  form, an object key is  generated
as follows: the full report name, /, report variant key as a string, /, Purpo-
seUseKey property value and /CurrentUserSettingsKey string.
An example of an object key:
Report.Sales/SalesByRegion/ForDiscountChargeForm/CurrentUserSettingsKey

In this example, the report variant key is  set to SalesByRegion, and the Purpo-
seUseKey property is  set to ForDiscountChargeForm.
„„ Setting key – empty string.
„„ Saved value type – any value containing the current variant key.

Settings: Report Variant Settings On Report Close

or Variant Change
„„ Object key – string value including full report name, report variant key
(represented as a  string) and /CurrentUserSettings text.
An example of an object key:
Report.Sales/SalesByRegion/CurrentUserSettings

If the PurposeUseKey property is  set for a  form, an object key is  generated
as follows: the full report name, /, report variant key as a string, /, Purpo-
seUseKey property value and /CurrentUserSettings string.
An example of an object key:
Report.Sales/SalesByRegion/ForDiscountChargeForm/CurrentUserSettings

In this example, the report variant key is  set to SalesByRegion, and the Purpo-
seUseKey property is  set to ForDiscountChargeForm.
„„ Setting key – empty string.
„„ Saved value type – DataCompositionUserSettings.
2-1202 1C:Enterprise 8.3. Developer Guide

Settings: Form Field Current Setting Key

„„ Object key – string value including full form name and
/CurrentDataSettingsKey text.

An example of an object key:

DataProcessor.DataDump.Form.DefaultForm/CurrentDataSettingsKey

If the PurposeUseKey property is set for a form, an object key is gener-

ated as follows: the full form name, /, PurposeUseKey property value and
/CurrentDataSettingsKey string.

An example of an object key:

DataProcessor.DataDump.Form.DefaultForm/ForDiscountChargeForm/CurrentDataSettingsKey

In this example the PurposeUseKey property is set to ForDiscountCharge-

Form.
„„ Setting key – empty string.
„„ Saved value type – any value containing the current setting key.
Settings: Form Field Values On Close
„„ Object key – string value including full form name and /CurrentData text.

An example of an object key:

DataProcessor.DataDump.Form.DefaultForm/CurrentData

If the PurposeUseKey property is  set for a  form, an object key is  generated
as follows: the full form name, /, PurposeUseKey property value and /Current-
Data string.

An example of an object key:

DataProcessor.DataDump.Form.DefaultForm/ForDiscountChargeForm/CurrentData

In this example the PurposeUseKey property is set to ForDiscountCharge-

Form.
„„ Setting key – empty string.
„„ Saved value type – Map. Map key is path to saved data attribute and its
value is  attribute value.
Settings: Form Display Setting
„„ Object key – string value including full form name and /FormSettings text.
Appendix 3. List of Auto-Saved Settings 2-1203

An example of an object key:

DataProcessor.DataDump.Form.DefaultForm/FormSettings

„„ Setting key – empty string.

„„ Saved value type – FormSettings. Object with no properties and methods.

Settings: Form and Control Size, Separator Location

and Table Column Width
„„ Object key – string value including full form name and /WindowSettings
text.
An example of an object key:
DataProcessor.DataDump.Form.DefaultForm/WindowSettings

If the WindowOptionsKey property is specified for a form, object key

includes the key value: <WindowOptionsKeyValue>/WindowSettings. Thus,
if options key value is  DefaultMode for a  window, the above example looks
like the following: DataProcessor.DataDump.Form.DefaultForm/DefaultMode/
WindowSettings.
„„ Setting key – empty string.
„„ Saved value type – WindowSettings. Object with no properties and
methods.
Settings: Application Main Window Settings
„„ Object key – string value MainWindow/WindowSettings.
„„ Setting key – empty string.
„„ Saved value type – WindowSettings. Object with no properties and
methods.
Settings: Desktop Settings
„„ Object key – Common/DesktopSettings.
„„ Setting key – empty string.
Saved value type – DesktopSettings.Settings: Desktop
Separator Location
„„ Object key – string value:
○○ Desktop/WindowSettings in compatibility mode with version 8.3.2 or
later.
○○ StartPage/WindowSettings in  compatibility mode with versions earlier
than version 8.3.2.
○○ StartPage/Taxi/WindowSettings if the Taxi interface is  used.
2-1204 1C:Enterprise 8.3. Developer Guide

„„ Setting key – empty string.

„„ Saved value type – WindowSettings. Object with no properties and
methods.
Settings: Form and Control Size, Separator Location
and Table Column Width in Web Client
„„ Object key – string value including full form name and
/WebClientWindowSettings text.
Example:
DataProcessor.DataDump.Form.DefaultForm/WindowSettings

„„ Setting key – empty string.

„„ Saved value type – WindowSettings. Object with no properties and
methods.
Settings: Start Page (Desktop)
„„ Object key – string value:
○○ Common/DesktopSettings in  version 8.3.2 and older compatibility mode
○○ Common/StartPageSettings in compatibility mode with version later
than 8.3.2
„„ Setting key – empty string.

Saved value type  StartPageSettings.

Object with no properties and methods.Settings: Favorites
„„ Object key – Common/UserWorkFavorites.
„„ Setting key – empty string.
„„ Saved value type – UserWorkFavorites.
Settings: Global Command Interface Settings
„„ Object key – string value; one of the options:
○○ full name of command interface section and /ActionsPanel
○○ full name of command interface section and /NavigationPanel/Command-
InterfaceSettings
○○ Common/PartitionPanel/CommandInterfaceSettings
○○ MainSection/ActionsPanel/CommandInterfaceSettings – desktop actions
panel settins (in compatibility mode older than version 8.3.2)
○○ Desktop/NavigationPanel/CommandInterfaceSettings – desktop naviga-
tion panel settings (in compatibility mode later than version 8.3.2)
Appendix 3. List of Auto-Saved Settings 2-1205

○○ MainSection/NavigationPanel/CommandInterfaceSettings – navigation
panel settings (in compatibility mode older than version 8.3.2)
Example:
Subsystem.Sales/NavigationPanel/CommandInterfaceSettings
Desktop/ActionsPanel/CommandInterfaceSettings

Setting key – empty string.

Saved value type – CommandInterfaceSettings.
Settings: Spreadsheet Document Print Settings
„„ Object key – string value including Common/SpreadsheetDocument-
PrintSettings/ and print parameter name. For example, Common/
SpreadsheetDocumentPrintSettings/Invoice.
„„ Setting key – empty string.
„„ Saved value type – SpreadsheetDocumentPrintSettings.
Settings: client application settings
„„ Object key  – string value Common/ClientSettings.
„„ Setting key – empty string.
„„ Saved value type  – ClientSettings. Object with no properties and
methods. Stores the following settings: whether the All actions command
is  displayed. whether the debug mode is  enables on startup, where the slow
connection mode is  enabled (for the web client), and the External parameter
of the Get link dialog box.
„„ For the Taxi interface mode, it  also stores the following settings: changes
in  the list of displayed panels and their positions, as specified in  Designer.
Settings: add-in settings
„„ Object key  – string value AddInSettings/<AddInSettingName>). String value
<AddInSettingName> is defined by the add-in using the RegisterPro-
fileAs() method.

An example of an object key:

AddInSettings/BarCodeScanner

„„ Setting key – empty string.

„„ Saved value type – AddInSettings. Object with no properties and methods.
Settings: help system settings
„„ Object key  – string value Common/HelpSettings.
„„ Setting key – empty string.
2-1206 1C:Enterprise 8.3. Developer Guide

„„ Saved value type – HelpSettings. Object with no properties and methods.

Settings: color settings for file comparison parameters
„„ Object key  – string value Common/ComparisonSettings.
„„ Setting key – empty string.
„„ Saved value type – ComparisonSettings. Object with no properties and
methods.
Settings: search history
„„ Object key  – string value Common/TableSearchParameters.
„„ Setting key – empty string.
„„ Saved value type – value list containing a  list of history strings. The  latest
items are in  the beginning of the list.
Appendix  4

FULL-TEXT SEARCH
EXPRESSIONS

You can search by several words, exact phrases or using search operators.
By default synonym-based search and fuzzy search are not used. To perform
searches of these types use the appropriate operators.
The following search operators can be used in the input string (both for Help/
Syntax Assistant search and for 1C:Enterprise script FullTextSearch object):
Operator Sample Expression Explanation
Space Business Success Both "Business" and "Success" must be included
AND Business AND Success
AND Business AND Success
& Business & Success
OR Business OR Success Either "Business" and "Success" must be included
OR Business OR Success
| Business | Success
, Business , Success
NOT Business NOT Success "Business" must be included, while "Success" must not
NOT Business NOT Success
~ Business ~ Success
NEAR/[±]n Example 1: Searches for data that have the specified words in  the same
NEAR/[±]n drier NEAR/3 air attribute (with account taken of morphology) separated by n
Example 2: words.
drier NEAR/+3 air The sign determines where the second word should be
Example 3: located with respect to the first word (+ – after the first word;
drier NEAR/-3 air - – before it).
If no sign is  specified, the search returns data that contain
the words separated by n words. Their order is  not important.
Example 1 returns data with "air" separated from "drier" by
a  maximum of 3 words and located before or after "drier".
Example 2 returns data with "air" separated from "drier" by
a  maximum of 3 words and located after "drier".
Example 3 returns data with "air" separated from "drier" by
a  maximum of 3 words and located before "drier".
2-1208 1C:Enterprise 8.3. Developer Guide

Operator Sample Expression Explanation

NEAR Library NEAR n.a. NEAR Short form. The  query finds data with both words in  the
NEAR Dostoyevsky same attribute; the words can be separated by a  maximum of
8 words and located in  any position.
"" "network administrator" Finds exact terms (equivalent to "network NEAR/+1 admin-
istrator)
() (process | production) & Word grouping (any number of nesting levels)
(cheese | cottage cheese)
* arch* Searches using a  wildcard  – any number of "*" characters
arch* & docfl* can be inserted anywhere in  the word. Thus, "arch*" query
can find "archive" and "archeology"

The AND or, NOT and NEAR operators must be entered in  upper case only. Operators
must not be used on their own (at the beginning of the search string). For example,
it  is  not possible to select all the chapters without the specified text. All the char-
acters in  the search box except for search operators, letters and digits are ignored.
When using 1C:Enterprise script FullTextSearch object please remember the
following:
Operator Sample Expression Explanation
* arch* Searches using a  wildcard  – only one "*" character
arch* & docfl* is  supported and should be added to the end of the word.
Thus, "arch*" query can find "archive" and "archeology"
# #System Fuzzy search for words with the number of differences
System#2 specified in  the search box.
"#System" query (equivalent to "System#1") can return
"sustem" or "syxtem".
"System#2" query can return "suxtem" or "syytem".
It can only be used in  full-text search
! !red tile Search is  performed using synonyms in  English, Russian
and Ukrainian. "!" operator precedes the relevant word.
Example: "!red tile" query finds "scarlet tile" and "coral tile"
as well

The AND or, NOT and NEAR operators must be entered in  upper case only. Operators
must not be used on their own (at the beginning of the search string). For example,
it  is  not possible to select all the chapters without the specified text.
To look up special characters used in texts enclose them in quotation marks.
Example: "NEAR".
Appendix  5

DESCRIPTION
OF ACCESS RIGHTS

This annex describes all the access rights that can be managed when you edit roles
in 1C:Enterprise.
„„ Automation – using the automation server.
„„ Administration:
○○ Administrative rights for the whole infobase and user list editing
(the configuration right). Requires DataAdministration.
○○ An ability to configure connection options (for an external data source).
○○ Display of licenses, that were used when operating with the configuration
and infobase, in  the About 1C:Enterprise window.
○○ Deleting data areas (including the deletion of all the areas at once).
○○ An ability to execute background database configuration update on the
client side.
„„ DataAdministration – this right regulates administrative actions with data.
These actions include:
○○ viewing event log records and getting filter values without restrictions.
○○ setting the infobase (data area) time zone (calling the SetInfoBa-
seTimeZone() method).
○○ Creating an initial image for the distributed infobase subordinate node
(calling the CreateInitialImage method).
○○ Refreshing object numbering (calling the RefreshObjectsNumbering()
method).
○○ Executing the StandardSettingsStorageManager object method,
if non-current user settings are processed.
„„ ActiveUsers – view the list of active users.
2-1210 1C:Enterprise 8.3. Developer Guide

„„ InputByString – use of the input by string mode.

„„ WebClient – the right to start a  web client.
„„ ExternalConnection – external connection.
„„ Output – print information, save it  to a  file or copy to the clipboard.
„„ Execute – execute the task.
„„ Insert – insertion (main).
„„ EventLog – the right to view the event log.
„„ Update – change (main).
„„ StandardAuthenticationChange – the user has the right to change his/her
standard authentication options (the Standard Authentication, User Name, Pass-
word properties) of an external data source.
„„ SessionOSAuthenticationChange – the user has the right to change the
parameters of external data source OS authentication in his settings and
in  session parameters.
„„ SessionStandardAuthenticationChange – the user has the right to change
standard authentication options (the Standard Authentication, User Name, Pass-
word properties) of an external data source for the current session.
„„ InteractiveActivate – interactive activation.
„„ InteractiveUndoPosting – interactive posting cancel.
„„ InteractiveSetDeletionMark – interactive deletion mark.
„„ InteractiveSetDeletionMarkPredefinedData – enables interactive
setting of deletion mark for predefined data.
„„ InteractiveExecute – interactively execute the task.
„„ InteractiveInsert – interactive insertion.
„„ InteractiveChangePosted – interactive editing of the posted document.
If the right is not set, the user can't delete the posted document, mark the
document for deletion, repost the document or clear posting. A form of this
document is  opened in  viewing mode.
„„ InteractiveOpenExtDataProcessors – interactive opening external
handlings.
„„ InteractiveOpenExtDataReports – interactive opening external reports.
„„ InteractivePosting – interactive posting.
„„ InteractivePostingRegular – interactive posting (by standard form
commands) of the document is  done in  regular mode.
„„ InteractiveClearDeletionMark – interactive deletion mark cancel.
„„ InteractiveClearDeletionMarkPredefinedData – enables interactive
clearing of deletion mark for predefined data.
„„ InteractiveDelete – direct interactive deletion.
„„ InteractiveDeleteMarked – interactive deletion of marked objects.
Appendix 5. Description of Access Rights 2-1211

„„ InteractiveDeleteMarkedPredefinedData – enables interactive deletion

of marked predefined data.
„„ InteractiveDeletePredefinedData – enables interactive deletion of prede-
fined data.
„„ InteractiveStart – the right to interactively start a  business-process.
„„ Use – use this or that configuration object.
„„ ExclusiveMode – use of the exclusive mode.
„„ UpdateDataBaseConfiguration – allows you to execute database configura-
tion updates. You can only have this right to execute configuration updates on
the server or background configuration updates on the server. The  Adminis-
tration right is  not required in  this case.
„„ UndoPosting – cancel documents posting.
„„ Get – getting a  value which is  not stored in  the database.
„„ Posting – documents posting.
„„ View – viewing.
„„ Edit – editing.
„„ AllFunctionsMode – manages All functions command availability in  the main
menu and manages the availability of the corresponding client application
setting.
„„ SaveUserData – manages an ability to save user settings. If the right is  disa-
bled, then:
○○ The History button is  not available, accessing the history from 1C:Enterprise
script raises an exception, interactive writing operations are not registered
in  the history.
○○ The Favorites command is not available in the system command bar.
The  Add to favorites button is  not available in  Get link and Go to link forms.
When favorites are accessed in  1C:Enterprise script, an exception is  raised:
○○ Form configuration is not available (the Change form command is not
present).
○○ Section panel, navigation panel and start page configuration commands are
not available.
○○ User settings and report variant saving commands are not available
in reports. A prompt to remember any changes applied by a user in the
current report variant is not shown. Changes are not saved. Select report
settings command is available only if report user settings storage is set
for the report or configuration. When the SetCurrentUserSettings()
method is  called, an exception is  raised.
○○ Save form data and restore form data commands are not available (the Save
settings and Select settings commands). Form data are not automatically
saved.
2-1212 1C:Enterprise 8.3. Developer Guide

○○ Window settings (size and position) are saved only during the session.
○○ Main window panel size settings are saved only during the session.
○○ When settings are programmatically saved, an exception is  raised.
○○ Client application settings are saved only during the session. The Allow
debugginf on startup checkbox is  not shown (for a  thin client and a  thick
client). The  Slow connection checkbox is  not shown (for a  web client).
○○ Period settings in the list are not saved. The Use this period next time
the form is  opened checkbox is  not available in  the period configuration
dialog.
„„ Start – the right to start a  business process.
„„ ThickClient – the right to start a  thick client.
„„ ThinClient – the right to start a  thin client.
„„ Delete – deletion (main).
„„ TotalsControl – controlling accounting register totals and accumulation
register totals (setting the period until which totals are calculated and totals
recalculation).
„„ Set – setting a  value which is  not saved in  the database.
„„ Read – reading (main).
Appendix  6

SYSTEM BEHAVIOR
IN  VARIOUS MODES

6.1. SPECIAL CHARACTERISTICS

OF LOW CONNECTION SPEED MODE
In the low connection speed mode the system behavior acquires the following
special characteristics:
„„ Desktop forms are not displayed automatically. To display the desktop click
the Show Desktop hyperlink in  the top left corner of the desktop working area.
In  Taxi interface the start page is  displayed once you open the application.
„„ When a  form is  generated, presentations for form reference data are obtained
(after the form is  opened no additional calls are made to the server to retrieve
presentations).
„„ When a form is generated, "over-the-period" form data values displayed by
form elements are obtained (after the form is opened no additional calls are
made to the server to retrieve these values).
„„ The server notifies the user forms have been closed (or object locks – released if
objects have been locked) after 20 forms have been closed or 20 s have elapsed
after form closing.
○○ Getting a  form from a  server using the OpenForm(), GetForm() methods.
○○ Calling server (context and out-of-context) form methods.
○○ Closing 20 forms.
○○ The system is  the waiting state for more than 20 seconds.
○○ When the following dynamic list commands are executed:
□□ deleting an item;
□□ marking an item for deletion;
2-1214 1C:Enterprise 8.3. Developer Guide

□□ posting a  document or canceling a  posting;

□□ moving a  catalog item to another group.
„„ Settings are only saved if modified. Moreover, it  does not happen immediately
after form closing, the procedure is  delayed until the next form is  opened, 20
delayed settings have accumulated, 20 min have elapsed (when idle) or the
application is  closed.
„„ Client application neither receives nor displays pictures of sectionsections
panel.
„„ Initial status of selection form is  cached and re-used upon re-creation of this
form. Form data are removed from cache if:
○○ The form has not been in  use for the last 20 min.
○○ Refresh command has been called in  the selection form.
○○ Data changes for an object of relevant type are displayed on the client side.
„„ Selection list is  not generated in  the text box while waiting for input by string
to complete.
„„ A special data cache is  generated for quick selection lists and input-by-string
lists. Cache data are saved for a  session lifetime. A maximum of 20 latest lists
can be stored for each object type. Cache can store a  maximum of 200 lists.
Every 20 min cache is cleared of expired data related to objects that have
changes displayed in  this session on the client side.
Repeat selection or input by string operation with the same parameters without
moving to another field creates a  new data query to the server.

6.2. SPECIAL CHARACTERISTICS OF COMPATIBILITY MODE

A number of system mechanisms can vary their behavior depending on the Compat-
ibility mode configuration property. The  present section lists the possible behavior
differences:
„„ You cannot set Default run mode to Managed application when the Compatibility
mode configuration property is  set to Version 8.1. These settings are checked
when updating the configuration database.
„„ In the Version 8.1 Compatibility Mode, the Subsystems property of the
metadata objects that could belong to subsystems is available from the
1C:Enterprise script. Moreover, the Version 8.1 Compatibility Mode makes the
Content configuration property available. This  property is  filled with refer-
ences to objects that belonged to subsystem tree root item. If you disable the
Version 8.1 Compatibility Mode, the Content configuration property is  cleared
and becomes unavailable in  the configuration properties panel.
„„ In ordinary forms, the object filling procedure is  similar to Version 8.1, i.e. the
filling handler is  called for Enter Based On only or when the Fill() method
is invoked.
Appendix 6. System Behavior in Various Modes 2-1215

„„ The FillCheck() method is unavailable for metadata objects; auto-check

is  not used.
„„ You can invoke help from a  form the same way you did in  Version 8.1, i.e.
open a  dialog box where you can select a  help section if no help is  provided
for the current form.
„„ Document journal tables contain Type virtual field.
„„ Infobase table list of the query wizard displays tables and fields that can be
viewed by the current user.
„„ The data composition system does not validate interactive rights to tables.
„„ Pictures selected in the picture library and inserted into a report or a data
processor are converted to external pictures.
„„ The Type property is available for DataCompositionAvailableField,
DataCompositionFilterAvailableField and DataCompositionAvaila-
bleParameter objects.
„„ The DataVersion property is  unavailable for catalogs, documents, charts of
characteristic types, charts of accounts, charts of calculation types, exchange
plans, business processes and tasks. Data access restrictions for the DataVer-
sion field are checked based on the restrictions set for the Ref field.
„„ Setting the InteractiveInsert, InteractiveDelete, Interac-
tiveSetDeletionMark, InteractiveClearDeletionMark, Interacti-
veDeleteMarked, InteractivePosting, InteractivePostingRegular,
InteractiveUndoPosting, InteractiveChangeOfPosted, Interac-
tiveStart, InteractiveActivate and InteractiveExecute rights is  not
related to setting the Edit right.
„„ As you dump configuration files, an ordinary application module is  dumped to
Configuration.ApplicationModule.txt.
„„ Formatting Number, Date and Boolean values is  based on parameters speci-
fied in  the regional infobase settings.
„„ Web colors in the color selection dialog box are ordered by their English
names.
„„ You can assign any values to spreadsheet document Output and PageOrien-
tation properties. Values of invalid types are ignored.
„„ You can interactively select the following pictures: DocumentOb-
ject, ChartOfCharacteristicTypesObject, ScheduledJobs,
CatalogObject, BusinessProcessObject, TaskObject, ChartOfCalcu-
lationTypesObject, ExchangePlanObject, ChartOfAccountsObject,
InformationRegisterRecord, ChooseFromList, AddListItem, NewFolder,
ChangeListItem, SetListItemDeletionMark, DeleteListItemDirectly
and DeleteListItem.
„„ Contains comparison type of the data composition system counts _, % and [ as
special characters.
2-1216 1C:Enterprise 8.3. Developer Guide

„„ CAST operation of the query language returns a fixed-length string (with

trailing white spaces) when you perform casting to the String type.
„„ Print parameters for individual spreadsheet documents (objects) are not sepa-
rated and are modified at the same time (even if the print parameter key is  a
match).
„„ If a  query contains the DISTINCT keyword and an expression missing from the
selection list is  specified in  the ORDER BY clause, this query is  valid and does
not raise an error.
„„ Nested query balance fields are not treated as balance fields in an external
query and totals for these fields are calculated in  the same way as for standard
fields.
„„ Maximum size of String of Fixed Size metadata attribute is  1024 characters.
„„ New accumulation and accounting registers do not have their totals splitting
flag set by default.
„„ Representation of complete module names in technological information
(technological log, event log, etc.) has been modified: names do not specify the
module precisely.
„„ When you execute the Lock() method in  managed lock items, only the first
lock value in  each item is  checked against the lock field type.
„„ Synonym modification in the form and template wizards changes the name,
while the name change modifies the synonym if none of these auto-generated
field values has been changed after opening the wizard.
„„ The picture editor does not support the alpha channel. After you complete
editing, pictures are not converted to PNG.
„„ Title of an active table column in  a form is  highlighted.
„„ Pressing Tab or Shift + Tab in  a form table with no rows or with the Row selec-
tion mode on activates the next or previous column, accordingly. The  next or
previous form element is  only activated after you reach the last or the first table
column.
„„ The following properties are available for spreadsheet documents: GroupBack-
Color, GroupTextColor, HeaderBackColor and HeaderTextColor.
„„ If you select a custom border or border color for a form element or choose
a  custom button background color for a  Button, Text Box or Slider elements,
the form element is  displayed with the selected color and the border corners are
not rounded.
„„ BeforeClose form handler is  not called if modal form times out.
„„ When event log is  dumped in  XML format, the UserName field displays the
full user name.
„„ User with no administrative permissions can modify the CannotChangePass-
word property of the InfoBaseUser object.
Appendix 6. System Behavior in Various Modes 2-1217

„„ When a  template is  received on a  server and in  an external connection, the
default configuration language is  set as the template language.
„„ The Data Path property of the data composition template user field is  generated
in English.
„„ When a  normal form of an information register record is  opened, the Period
property value is  set to the current data, but only if this property is  not filled
and the form record is  opened from a  list form. For all other cases, this prop-
erty is  not populated.
„„ Contents of tables describing scheduled jobs are changed:
○○ Compatibility mode is  used – all scheduled jobs are stored in  one table.
○○ Compatibility mode is  not used – each scheduled job is  stored in  a sepa-
rate table.
„„ Contents of tables storing constants is  changed:
○○ Compatibility mode is used – one table is used to store constants.
The  same table is  used to register changes.
○○ Compatibility mode is  not used – each constant is  stored in  its own table.
Changes for each constant are also registered in  a separate table.
„„ Contents of tables storing accumulation register settings are changed:
○○ Compatibility mode is used – accumulation register settings are stored
in  one table.
○○ Compatibility mode is not used – the settings of each register are stored
in  a separate table.
„„ Contents of tables storing accounting register settings are changed:
○○ Compatibility mode is  used – accounting register settings are stored in  one
table.
○○ Compatibility mode is not used – the settings of each register are stored
in  a separate table.
„„ Help inclusion by a  subsystem in  help system contents was changed:
○○ Compatibility mode is  used – subsystem help was shown in  help contents,
if for any object included in  the subsystem, the Include in  Help Contents
property was set and it  was disabled for the subsystem.
○○ Compatibility mode is not used – inclusion of subsystem help in help
contents completely depends on the Include in  Help Contents subsystem
property status and does not depend on the properties of the objects included
in  the subsystem.
„„ A number of resources shown in  a diagram by the data composition system has
changed:
○○ Compatibility mode is used – only one resource (the first one) is shown
in  the diagram.
○○ Compatibility mode is not used – several resources are shown in the
diagram.
2-1218 1C:Enterprise 8.3. Developer Guide

„„ An ability to group by data composition system field resources has changed:

○○ Compatibility mode is  used – grouping by field resources is  not supported.
○○ Compatibility mode is  not used – grouping by field resources is  supported.
„„ Diagnostics of key values identifying a  string displayed for a  dynamic list with
a  set arbitrary query has changed:
○○ Compatibility mode is  used – errors occurring when receiving dynamic list
data are not shown.
○○ Compatibility mode is  not used – if duplicated key values are found in  the
selection, a  warning is  shown and data can't be displayed.
„„ Period parameter necessity of the Get() method for periodic information
register manager has changed:
○○ Compatibility mode is used – the option is not required and the method
result is  not defined.
○○ Compatibility mode is  not used – the option is  required.
„„ System behavior is changed for a scenario when the form element size
is  determined automatically if the font size specified in  the form element prop-
erties is  not the default font size.
○○ Compatibility mode is  used – the element font size is  not taken into account
when element size is  calculated.
○○ Compatibility mode is  not used – the element font size is  taken into account
when element size is  calculated. Changing font using a  form or dynamic
list conditional appearance does not affect form element size.
„„ DataVersion standard attribute text representation has changed:
○○ Compatibility mode is  used – representation is  an empty string.
○○ Compatibility mode is  not used – representation is  a string containing 12
white spaces.
„„ When a  value is  passed from an attribute to a  form element, text refreshing
in  a text box has changed:
○○ Compatibility mode is  used – refreshing always takes place, except in  the
case when the AutoComplete event handler sets the same type of value that
is  set in  value text box. The  RefreshingEditText property is  ignored.
○○ Compatibility mode is not used – refreshing can be managed with the
RefreshingEditText text box property and the RefreshEditText()
method of the text box form extension.
„„ When the SetValue() method and the UseFromDataSource() method of the
DataLockItem object are simultaneously used.
○○ Compatibility mode is  used – the value set by the UseFromDataSource()
method has the highest priority.
○○ Compatibility mode is  not used – an exception is  raised.
Appendix 6. System Behavior in Various Modes 2-1219

„„ Keys of objects designed to store desktop command interface settings have

changed:
○○ Compatibility mode is  used:
□□ The Subsystem.desktop/NavigationPanel/CommandInterfa-
ceSettings key is  used for navigation panel settings.
□□ The Subsystem.desktop/ActionPanel/CommandInterfa-
ceSettings key is  used for action panel settings.
○○ Compatibility mode is  not used:
□□ The Desktop/NavigationPanel/CommandInterfaceSettings key
is  used for navigation panel settings.
□□ The Desktop/ActionPanel/CommandInterfaceSettings key
is  used for action panel settings.
„„ The algorithm used to fill automatically the form attribute list that has to be
checked is  changed:
○○ If the compatibility mode is used and attributes disabled by functional
options are included in  the list of checked attributes.
○○ If the compatibility mode is  not used and attributes disabled by functional
options are not included in  the list of checked attributes.
„„ Reading data for managed form tables linked with dynamic lists when the form
is open:
○○ If the compatibility mode is used, reading is available for all the tables
linked with dynamic lists, including tables which are not visible to the user.
○○ If the compatibility mode is not used, reading is available only for the
tables displayed when the form is  open.
„„ Converting the Name in  data source property of the external data source table
field when placed to the SQL query:
○○ If the compatibility mode is  used, the property value is  always surrounded
by double quotes regardless of the characters in  the name.
○○ If the compatibility mode is  not used, the property value is  surrounded by
double quotes only when the field contains special characters and is not
surrounded by single quotes.
„„ Defining the calculated field column type when data composition results are
output to the collection of values:
○○ If the compatibility mode is  used, the column type is  defined automatically
on the basis of the calculated field expression.
○○ If the compatibility mode is  not used, the value type specified for the calcu-
lated field is  set as the column value type. If the value type is  not specified,
then it  is  defined based on the calculated field expression.
2-1220 1C:Enterprise 8.3. Developer Guide

„„ Outputting data composition results to the collection of values when one data
composition field is  included in  different groups:
○○ If the compatibility mode is  used, different group fields that reference to the
same data composition field were included in  different collection columns.
○○ If the compatibility mode is  not used, different group fields that reference
to the same data composition field were included in different collection
columns.
„„ Generating an custom data object presentation:
○○ If the compatibility mode is  used, generating custom presentations is  not
supported.
○○ If the compatibility mode is not used, generating custom presentations
is supported.
„„ To obtain a  value for the functional option, if this value is  set to be received
in  privileged mode:
„„ If compatibility mode using version 8.3.2 is used – an error is generated
in  safe mode if you do not have access rights to an object storing the functional
option value.
○○ If compatibility mode is  not used – rights are not verified.

6.3. SPECIFIC CHARACTERISTICS OF WEB CLIENT

„„ The following features are not supported in Google Chrome and Safari
browsers:
○○ Programmatical insertion from the clipboard, and starting with Google
Chrome 6 and Safari 5 – any operations of programmatical access to
the clipboard. Only keyboard clipboard commands (not context menu
commands) are available.
○○ Automatic operating system authentication.
○○ The ability to change headers and footers when printing.
„„ The cryptography tools extension is  not supported in  the Safari web browser.
„„ MacOS X only supports password input using Latin letters and digits. iOS (up
to version 5.x) only supports password input using the Latin alphabet and digits.
iOS 6 supports the use of national alphabet characters in passwords. If you
need to ensure compatibility between various OS versions or to use the applied
solution in  the Safari web browser, we recommend you enter passwords using
digits and the Latin alphabet only.
„„ Due to operational peculiarities of the Safari web browser for MacOS X,
a  slow connection may result in  server connection errors that are not generated
in  other browsers. These errors are caused by the lack of connection timeout
parameters in  this web browser.
Appendix 6. System Behavior in Various Modes 2-1221

„„ In a  cross-domain query, if an OpenID authentication is  performed in  Micro-

soft Internet Explorer 6.0 and 7, a  message window prompting you to confirm
the operation opens after the username and password are entered. If the user
confirms the operation, authentication proceeds. Otherwise, the system prompts
the user to enter his/her user name and password again.
„„ When a  page with Web application is  added to Bookmarks in  Mozilla Firefox
Web browser using the Bookmark This  Page command, the user has to adjust
the added link manually. To do this, open the properties editing window for the
added bookmark and remove text up to http:// in  the address box or drag and
drop the application icon (to the left of page address) in  the Bookmarks menu.
„„ User-initiated interruption of module operation is not supported. When the
module is running, calls of the UserInterruptProcessing() method are
ignored.
„„ The LockApplication() method is  not supported.
„„ The Eval() function does not diagnose the Procedure called as function error.
„„ If there is  a mistake in  the expression transferred to the Eval() function, the
error is  identified as a  method call error, and not as an error in  the transferred
expression.
„„ Google Chrome does not support script code debugging in the BeforeExit
and OnExit event handlers.
„„ Long-lasting operations do not affect cursor appearance in  any way.
„„ Horizontal scrolling is not supported in any of the form’s elements (with
a  mouse wheel when Shift is pressed).
„„ Microsoft Internet Explorer and Mozilla Firefox browsers do not process keys
pressed during a server call. In Google Chrome and Safari browsers these
keystrokes are processed when the server call is  finished.
„„ Hotkey definition with the & character in  the command text, menu items, etc.
is not supported. The & character specified in the text is ignored and not
shown in  the interface.
„„ In Safari, when a  server handles a  query for a  long time, an error can occur.
„„ It is not recommended to programmatically open and close one or more
forms in  one handler. These actions should be performed at a  different time.
It  is  recommended to close forms in  a standby handler.
„„ If a form opened in an auxiliary window is closed by clicking the system
close button ("cross" in  the top corner of the form) or pressing Alt  +  F4, the
BeforeClose handler is  not called for the closed form module.
„„ If a form opened in an auxiliary window is closed by clicking the system
Close button (the cross in  the top right form corner) before it  is  fully shown
on the screen, an error can occur in  a browser.
„„ A minimized window in  Google Chrome is  not activated if a  warning related
to the contents of this window is  displayed.
2-1222 1C:Enterprise 8.3. Developer Guide

„„ If a  user minimizes a  form of the modified object in  Google Chrome and then
closes the main application window, the system warns that some data has not
been saved, but the form with this data will not be activated.
„„ Sometimes in  Internet Explorer 6.0 and Google Chrome, an empty window can
be shown when receiving a  file from a  server.
„„ If you need to display form element text normally when specifying the font size,
you should specify both the font size and type of the TrueType font used.
„„ If button height is  more than 5 units (with the standard font size), the button
is  shown without gradients.
„„ If the Question() global context function button list does not contain a  button
with the DialogReturnCode.Cancel function, an attempt to close the dialog
using the system Close Window button (the cross in  the top right form corner)
will reopen the dialog.
„„ Status bar functionality is  limited. When a  module is  running, status updates
depend on the Web browser (for details see page 1-351).
„„ The indicator field display differs from a  thin client. In  particular, this concerns
the appearance of an indicator field for which the Representation property
is  set to Broken or BrokenTilt.
„„ Dendrogram object functionality is  limited.
„„ GraphicalSchema object functionality is  limited.
„„ GeographicalSchema object functionality is  limited.
„„ GanttChart object has limited interactive setup features.
„„ Retrieval of system information about client computer is  not supported.
„„ Work with TextReader, TextWriter, ZipFileReader, ZipFileWriter and
XBase objects is  not supported. It  is  recommended to work with these files on
the server side.
„„ Work with XML and XDTO is not supported. It is recommended to work
with these files on the server side.
„„ Internal clipboard is  implemented in  Google Chrome and Safari browsers:
○○ Data in  the internal clipboard are relevant during the session.
○○ All values in the operating system clipboard are also duplicated in the
internal clipboard.
○○ The M+ and M- commands change the value in the internal clipboard.
The  result is  written to the operating system clipboard.
○○ The internal clipboard is  shown in  the "1" cell in  the calculator, and the
MR, M+ and M- calculator commands work with internal clipboard values.
The  result is  written to the operating system clipboard.
„„ The calculator configuration dialog is  not supported.
„„ The functionality of the interactive spreadsheet change is  restricted.
Appendix 6. System Behavior in Various Modes 2-1223

„„ Interactive commands for setting up the spreadsheet view are limited.

„„ Background image for spreadsheet documents is  not supported.
„„ Patterns in  spreadsheet document cells are not supported.
„„ If text does not fit in  a table cell, no ellipsis is  added at the end.
„„ When changing table data source, the current table row is  changed and at the
same time the form element property value changes, which rebuilds the form,
the OnRowChange handler call and form reload procedures are not defined.
„„ Vertical stretching should be disabled in forms with a vertical scrollbar for
elements, such as a  table, a  spreadsheet document, a  diagram, etc.
„„ The GetHTML() method of the FormattedDocument object returns an empty
picture list.
„„ Opening a spreadsheet document with a report containing reference values
from a  file is  not supported.
„„ The spreadsheet document field and form table are not supported when you are
scrolling using the mouse wheel in  a spreadsheet document.
„„ If the Fit property for a  non-empty spreadsheet document cell is  set to Auto,
cells are merged horizontally up to the next filled cell or to the end of the
spreadsheet document.
„„ If a  picture is  located in  multiple spreadsheet document cells, all intersected
cells are merged and only the text in  the top left cell within the intersected cells
is displayed.
„„ A spreadsheet document will not support overlapping of a  text and a  picture
in  cells. First the picture is  displayed, then the text.
„„ In some cases, a  picture placed in  a spreadsheet document can be truncated by
edge row borders or column borders of the area where the picture is  located.
Changing the picture size or moving it to normalize the image is recom-
mended.
„„ In some cases, a  picture in  a spreadsheet document, for which the lower or the
right border is  located above the upper border or to the left of the left picture
border, can be located with a  shift. Changing the picture size or moving it  to
normalize the image is  recommended.
„„ If right alignment is  set for a  spreadsheet document cell and the text does not
fit in  the cell, the text part moved is  left-aligned.
„„ Microsoft Internet Explorer 6.0 and 7 Web browsers do not support display
of merged spreadsheet document cells that have a  left border and no bottom
border. It  is  recommended to set bottom borders for these cells.
„„ In Microsoft Internet Explorer 7 Web browser spreadsheet documents with
cells of varying widths in  a single column and text combined with picture in  a
single cell produce garbled printouts.
2-1224 1C:Enterprise 8.3. Developer Guide

„„ In Google Chrome and Safari, a  border can be shown incorrectly with a  certain
combination of cell groups and cell frames in  a spreadsheet document.
„„ For two adjacent (horizontally) spreadsheet document cells, the contiguous
border will be decorated with the same line that is  used for the right border of
the left cell if the document is  displayed in  Microsoft Internet Explorer 6.0.
„„ The following line types are only available for spreadsheet document cells:
Solid, Dotted and None. Other line types are replaced with the available types
as follows:
○○ Double line type is  replaced with Solid;
○○ ThinDashed, ThickDashed and LargeDashed line types are replaced with
Dotted.
„„ In Microsoft Internet Explorer and Google Chrome, the dotted frame of adjacent
cells can sometimes be displayed as a  solid frame.
„„ To ensure spreadsheet documents with dotted lines are correctly printed from
the Google Chrome web browser, we recommend you set the PrintAccuracy
property for these documents to Accurate. Similarly, this recommendation
applies if you use Google Chrome to print spreadsheet documents and want to
ensure that accurate dimensions are used for all printed items.
„„ File comparison mode is  not supported.
„„ Recently used file list is  not supported.
„„ Files cannot be dragged and dropped to web client forms.
„„ Web clients use a limited set of fonts available in OS in use. Other fonts
cannot be selected in  the font selection dialog box in  the web client; if used
they are replaced with supported fonts.
„„ The main menu can be accessed by pressing F10; access by pressing Alt once
is  not supported.
„„ Pressing Ctrl  +  W in  Google Chrome closes auxiliary windows and does not
select a  word.
„„ Pressing Ctrl + F4 in  Google Chrome closes the current tab. If the tab is  the last
tab, the next browser window is  closed.
„„ Pressing Ctrl + N in  Google Chrome creates a  new browser window and does
not open the New Document menu.
„„ Web browsers do not support scaling (other than 100%) or non-standard DPI
settings.
„„ Navigation between windows using the keyboard can have special characteris-
tics (depending on Web browser type):
○○ Microsoft Internet Explorer 6.0 – no special characteristics.
○○ Microsoft Internet Explorer 7, Microsoft Internet Explorer 8 – navigation
using Ctrl + Tab and Ctrl + Shift + Tab is  not supported if tabs are enabled
in  the Web browser. Navigation using F6 and Ctrl + F6 is  available with no
constraints.
Appendix 6. System Behavior in Various Modes 2-1225

○○ Mozilla Firefox – navigation between windows using the keyboard requires

additional setup in  the Main Menu – Tools – Web browser setup dialog box.
○○ Google Chrome:
□□ For any version – Ctrl + Tab, Ctrl + Shift + Tab combinations do not switch
tabs. F6, Ctrl + F6 work without restrictions.
□□ For version 7.0 and earlier versions, when you are using hotkeys (F6,
Ctrl  +  F6) to switch browser windows, an attempt to reopen an already
open form or using the Activate() method, Navigation to the window
completed. Click OK to proceed warning is shown after switching to
a  new window. You can click OK and continue working with the opened
window.
„„ A modal window in Microsoft Internet Explorer locks all parent windows,
in  Mozilla Firefox only the parent window is  locked, and in  Google Chrome
windows are not locked. All other application windows are shaded. You can
switch to them, but you can't perform any actions in  them.
„„ When a modal window is opened, the main window is not refreshed
in  Microsoft Internet Explorer.
„„ Web browser restrictions make it impossible to open a modeless form from
the modal one. Therefore all forms to be opened from modal ones are opened
in  the modal mode.
„„ The web client window can't have a  size smaller than the size set in  a browser.
„„ In multiple display mode, if displays have set a  different resolution, windows
not opened on the first display can have different coordinates when they are
reopened.
„„ Displaying the command bar with vertical buttons rendering is  not supported.
„„ Displaying a missing picture in the web client differs from displaying
a  missing picture in  the thin client.
„„ Microsoft Internet Explorer 8 incorrectly displays images with transparency
other than 0 and 100%.
„„ Displaying pages with a  web server host name in  the address matching web
client host name in  an HTML document field is  not supported. Storing pages
in  an infobase is  recommended.
„„ Processing events of an HTML document field for pages with a  web server host
name in  the address matching web client host name is  not supported. Pages
that require event handling should be stored in  an infobase.
„„ When the ChooseFromList() method is  used, the value list selection window
is  opened as a  separate browser window and not as a  list.
„„ When the ChooseFromMenu() method is  used, the value list selection menu
and data composition system details menu are opened as a separate browser
window and not as a  menu.
2-1226 1C:Enterprise 8.3. Developer Guide

„„ When the PutFile() method is called, there could be situations when put
file errors are determined incorrectly. In this case True is returned and the
Address parameter does not contain a  temporary storage address.
„„ Size modification mode (using the mouse) for a  calendar opened from a  text
box is  not disabled if the mouse button is  released outside the window where
the calendar is  opened. To disable size modification mode click the left mouse
button again and release it  inside the calendar window.
„„ In Safari, the calculator and calendar windows are always opened in  windows,
which size is  not less than the minimal window size for that browser.
„„ Scroll bar color for HTML document field matches OS color, except the cases
when Microsoft Internet Explorer is  used and HTML document field displays
HTML page set by a  text string.
„„ Calling the DocumentComplete and OnClick event handlers and Print and
Save commands of an HTML document field is  not supported if a  document
is  displayed in  the field for which the web server host name is  different from
the web client host name.
„„ Cancel and Undo commands behavior in  multiple line text boxes is  different
from other clients. In  the web client, the amount of canceled changes is  defined
by the browser.
„„ The result of left clicking a  word in  a text box (with pressed Ctrl) depends on
the browser and the clicked word is  not selected.
„„ Clicking left/right arrows in  a text document field in  the first/last string posi-
tion will move the pointer to the previous/next string.
„„ In a  multiple line text box and in  a text document field, entering text in  the
insert mode is  not supported.
„„ In a  multiple line text box and a  form table cell, text is  broken only per word.
Solid text at element border is  not wrapped.
„„ When Shift+Del is pressed in a multiple line text box, the whole string
is  deleted and automatic line break for text box borders is  not considered.
„„ If an invalid XML version 1.0 character (http://www.w3.org/TR/xml/) is  program-
matically moved to a text box, in Google Chrome and Safari this character
is  replaced with "?" and the text box becomes uneditable.
„„ If a  tip text contains line breaks, in  Mozilla Firefox white spaces are shown
instead.
„„ The web client language in  Safari matches the browser interface language, if
the interface language is  not explicitly set using the L command line option.
„„ When the web client is debugged and local variables or method options are
used in  the Expression window, a  table or breakpoint conditions, their names
should be specified exactly as they were set in  the definition (accounting case
characters).
Appendix 6. System Behavior in Various Modes 2-1227

„„ The following features are not supported in  the web client:
○○ General:
□□ Print using the current printer.
○○ Graphical schema field:
□□ Search and Replace.
○○ Spreadsheet Document:
□□ Go to Cell.
○○ Text Document:
□□ Go to Line.
□□ Using tabs.
□□ Text submenu of the main menu.
„„ The web client does not support the following hotkey commands:
○○ Picture box:
□□ Zoom in  (Num+).
□□ Zoom out (Num-).
□□ Picture scrolling using keyboard.
○○ Graphical schema field:
□□ Schema scrolling.
○○ Table linked to a  hierarchical list:
□□ Minimize node (Ctrl + Num-).
□□ Minimize all nodes (Ctrl + Shift + Num-).
□□ Maximize node (Ctrl + Num+).
□□ Maximize all nodes (Ctrl + Shift+ Num+).
○○ Spreadsheet Document:
□□ Minimize group (Ctrl + Num-);
□□ Minimize all groups (Ctrl + Shift + Num-).
□□ Maximize group (Ctrl + Num+).
□□ Maximize all groups (Ctrl + Shift + Num+).
□□ scroll page left (Alt + PgUp).
□□ scroll page right (Alt + PgDn).
□□ Select cells using keyboard.
○○ Text Document:
□□ delete current line (Ctrl +L  ): not supported in  Mozilla Firefox, Google
Chrome, Safari.
○○ In MacOS X, when a  non-English keyboard layout is  enabled, hotkeys are
not supported if the following keys are pressed:
□□ Google Chrome: Alt and Alt + Shift;
□□ Safari: Alt, Alt + Shift, Cmd and Cmd + Shift.
2-1228 1C:Enterprise 8.3. Developer Guide

6.4. WEB CLIENT SPECIFICS FOR IPAD

These specifics extend the list of web client behavior specifics described in  the
previous section.
For iPad:
„„ Instead of a  mouse double-click, a  quick double touch of the same screen posi-
tion is  used. Instead of a  mouse right click, a  long touch is  used (more than 1
sec.)
„„ Tabs are supported only.
„„ The on-screen keyboard cannot show automatically when you are editing
a  table cell or a  spreadsheet document cell (in the text box shown). To show
the keyboard, click the text box edited again.
„„ Switching to the main window using the All Windows dialog is  not supported.
If you try to switch to the dialog, the following warning is  displayed: Unable to
go to the main window.
„„ It is  recommended to use the close button in  the top right corner of the main
window to exit the web client.
„„ Drag-and-drop is  not implemented.
„„ Switching to the main window when auxiliary windows are open is not
supported.
„„ Printing is  not supported.
„„ A formatted document field allows only viewing of the document (without
editing).
„„ The status bar is  shown in  the same window as user notifications.
„„ The PutFile() method is  not available.
„„ The file system extension, cryptography tools, and add-ins are not available.
The following object and global context methods cannot be used in an applied
solution on iPad:
„„ Global context:
○○ Question()
○○ OpenValue()
○○ OpenFormModal()
○○ Warning()
○○ InputData()
○○ InputValue()
○○ InputString()
○○ InputNumber()
„„ FontChooseDialog object:
○○ Select()
Appendix 6. System Behavior in Various Modes 2-1229

„„ ColorChooseDialog object:
○○ Select()
„„ StandardPeriodEditDialog object:
○○ Edit()
„„ FormatStringWizard object:
○○ OpenModal()
„„ DataCompositionDetailsProcess object:
○○ ChooseAction()
„„ ScheduledJobScheduleDialog object:
○○ OpenModal()
„„ ValueList object:
○○ CheckItems()
○○ ChooseItem()
„„ ManagedForm object:
○○ ChooseFromMenu()
○○ ChooseFromList()
○○ OpenModal()

6.5. SPECIFICS OF SYSTEM OBJECT BEHAVIOR WITH ENABLED

DATA SEPARATION MODE
This section describes specifics of different 1C:Enterprise objects and mechanisms
behavior, if the application uses data separation mode.

6.5.1. Changing Separator Values

In the session separator usage and separator, values can be changed by directly
changing the session options. Session option values to which a  common attribute
is  referencing (see page 2-898) can be changed anytime according to rights restric-
tions of the user on behalf of which the attempt to change the session options
is made.
Replacing the current separator values, for example, allows you to perform neces-
sary administrative actions when the separated mode is  required.
However, we should note that if an infobase is accessed via a web server,
changing object values programmatically can be locked with the default.vrd file (for
more details see page 2-913).
1C:Enterprise does not guarantee the logical integrity of application data (not
infobase data) after session options change, similar to changing session options
affecting access restrictions (see page 1-188).
2-1230 1C:Enterprise 8.3. Developer Guide

Changing a  session option value referenced by at least one separator in  the Inde-
pendent mode in  1C:Enterprise script leads to the following:
„„ Object cache is  cleared.
„„ Reused values are deleted (see page 1-178).
When separator usage and separator values are changed in  the session, it  is  recom-
mended to call the RefreshInterface() method.

6.5.2. Object Numeration

The numerating mechanism works within every unique combination of separator
values. Automatic object numeration works for this combination and uniqueness
control is  implemented.
When a  number is  determined, the separator values set in  the session are used.
In  this case, if a  separator is  not used in  the session, the value set for the infobase
object is  used for the separator.

6.5.3. Real-Time Timestamp

Real-time timestamp is  separated within every unique combination of independent
separators only if there are no documents for which real-time posting is  enabled
and which are not included in  these separators.
For example, there are two independent separators in  an application: Subscriber
and Organization, and three documents (with enabled real-time posting):
ReceiptOfGoods, Invoice and Move. The  Organization separator includes the
ReceiptOfGoods and Move documents, and the Subscriber separator includes
all documents. The real-time timestamp is separated only for the Subscriber
separator, since documents exist for the Organization separator that are not sepa-
rated (the Invoice document).
Subscriber Organization
ReceiptOfGoods Included Included
Invoice Included Not included
Move Included Included
Real-time timestamp separation Separated Not separated

6.5.4. Predefined Data

You can use predefined data for objects included in  any splitters.
When you first access an object table, predefined data is  only created if the session
uses all the splitters (including splitters in  the Independent and Shared mode) that
contain an object with predefined data.
You can create predefined data in  a new data area using the InitializePrede-
finedData() method. The  session must use all the splitters that contain objects
with predefined data.
Appendix 6. System Behavior in Various Modes 2-1231

Unique identifiers of data items associated with predefined data do not match for
data from different areas. In  other words, if the Goods catalog has a  predefined
item named P1 and two areas with codes 165 and 567, the unique identifier of
a  data item associated with P1 in  area 165 is  not the same as the unique identifier
of a  data item associated with P1 in  area 567.

6.5.5. Access Rights

Administrative actions that are generally performed with an infobase and a  specific
data area are regulated with different rules.
„„ Administration – this right regulates administrative actions with the whole
infobase and regulates user list editing.
„„ Data administration – this right regulates administrative actions with data. These
actions include:
○○ Viewing event log records and getting filter values without restrictions.
○○ Setting the infobase (data area) time zone (calling the SetInfoBa-
seTimeZone() method).
○○ Creating an initial image for the distributed infobase subordinate node
(calling the CreateInitialImage method).
○○ Refreshing object numbering (calling the RefreshObjectsNumbering()
method).
○○ Executing the StandardSettingsStorageManager object method, if
settings of a  non-current user are processed.
NOTE
The Administration right requires the Data administration right. When an infobase
user list is  checked with the Administration right, it  considers only users without
any separators.
For common attributes with enabled data separation, default rights are not set, even
if the Set rights for attributes and tabular sections by default checkbox is  checked
for the form.

6.5.6. Users
When an infobase user is created (the InfoBaseUser object), you can specify
separator values for the user.
The DataSeparation property of the InfoBaseUser object is used for this
purpose. This  property stores a  structure with the following specifics:
„„ The structure element key contains the name of the separator (as it  is  set in  the
Designer).
„„ The structure element value contains a string representation of the separator
value. For details about generating a  string representation of a  separator value,
see page 2-911.
2-1232 1C:Enterprise 8.3. Developer Guide

If a  structure includes a  record with a  separator name, this separator value is  set
for the user.
The DataSeparation property value determines:
„„ Username uniqueness space, if the separator separates authentication (see page
2-900).
„„ User list separation, if the separator separates users (see page 2-899).
„„ Initial separator values setting of a  user session for any separator defined in  the
configuration (see page 2-910).

6.5.7. Exchange Plans

From an exchange plan point of view, any separator that includes an exchange plan
is  considered as being in  the Independent and Shared mode. This  ensures unique-
ness of exchange plan element references, including those elements that describe
predefined nodes in  every data area (the ThisNode() method of the exchange plan
manager).
When changes are registered, system behavior depends on the following factors:
„„ Is the exchange plan separated or not?
„„ Is the registered object separated by all exchange plan separators or not?
„„ Is at least one separator that includes the exchange plan used in the current
session?
The table below describes automatic change registration depending on the factors
stated above:
Metadata object is  separated by At least one exchange Automatic
Exchange Plan
all exchange plan separators plan separator is  used registration
Not separated All nodes
Separated No No All nodes
Separated No Yes 1.
Separated Yes No 2.
Separated Yes Yes 2.

In this table:
1. An exception is  raised when the receiver node list is  automatically populated.
If an exchange plan includes at least one separator that does not include a  meta-
data object with autoregistration enabled for this exchange plan, when the
database configuration is  updated a  warning is  shown saying that the configu-
ration object is  not included in  the exchange plan separator.
2. When the receiver node list is  automatically populated, a  data area is  used
which is  defined by a  set of separators, each of which separates both the
exchange plan and the metadata object. If not every separator that includes both
the exchange plan and the object for which changes are registered is  used, these
Appendix 6. System Behavior in Various Modes 2-1233

object separator values are used for missing separators. If in  the process of
change registration it  is  found that separator values are changed:
○○ For data area exchange plan nodes defined by the "old" combination of
separator values, data object deletion is  registered.
○○ For data area exchange plan nodes defined by the "new" combination of
separator values, data object modification is  registered.
Configuration modification is registered for all nodes and all exchange plans
regardless of their separation by any separator (only for exchange plans with
a checked Distributed infobase checkbox).

6.5.8. Functional Options

If a configuration object used to store the functional option value is included
in  separators, the functional option value is  received as follows:
„„ If at least one independent separator that separates the configuration object used
to store a  functional option value is  not set, the value of the functional option
stored in  a Boolean-type attribute will be set to True, and for other types of
attributes an exception is  raised.
„„ If all the independent separators are used and at least one separator with the
Independent and Shared mode enabled is  not used, the value of the functional
option stored in  a Boolean-type attribute will be determined by OR-ing all the
values with unspecified separator values; for other types of attributes an excep-
tion is  raised.
„„ Only those separators are analyzed that include a  configuration object storing
a  functional option value.

6.5.9. Scheduled Jobs

A scheduled job can be included in  a separator.
A scheduled job is  started with separator values set for this job using the Data-
Separation property of the ScheduledJob object. This property can also be
used to get a  set of separators corresponding to the session where the scheduled
job is  started (only values of separators with the Independent and Shared mode
enabled are available, see page 2-897).
For the ScheduledJob object you can change the DataSeparation property by
general rules, except predefined scheduled jobs for which the DataSeparation
property can't be changed. You can change a  scheduled job from a  session that
uses only separators that separate that scheduled job.
2-1234 1C:Enterprise 8.3. Developer Guide

When scheduled jobs are received (by a  unique ID or a  scheduled job list), the filter
is  implicitly set by separators according to the separator values set in  the current
session. Based on a  separator value, different scheduled job sets are available:
„„ The  Independent mode separator.
○○ The separator is  used – only those scheduled jobs are available for which
separator values match current session separator values.
○○ The separator is  not used – there are no available scheduled jobs.
„„ The Independent and Shared mode separator:
○○ If the separator is used – only scheduled jobs with separator values
matching separator values in  the current session are available.
○○ If the separator is  not used – scheduled jobs with random separator values
and jobs with no separator are available.
If a  scheduled job is  marked in  the Designer, when 1C:Enterprise is  first enabled
with a  new combination of separators, a  list of scheduled jobs is  created with the
current combination of separator values and separator usage. If a  separator is  not
used in  this session and a  scheduled job is  included in  this separator, the corre-
sponding scheduled job property will be set to the default value for the separator
type and separator usage will be enabled.
TIP
Creating separated scheduled jobs that are frequently executed with a large
number of data areas is not recommended. Rather, creating a non-separated
scheduled job that will process different separator values on its own is  advised.

6.5.10. Background Jobs

A background job is started with separator values corresponding to the session
from which the background job is  started. When a  background job is  running (or
after it is completed) you can get separator values using the DataSeparation
object of the BackgroundObject (only the values of separators with the Inde-
pendent and Shared mode enabled are available, see page 2-897).
When background jobs are received (by a  unique ID or a  background job list), the
filter is  implicitly set by separators according to separator values set in  the current
session. Based on a  separator value, different background job sets are available:
„„ The Independent mode separator: only those background jobs are available that
were started from sessions with the same separator usage and separator values
as the current session's.
„„ The Independent and Shared mode separator: only those background jobs are
available that were started from sessions with the same separator values as are
used in  the current session. Unused separators are not considered.
Appendix 6. System Behavior in Various Modes 2-1235

NOTE
In a  file mode infobase a  background job is  running not with a  set of separators
set in  the session where the background job was started, but rather with a  set
of separators of the session where the ProcessJobs() global context method
is  executed (see page 2-831).

6.5.11. Web Services

When a  web service is  called, separator values can be specified similar to the web
client (see page 2-912).

6.5.12. Constants
If all separators that include constants are used in  a session, you can use constants
in  the query language using the Constants table (similar to 1C:Enterprise 8.2.13
and earlier versions).
The ConstantValueManager object and the Constant table have fields corre-
sponding to splitters in  the Independent and Shared mode.

6.5.13. Registers
An Independent and Shared mode separator acts in  a register as a  dimension that
logically precedes dimensions set by the application developer.
One recordset can only contain records with the same separator values set.

6.5.13.1. Information Registers

Separators are not included in  the main information register filter.
Filter items corresponding to separators that include an information register can be
added to the Filter property of the information register recordset.
Record uniqueness is checked within the data area corresponding to the current
unique combination of separation values.
When you call the Read() method for a  set of records, remember the following:
„„ You do not need to set separator values in a record set filter if the current
session uses all separators that contain a  register;
„„ If the separator values in  the record set filter are set to values that do not match
the current session values, the method execution returns an empty set of records;
„„ If the values for separators that are not used in  the current session are not set
in  the record set filter, the method execution returns a  set of records with no
filtering according to the values of these separators.
When you call the Read() method for the record manager, remember the following:
„„ You do not need to set separator values in  the record manager if the current
session uses all separators that contain a  register;
2-1236 1C:Enterprise 8.3. Developer Guide

„„ If the separator values in  the record manager are set to values that do not match
current session values, the method execution returns an empty record;
„„ If the values for separators that are not used in  the current session are not set
in  the record manager, the method execution returns an empty record.
When the Select(), Get(), GetFirst(), GetLast(), SlcieFirst() and
SliceLast() methods of the register manager are called, you should note the
following:
„„ If the Filter property of these methods has a  separator value passed as the
parameter for the separator used in  the session, and this value should match the
separator value; otherwise an exception is  raised.
„„ When the Get() method is called, the Filter parameter should specify the
values of all the separators not used in  the current session.

6.5.13.2. Accumulation and Accounting Registers

Register parameters (totals separation flag, totals usage flag, etc.) are separated and
stored for each data area. Totals settings can be received only for a  session that
uses all the values of separators that include the register.
When separators are deleted or their types are modified, the records are merged
in  the register parameter tables by new combinations of defined separators during
the database configuration update.
Recalculate totals operation (the RecalcTotals() and RecalcTotalsForPeriod()
methods) and recalculate present totals (the RecalcPresentTotals() method)
can be executed with any usage state of separators that include the corresponding
register. Totals are recalculated within a  data area defined by the current values of
used separators.
Accounting Register
When accounting registers and charts of accounts are edited, you should note the
following:
„„ Contents of independent separators that include charts of accounts and the
related accounting register should be identical.
„„ The accounting register should be included in all Independent and Shared-
mode separators that include a  chart of accounts related to this register.
When a chart of accounts element is written, if the accounting settings that
affect accounting registers movement are changed, the system checks whether the
accounting register separators that are not included in  the chart of accounts in  the
session are used in  the Independent and Shared mode.
When the accounting register recordset is written, the system checks that all
accounts used in  the recordset have separator values identical to recordset sepa-
rator values.
Appendix 6. System Behavior in Various Modes 2-1237

Accumulation Register Aggregates

Aggregate setting is  separable and stored for every data area.
You should note the following when working with aggregates:
„„ The following methods can be called only in  a session where all separators that
include the register are used.
○○ GetAggregatesMode(),
○○ GetAggregatesUsing(),
○○ GetAggregates(),
○○ SetAggregatesMode(),
○○ SetAggregatesUsing().
„„ The following methods can be called in  any case:
○○ DetermineOptimalAggregates(). Executed for the data area defined by
used separator values.
○○ RebuildAggregatesUsing(). If all the separators that include the register
are used in the session, the method is executed only for a specific data
area. Otherwise, similar settings (contents and periodicity) of aggregates
usage for separators used and all value combinations of unused separators
are set.
○○ UpdateAggregates(), ClearAggregates(), AggregatesIsFilled().
If all separators that include the register are used in  the session, methods
are executed only for a  specific area; otherwise, they are executed for every
data area within separator values used.
If a separator is in the Independent and Shared mode and it  is  not used in  the
session, you can use aggregates, except for the following scenarios:
„„ If the totals mode is  enabled for some separator values.
„„ If aggregates usage is  disabled for some separator values.
„„ If different minimal periodicity of used aggregates is  set for different separator
values. If the RebuildAggregatesUsing() method is called in the non-
separated mode, minimal periodicity of used aggregates is  the same.
„„ If for different separator values used aggregate sets are not overlapping. If the
RebuildAggregatesUsing() method is  called when separators are not used,
the sets of the used aggregates are the same.
„„ For queries in  a transaction – if for some separator values the aggregates update
process is  not completed and it  is  in  the stage of data migration from a  buffer
to an aggregate.
2-1238 1C:Enterprise 8.3. Developer Guide

6.5.13.3. Calculation Registers

When the schedule data virtual table is  received, the calculation register records
and information register job schedule records are mapped not only by calculation
register attributes with the filled Link to schedule property, but also by Independent
and Shared-mode separators that are common separators for the information
register and the calculation register.
When a  basic data virtual table is  received, calculation register records are mapped
not only by fields passed as virtual table parameters, but also by Independent and
Shared-mode separators that are common separators for the information register
and the calculation register.
When an actual validity period is  calculated, the validity period between displacing
calculation types is  separated using separator value matches (in the Independent
and Shared mode).
Also note the following:
„„ When a  calculation register recordset is  written, separator value matching (the
Independent and Shared mode) is  not controlled in  calculation register records
and this record calculation type.
„„ When a  calculation type is  written, separator value matching (the Independent
and Shared mode) is  not controlled in  the calculation type and all calculation
register records with this type of calculation.
„„ Separator value matching (the Independent and Shared mode) is  not controlled
in the calculation type and those calculation types that are included in the
tabular section of displacing, base and leading calculation types.

Recalculations
Recalculations are automatically included in the same set of separators as the
corresponding calculation registers. When recalculations are written, values of
separators set for the corresponding calculation register records are used.

6.5.14. Document Sequence

In the Independent and Shared mode, the separator acts as a  tool of calculation for
a sequence.
A document sequence is  separated only in  the following scenarios:
„„ All documents and registers included in  the sequence are separated.
„„ Documents and registers included in  the sequence are separated with the same
set of separators.
The Filter parameter of the SetBound() and Validate() methods is not
required.
Appendix 6. System Behavior in Various Modes 2-1239

If the Sequence Filling property of a  document included in  the sequence is  set to
Fill automatically, sequence record common attribute values will be set to values
corresponding to the document generating this record.

6.5.15. Infobase Options

The infobase time zone is  separated by independent separators. If not all separa-
tors are used, an attempt to set or get the infobase time zone raises an exception.
Otherwise, the timezone value in  the separator values slice is  used.
Other sessions are notified of any time zone change within 20 seconds after the
change. The  exclusive infobase access mode is  not required if the time zone is  set
in  the session that uses at least one separator.
The SetInfoBaseTimeZone() method requires an exclusive area lock to be set if
the current session does not use a  separator.

6.5.16. Session List

The session list will include the session where separator values match the values of
the current session (from which the list is  received using the GetInfoBaseSes-
sions() method). In  this session, the list user names (and computer names) are
not available if the user does not belong to the data area available for the current
session. For example, the Subscriber separator exists in  an infobase (the Number
type). For Johnson, the separator value is  set to 5. If the application changes the
Subscriber separator value for any other value, user names are not available in  the
session list.

6.5.17. Connection List

Only if no separators are used in the current session will a connection list
(received using the GetInfoBaseConnections() method) not be empty.

6.5.18. The Event Log

6.5.18.1. Visual Representation
If the event log is opened in a session with at least one unused separator, the
Session data split field will be added to the following forms:
„„ Event log list form
„„ Event log list filter setting form
„„ Event log record form
Separator name representation is  defined as follows:
„„ For an existing separator – its representation.
„„ For a renamed separator, i.e., a separator whose name was changed after
related records were added to the log – current separator representation.
2-1240 1C:Enterprise 8.3. Developer Guide

„„ For a  deleted separator – the last name of the deleted separator appended with
white spaces before upper case letters (but not before the first upper case letter).
In  this case upper case letters are converted to lower case letters (except for the
first letter in  the separator name).

6.5.18.2. Filter
When the event log is  generated (to view the log or export it  using the Unload-
EventLog() method), filtering is  always implemented for separators that are used
in  the current session. This  filter (forced filter) can't be disabled or changed. If
the event log is  generated within the session where the separator is  conditionally
disabled, the filter by this separator is  also disabled.
For separators that are not used in  the current session, filter values can be set by
the user. In  this case the forced filter and user filter by separator values are added
with the AND operation.
When filter values for the User and Computer fields are received (using the
GetEventLogFilterValues() method), the result is  generated as follows:
„„ The separator is  used – field values are returned from log records that were
registered for the current separation value.
„„ The separator is not used – all field values registered by the event log are
returned.
When event log records are received programmatically (using the GetEvent-
LogFilterValues() method), a  filter is  generated by adding the
DataSessionSeparation element of the Structure-type to the filter struc-
ture. Every structure element contains a  separator name as the key, and a  set of
separator values that are used to filter event log records as the value. If the Data-
SessionSeparation structure contains multiple elements, a  record will match the
filter, if it  matches all values set in  the structure (the AND filter).
This set can be specified using a  structure (in this case the records are filtered by
one value) or using a  structure array (in this case the filter is  specified with a  set
of values).
A structure used for a  filter contains the following elements:
„„ Using (Boolean type). Default value – True. Sets using a  common attribute
separating data. If the value is  set to False, the Value element is  ignored and
can be omitted. Thus you can filter log records for which this common attribute
is  not set.
„„ Value (arbitrary type). Common attribute value, default value – Undefined.
If a structure array is specified in the SessionDataSeparation structure
element, an event log record will match this condition, if it  matches at least one
value (the OR filter).
Consider the following example.
Appendix 6. System Behavior in Various Modes 2-1241

Two separators are set in  an application:

„„ Subscriber, Number type.
„„ Branch, Number type.

Example 1:
„„ Type: Structure.
○○ Key: Subscriber, value: Structure.
□□ Item 1: key: Using, value: True.
□□ Item 2: key: Value, value: 1.
○○ Key: Branch, value: Structure:
□□ Item 1: key: Using, value: False.
In this case the event log records that simultaneously fulfill the following condi-
tions are filtered:
„„ The Subscriber separator is  used and set to 1.
„„ The Branch separator is  not used.

Example 2:
„„ Type: Structure.
○○ Key: Subscriber, value: Array.
□□ Item 1: Structure.
 Item 1: key: Using, value: True.
 Item 2: key: Value, value: 1.
□□ Item 2: Structure.
 Item 1: key: Using, value: True.
 Item 2: key: Value, value: 5.
○○ Key: Branch, value: Structure:
□□ Item 1: key: Using, value: True.
□□ Item 2: key: Value, value: 8215.
In this case event log records that simultaneously fulfill the following conditions
are filtered:
„„ The Subscriber separator is  used and can accept values from 1 to 5.
„„ The Branch separator is  used and can accept 8215 value.

6.5.18.3. Getting Event Log Records

When the event log is unloaded (to a value table or an XML document) the
following columns are added to the corresponding data structure:
„„ SessionDataSeparation, Structure type, where the structure key is the
separator name and the structure value is  the separator value.
2-1242 1C:Enterprise 8.3. Developer Guide

„„ SessionDataSeparationRepresentation, Array type, containing the

<Separator Representation>: <Separator Value Representation> strings.
These columns are added only if the current session has at least one separator
that is not used in this session. Data in the SessionDataSeparation and
SessionDataSeparationRepresentation columns contain information only
for separators not used.
For example, two separators exist in  an application:
„„ Subscriber,
„„ Branch.
If both separators are used in the session, unloaded data will not have the
SessionDataSeparation and SessionDataSeparationRepresenta-
tion columns. If only the Subscriber separator is  not used in  the session, the
SessionDataSeparation and SessionDataSeparationRepresentation
columns data will contain only information for the Subscriber separator, and for
the Branch separator there will be no information.
Separator name representation is  defined as follows:
„„ For an existing separator – its representation.
„„ For a renamed separator, i.e., a separator whose name was changed after
related records were added to the log – current separator representation.
„„ For a  deleted separator – the last name of the deleted separator appended with
white spaces before upper case letters (but not before the first upper case letter).
In  this case upper case letters are converted to lower case letter (except for the
first letter in  the separator name).
The GetEventLogFilterValues() method is used to get a set of acceptable
values for common attributes separating data.
You need to specify the SessionDataSeparation string as the first method
parameter to get a  set of common attributes separating data.
In a  structure returned by the method, a  set of common attributes is  written to an
item with the SessionDataSeparation key. Item value is  a match, where:
„„ Key is  the common attribute name,
„„ Value is  the common attribute representation.
To get a  set of separator values you need to specify the
SessionDataSeparation.<Common attribute name> string in the first
method parameter, where <Common attribute name> is the name of the
common attribute (see above).
In a  structure returned by the method, a  set of acceptable values of the common
attributes is  written to an item with the SessionDataSeparation key. Item value
is  a match, where:
„„ Key – common attribute name,
Appendix 6. System Behavior in Various Modes 2-1243

„„ Value – Match-type value, where:

○○ Key is  the common attribute value,
○○ Value is  the common attribute value representation.

6.5.18.4. Other
If the user is not available in the current session (belongs to another data area,
is  deleted, etc.), when you view the log, unload it  and use the filter setting dialog
this user is  shown as User name <not found>.

6.5.19. Settings and Favorites

Settings are stored in  a slice of a  unique combination of separator values and user
names. Different users with the same name are accepted as identical. A disabled
separator represents a  single value, for which settings are also stored.
When separator values are changed in  the process of system operation, new sepa-
rator content settings are not automatically read. For this purpose you need to close
and reopen the form whose settings need to be read.
When an infobase is restructured (after the separator contents change) the
following actions are performed:
„„ When a separator is added, it is considered that all settings previously set
in  a database were written in  a situation when a  new separator is  used and its
value is  the default value of the added common attribute type.
„„ If when a separator is added, several settings are found that were saved for
identical configuration objects and different separator values, only those settings
will be saved that were saved for a  minimal value of the deleted separator. A
warning is  shown when this situation occurs in  restructuring.
Work with user favorites follows the rules stated above.

6.5.20. History
User actions history is stored in a slice of a unique combination of separator
values and user names. Different users with the same name are not distinctive. A
disabled separator represents a  single value, for which history is  also stored.
When an infobase is restructured (after the separator contents change) the
following actions are performed:
„„ When a  separator is  added, it  is  considered that all action history previously
set in  a database was written in  a situation when a  new separator is  used and
its value is  the default value of the added common attribute type.
„„ History is  cleared when a  separator is  deleted, so every unique value combina-
tion of the remaining separators never contains more than 200 history records.
2-1244 1C:Enterprise 8.3. Developer Guide

6.5.21. Queries
If an object is  included in  a separator and a  data query uses the connection with
its object table, you can't use the object tabular section in  the connection condition
(the UNTIL section).
Please note that performance of queries that are processed slowly (due to the large
number of connections) in  a system without separators will be even lower if the
system contains over two separators or a  separator of the String type. Therefore,
try to avoid using multiple connections in  such systems.

6.5.22. Managed Transaction Locks

When the 1C:Enterprise script locks something without specifying any fields, the
whole space of any separators used is  locked.
Lock can be set in  1C:Enterprise script with an explicitly specified separator only
for the Independent and Shared-mode separators, and only for register dimension
spaces (not recordsets).
If an object is  written with separator values equal to the default values of the corre-
sponding types and these separators are used in  the current session, lock is  set by
the separator values set in  the session.
If a  lock is  set by a  reference value, the lock space is  defined by these values and
the values of the independent separators used. Thus, simultaneous lock by a  refer-
ence value from the session where an Independent and Shared-mode separator
is  used and from the other session, in  which the same separator is  used, is  not
available.
If a  session imposes exclusive access to certain areas, any attempt to set managed
locks for the same areas (in the same session) are ignored.

6.5.23. Exclusive mode

The SetExclusiveMode() method works with an area described by the separator
used in  this session. So, a  single infobase can simultaneously have multiple areas
with the exclusive mode set (with regard to the restrictions described below). If
a session uses no separators, the exclusive mode is set for the entire database
rather than just for an area of it.
Exclusive mode for an area means that no other session can lock the same area
or any of its nested areas, and no other session can set an exclusive mode for any
enveloping area. Area A1 is  a nested area of area A2 if there is  a separator that
is used in area A2 and is  not used in  area A1, while separators used in  both area
A1 and area A2 have the same values. An enveloping area is  defined similarly.
When you move from one area to another, the list of areas with exclusive access set
by the current session does not change.
Appendix 6. System Behavior in Various Modes 2-1245

Exclusive mode set for a  data area prevents you from doing the following:
„„ Creating new sessions for an area and its nested areas
„„ Modifying area data from enveloping areas
„„ Setting exclusive mode in  enveloping areas
Please note that the restrictions described above mean that the entire infobase may
be seen as an enveloping area for any data area.

6.5.24. Deleting Marked Objects

The FindMarkedForDeletion() method finds all objects marked for deletion
available in  the current session.
When you try to delete objects (the DeleteObjects() method) with reference
integrity control, this control is  implemented among the objects that are available
in the current session according to set separators. Situations are possible when
there are references to deleted objects not available within the current session (for
example, from another data area). In  this case the application developer and user
deleting the objects is  responsible for deleting these objects.
TIP
It is  recommended to restrict object deletion in  applications (for example, delet-
ing non-separated objects in  separated sessions) using configuration tools (access
rights, etc.)

6.5.25. Full-text search

In applications using separators, the full-text search index (as a  set of service files)
is  common for all infobase separator values. The  index is  updated for all separator
values and it  can be updated only in  a session where separators are not used. Full-
text search index update is  not supported if the session uses at least one separator.
All non-separated objects and separated objects for which the following conditions
are met will be used for search:
„„ Separator in  the Independent mode:
○○ If the separator is  used – the search returns objects if their separator value
matches the value set for the session.
○○ If the separator is not used – separated objects are not returned by the
search.
„„ Separator in  the Independent and Shared mode:
○○ If the separator is  used – the search returns objects if their separator value
matches the value set for the session.
○○ If the separator is  not used – all separated objects are returned by the search.
If all application separators are used in  the session, the information search time
is  equal to the search time in  an infobase without separators similar to data area
characteristics. If not all application separators are used in  the session, the search
2-1246 1C:Enterprise 8.3. Developer Guide

can take longer than in  an infobase without data separation similar to the data area
in  set separators.
TIP
Scheduled jobs used to update and merge the full-text search index should be
made non-separated.
Since the full-text search index is  the same for the whole infobase (and not for
every separator combination), the IndexTrue method can return True, even if
there were no changes in the current session that can be included in the index.
Such changes can be applied in  a session with other separator values.
The UpdateIndex(), ClearIndex(), SetFullTextMode() methods can be
used only when the session does not use any separator. Otherwise, an exception
is raised.

6.6. RUNNING THE CLIENT APPLICATION IN  LINUX

The client application run under Linux OS has some specific features and restric-
tions:
„„ The system does not support COM-based technology nor any of the capabilities
associated with it, including:
○○ working with the COMObject object;
○○ running the 1C:Enterprise client in  the Automation server mode;
○○ external components created through the COM-based technology.
„„ The administration console for the 1C:Enterprise server cluster is not
supported. Administration can be performed via the administration server (ras)
and the administration utility (rac).
„„ User authentication through the operating system tools is  not supported;
„„ The Mail object is not supported. Instead, you can run the default mailing
application using the RunApp() function and passing a URL based on the
mailto: scheme (RFC 2368, http://www.ietf.org/rfc/rfc2368) as the function
parameter.
„„ The installation of multiple application versions on one computer is not
supported and automatic "selection" of the system version to work with the
infobase is  not possible.
„„ The use of Windows metafiles (WMF, EMF) is  not supported.
„„ When developing application solutions, remember that the HTMLDocu-
mentField control (in ordinary mode) and the form field of the HTML docu-
ment field type (in managed mode) are created on the basis of the WebKit library
instead of the Internet Explorer library. You should therefore note that the
appearance and the object model of the HTML document (DOM model) that
can be accessed via the HTMLDocumentField.Document property may differ
from those in  the client application under Windows.
Appendix 6. System Behavior in Various Modes 2-1247

6.7. SPECIFICS OF MOBILE APPLICATION OPERATIONS

When you develop a  mobile application, the following configuration objects and
system mechanisms are supported:
„„ Constants
„„ Catalogs
„„ Documents
„„ Document journals
„„ Accumulation registers (except totals split and aggregate mode)
„„ Information registers
„„ Data processors
„„ Enumerations
„„ Session parameters
„„ Exchange plans (except exchange plans with the Distributed infobase attribute
set)
„„ Event subscriptions
„„ Dynamic list (with limitations)
„„ Web service use (with Web service creation unavailable in  a mobile applied
solution)
„„ Common pictures
„„ Common commands and command groups
„„ Common templates
„„ Common modules
„„ Common forms
„„ Data composition system setting objects (without user interface)
„„ Conditional appearance
„„ XDTO
„„ Languages
The following mechanisms and configuration objects are not supported:
„„ Taxi interface
„„ Accounting mechanisms
„„ Periodic calculation mechanisms
„„ Mechanisms of business processes and tasks
„„ Data composition system
„„ Mechanisms of applied solution debugging
„„ Functional options
„„ Common attribute mechanism
2-1248 1C:Enterprise 8.3. Developer Guide

„„ Access rights, roles, data access restrictions

„„ Managed locks
„„ Use of external data sources
„„ Automated testing mechanism
„„ Dragging mechanism
„„ Subsystems
„„ Infobase users
„„ Full-text search
„„ Standard functions
„„ Ordinary interface
„„ Some managed form items
„„ Extended editing in  form items
„„ Custom form settings
„„ Saving and restoring form data in  settings
„„ Information panel, user work history and notifications (ShowUserNotifica-
tion() method)
„„ The display of the long-term process state (State() method)
„„ Printing of spreadsheet document
„„ Help system
„„ Features and modifications implemented in  version 8.2.16 and earlier are not
supported in  the mobile platform
Some configuration objects and mechanisms have certain operation peculiarities:
„„ iOS does not support the Execute() operator and the Eval() function.
„„ The start page can only display a  single form. If the start page settings specify
multiple forms, the platform uses the first form in the left-hand (or only)
column of the start page work area. If desktop visibility is disabled for the
form, no form is  displayed by the system.
If the start page work area on a mobile device has no form (for whatever
reason), the main application menu opens immediately upon application launch.
„„ iOS (up to version 5.x) only supports password input using the Latin alphabet
and digits. iOS 6 supports the use of national alphabet characters in  passwords.
If you need to ensure compatibility between various OS versions, we recom-
mend you enter user passwords using digits and the Latin alphabet only.
You should also remember that supported objects do not have the same capabilities
as they do in  applied solutions for desktop computers. To define the accessibility
of a  method or property in  the mobile platform, use the Availability section of the
Syntax Assistant.
Appendix  7

OPERATION
OF VARIOUS DBMS

7.1. GENERAL FEATURES

„„ Index can contain a  maximum of 16 database fields, except file mode version
where this value can be up to 256 fields.
„„ Strings comparison operations in the query language ignore ending spaces,
unlike string comparison in  1C:Enterprise script where ending spaces are used
in comparison operations. For example, comparing "bb" and "bb " strings
in  1C:Enterprise script returns False (strings are not equal), and returns True
in  the query language (strings are equal).

7.2. FILE DATABASE

„„ Database file (.1CD) is  a set of the so-called internal files. Each database table
can be mapped to up to 4 internal files:
○○ Table description file. It  stores a  table description.
○○ Data records file. It  contains data of all table records with the exception of
data from open-ended fields.
○○ Index file. It  stores all indices defined for a  table. If no index is  defined,
this file does not exist.
○○ Open-ended values file. It  stores open-ended values from table fields.
„„ Each of the files listed above can have a  maximum size of 4 GB.
„„ Key length cannot exceed 1920 bytes.
2-1250 1C:Enterprise 8.3. Developer Guide

7.3. IBM DB2 SERVER

„„ Untyped NULL. Type of column resulting from SELECT NULL query is the
most common composite type; it  is  not the simple type compatible with any
other type. Therefore, this column cannot be used in  operations which cannot
use composite type fields. For example, SELECT ISNULL(f1 + 1, 1) FROM
(SELECT NULL f1) t1 during work with DB2 results in  an error because
operation <+> operand cannot be a  composite type field.
„„ Maximum length of numeric data is  31 characters (not 38).
„„ Maximum length of accumulation and accounting registers resources is 25
characters (not 32).
„„ Maximum size of open-end data is  1 GB.
„„ Maximum number of columns in the operator selection list cannot exceed
1012. When defining number of columns please note that 1C:Enterprise creates
several columns in  DBMS table for composite type fields.
„„ Some rules that define result precision for arithmetic operations differ from
rules in  other DBMS.
„„ Only literal (parameter) or expression on literals can be a  right operand of LIKE
comparison operation. Only "_" (any character) and "%" ( sequence of any char-
acters) can be template characters.
„„ Use of subquery written in the query language in the BY section can slow
down query execution. If multiple subqueries are used in  the BY section (e.g.,
multiple tables are joined on conditions that contain subqueries), the query
could fail.
„„ If a query contains a concatenation operation for 10 and more string values
that include fields and literals and concatenation result is  used for comparison,
the following error could occur: DBMS error: SQL0401N. Operands specified
for '...' operation have incompatible data types.
„„ Joining is  not available in  a query if two tables are connected with a  condition
including tabular section fields comparison.
„„ Case sensitivity for string comparison. Implicit string comparison performed by
query language DISTINCT, GROUP BY and UNION statements is  case-sensitive.
Therefore, execution of queries is  characterized by the following features:
○○ When DISTINCT and UNION statements are used (without ALL), query result
field values of the String type are treated as different if they have differing
casing (in other DBMS they are treated as identical).
○○ When ORDER BY statement is  used, values of the String type that have
different.
○○ Query contains UNION, UNION ALL or DISTINCT statements.
○○ Query selection list contains CASE statement with nested queries.
Appendix 7. Operation of Various DBMS 2-1251

○○ Current user has restricted access to data and query contains no ALLOWED
keyword.
○○ In other cases comparison of string data is not case-sensitive (String
values with different casing are treated as identical):
□□ when String type fields are compare explicitly.
□□ when GROUP BY statement is  used.
□□ in ORDER BY statement with the exception of the above listed cases.
○○ The features listed above are relevant in  the following cases:
□□ IBM DB2 9.1 is  used.
□□ The compatibility mode for version 8.1 is enabled (the Compatibility
mode configuration property is  set to Version 8.1);
□□ The database has been generated with 1C:Enterprise version 8.1.12 or
with later versions.
„„ The background database configuration update is not supported when IBM
DB2 9.1 is  used.
„„ If you encounter one of the following situations:
○○ Long query execution time;
○○ A large number of drive operations during query execution;
○○ Presence of the HASH JOIN syntactic construction in  the query plan;
○○ Significant speed improvement after current query optimization from 5 to 0,
○○ You are recommended to execute the following command: db2set DB2_
OVERRIDE_BPF=5000, and restart IBM DB2 DBMS. This  recommendation
does not apply to DBMS version IBM DB2 9.7 FixPack 5 and later.

7.4. MICROSOFT SQL SERVER

„„ Up to 256 tables can be used in  a query (for Microsoft SQL Server 2000 and
Microsoft SQL Server 2005).
„„ The database management system error may occur when Microsoft SQL Server
2000 is used, grouping by the expression (instead of the field) is executed,
or the aggregate function in  the HAVING section not included in  the SELECT
section is  used. It  is  recommended that you add expressions from the HAVING
section to the SELECT section when developing solutions for Microsoft SQL
Server 2000. This  problem does not occur in  Microsoft SQL Server 2005 and
later versions of the database management system.
„„ If the application solution is  designed for Microsoft SQL Server 2000, using
functions intended to work with dates in  the GROUP BY query section is  not
recommended, as this can lead to false results. Rather than expressions with
functions, you can use grouping by all table fields which influenced the expres-
sion.
2-1252 1C:Enterprise 8.3. Developer Guide

7.5. ORACLE DATABASE SERVER

„„ In the automatic mode Oracle Database uses tabular locks. It means that
the transaction that captured one record in the table locks the whole table,
which could prevent competitive transactions to work with this table data.
It  is  recommended to develop applications in  the managed lock mode to get
the most of your DBMS. Application automatic mode is  used for compatibility
with previous application versions and it  is  not recommended for production
operation.
„„ Nested query with TOP modifier and ORDER BY section cannot be used in  the
IN operator if the nested query contains calls to external query fields.
„„ When sorting in  ascending order, NULL fields are the last in  the selection.
„„ Use of subquery written in  the query language in  the BY section can slow down
query execution. If multiple subqueries are used in  the BY section (e.g., multiple
tables are joined on conditions that contain subqueries), the query could fail.
„„ The first ValueStorage attribute (by order in the table) is optimized; if no
attribute of this type exists, the first Open End String attribute (by order
in  the table) is  optimized.
„„ Please note that in Oracle Database performance is affected by whether
statistical data are current. It is recommended to update DBMS statistics
regularly (DBMS does it by default, but the user can gather statistics using
the dbms_stats.gather_schema_stats procedure). It  also makes sense to
collect statistical data after infobase has been restored from infobase dump file
(*.dt). After database server is  restarted collection of statistics can also affect
performance.
„„ If registers have more than three string type dimensions, when database
configuration is  updated and when an infobase is  loaded tabular space can be
required for indexes with a  large key. 1C:Enterprise does not create this tabular
space, but it  can use a  space called V81C_INDEX_BIG.
Tabular space should be created by a  database administrator using the CREATE
TABLESPACE command by specifying block length in  the BLOCKSIZE param-
eter. To create a  tabular space with a  block length exceeding the database block
length an additional configuration of the database instance can be required. For
example, you can create a  tabular space with 16384 byte block length by speci-
fying the DB_16K_CACHE_SIZE parameter using the ALTER SYSTEM command.
„„ In queries with the LIKE comparison operation, square brackets are considered
to be special characters only when they are used in the text literal, but not
in  the expression.
In the example below the square brackets have a  special meaning – they repre-
sent a  set of characters:
SELECT * Catalog.Products WHERE Article LIKE "123[AB]%"
Appendix 7. Operation of Various DBMS 2-1253

In the following example the square brackets, which can be in  the Template
variable, have no special meaning.
SELECT * Catalog.Products WHERE Article LIKE Template+"%"

7.6. POSTGRESQL SERVER

„„ In the automatic mode PostgreSQL uses tabular locks. It  means that the trans-
action that captured one record in  the table locks the whole table, which could
prevent competitive transactions to work with this table data. It is recom-
mended to develop applications in the managed lock mode to get the most
of your DBMS. Application automatic mode is used for compatibility with
previous application versions and it  is  not recommended for production opera-
tion.
„„ When sorting in  ascending order, the NULL fields are the last in  the selection;
when sorting in  descending order, they come first.
„„ PostgreSQL uses table locks in the automatic lock control mode. It means
that a  transaction reading data from a  table prevents another transaction from
writing data to the same table. File mode version uses the same lock granularity
(table being one granule).
„„ Operations that remove/add a  lot of records from/to database tables (e.g., when
documents are re-posted) can also affect performance adversely. To restore
initial performance it  is  recommended to run REINDEX (or VACUUM) operation
regularly for database tables with high volumes of modification. Frequency of
these operations depends on how intensively the tables are used.
„„ PostgreSQL performance is greatly affected by the disk system performance
since fsync parameter is  enabled by default. It  means that when the COMMIT
operation runs data are immediately written from OS cache to disk, thus
ensuring consistency in  case of hardware failure. The  downside is  that write
operations in  a disk drive slow down as delayed write of OS data is  not used.
„„ To boost performance use multi-disk RAID arrays based on caching RAID
controllers with non-volatile cache memory or uninterruptible power supply
(UPS). In  case of hardware error data consistency is  ensured by the abovemen-
tioned devices; therefore, fsync parameter can be disabled and performance of
write operations in  a disk drive can be increased. Please note that increasing
the number of disks in  the RAID array and cache size of the RAID controller
is  enough to compensate for slow performance caused by the enabled fsync
parameter.
„„ There are certain differences in how date/time functions operate. Thus,
in  Microsoft SQL select datediff(hour, datetime(2006, 10, 29, 0,
0, 0), datetime(2006, 10, 30, 0, 0, 0)) returns 24, while in  Post-
greSQL it  returns 25 because transition to standard time has occurred between
2-1254 1C:Enterprise 8.3. Developer Guide

these two dates. The same applies to the DATEADD function regarding the
daylight savings time.
„„ It is  not recommended to use FULL OUTER JOIN in  queries since this construct
does not function efficiently enough in  DBMS. In  most cases source query can
be re-written without using this statement.
„„ You can't simultaneously use FULL OUTER JOIN and access tabular sections
in  the selection field list.
„„ In queries with the LIKE comparison operation, square brackets are considered
to be special characters only when they are used in the text literal, but not
in  the expression.
In the example below the square brackets have a  special meaning – they repre-
sent a  set of characters:
SELECT * Catalog.Products WHERE Article LIKE "123[AB]%"

In the following example the square brackets, which can be in  the Template
variable, have no special meaning.
SELECT * Catalog.Products WHERE Article LIKE Template+"%"
Appendix  8

WORK IN  XBASE

This section explains the terms used to describe XBase object – 1C:Enterprise
script tool that helps operate databases.

8.1. FIELDS AND RECORDS

A telephone directory for a  company is  a good example of a  database. It  contains
last names, telephone numbers and room numbers for all the employees of the
company. Each line of the telephone book is  a record and each column is  a field.
Each field has a name and attributes of information that is stored in it: type,
length and precision. Field contents for a  specific record is  called field value. For
example, a  telephone book can be organized as a  table with columns (fields) Full
name, Room number and Phone. Each row (record) contains information about one
employee.

8.2. SPREADSHEET, SPREADSHEET STRUCTURE

AND DATABASE FILE
In the database context, the entire telephone book is  called a  spreadsheet. Spread-
sheet fields determine spreadsheet structure and spreadsheet records determine
spreadsheet contents. Each record in  the table contains the same set of fields as the
entire spreadsheet. Therefore this set is  sometimes referred to as record structure.
Record structure is  basically the same as spreadsheet structure, although the former
term is  more accurate since a  spreadsheet always has a  structure even if it  does
not contain any records.
Implementation of databases in the DBF format implies that each spreadsheet
is stored in a separate file. Therefore, hereinafter we shall refer to a database
spreadsheet file as a  database file or DB file.
2-1256 1C:Enterprise 8.3. Developer Guide

8.3. INDICES, INDEX AND FILTER EXPRESSIONS AND INDEX

FILE
An index system is  used to organize database file contents and to search for values
of one or more fields. It  has the same principle as sorting a  card register based on
a  certain attribute (a set of attributes). However, unlike a  card register, a  DB file
can contain several indices and its contents can be sorted by several attributes. Each
index has a  name, unique attribute, expression and filter. The  index name is  used
for identification purposes. The  index expression and filter are expressions written
in  a special language. When values of these expressions are calculated for each
record, the results are used to determine its location and the necessity for placing
it  into an ordered list (an index can contain information not about all spreadsheet
records, but only about those that meet the requirements of the filter expression).
A unique index (that has the unique attribute on) can contain only references to
records with different index expression values.
Indices are stored in  an index file. The  index file can contain information about
more than one index.

8.4. WRITING CHANGES TO DATABASE

Each object is  a data structure located in  the computer memory. When you change
object properties, database files are not immediately modified. When the auto-save
mode is  on, object changes are written to the database only when you change the
position (move to the next record, perform a  key search, etc). When the auto-save
mode is  off, changes are written only when you run the appropriate object method.

8.5. WORK WITH INDEX FILES

Please keep in  mind that XBase can be linked only to one index file at once. All
database changes made during a  session with one index file do not influence other
index files. Therefore, it  is  not recommended to use more than one index file for
a  database. Otherwise index file contents have to be updated every time a  database
with a  new index is  opened.

8.6. RECORD DELETION

Deleting database record does not physically erase it  on disk. If you delete records,
a  special deletion mark is  put into a  hidden system field that cannot be accessed
in  the usual way. You cannot switch to records that are marked as deleted unless
you are running a  special mode of viewing deleted records. There is  a property
that manages this special mode and there are several methods that are used to deter-
mine whether the current record is  deleted and to restore the deleted records.
Appendix 8. Work in XBase 2-1257

The database compression method physically erases the database records that
are marked as deleted. The  database clear method physically erases all database
records. After any of these methods has been used, deleted records cannot be
restored in  future.

8.7. CREATION OF DATABASE, INDEX AND INDEX FILE

In addition to methods for working with existing databases, XBase objects have
methods for creating new databases of an arbitrary structure, new indices and new
index files. Please note that although you can use methods that change the database
structure only for objects that are not linked to the existing database (i.e. for new
databases), you can create new indices and index files both for new and existing
databases.

8.8. LIMITATIONS
The main purpose of XBase objects is organizing information export/import to/
from external files in  DBF format.
XBase objects do not support memo-type fields. XBase objects support only exclu-
sive access to files. XBase objects support index files in  CDX format. However,
it  is  not recommended to use index files created with XBase in  external programs
(e.g., FoxBase) and it  is  not recommended to use index files created with external
programs in  XBase objects due to possible incompatibility of versions.
2-1258 1C:Enterprise 8.3. Developer Guide
Appendix  9

SPECIFICS OF USING
SEPARATE MECHANISMS

Working with HTML Documents

„„ The <TABLE> element can't be added as a  child element in  the <P> element.
Thus, <P><TABLE></TABLE></P> construction after processing by
1C:Enterpise will become <P></P><TABLE></TABLE>. <P> element processing
rules are defined in  the HTML standard (http://www.w3.org/TR/html401/struct/text.
html), in  section 9.3.1 Paragraphs: the P element.

Form
„„ When program code in a waiting handler is executed, Ctrl  +  Break is not
processed and the screen is  not refreshed. You also should not add program
code that will worsen user experience in  a waiting handler.
„„ The server is notified about form closing (and unlocking an object if
it  is  locked) in  the following situations:
○○ The form is  closed, if an object was locked in  the form (for editing).
○○ Getting a  form from a  server using the OpenForm(), GetForm() methods.
○○ Calling server (context and out-of-context) form methods.
○○ Closing 20 forms.
○○ The system is  in  the waiting state for more than 20 seconds.
○○ When the following dynamic list commands are executed:
□□ deleting an item;
□□ marking an item for deletion;
2-1260 1C:Enterprise 8.3. Developer Guide

□□ posting a  document or canceling a  posting;

□□ moving a  catalog item to another group.
„„ If the applied solution runs on thick client running in  managed mode and you
use the OpenValue() method or the Open button (magnifying glass) for a  text
box, it  opens a  list form if all of the following conditions are met:
„„ The In  list editing mode is  selected for the configuration object (for catalogs,
exchange plans, charts of characteristic types, charts of accounts, charts of
calculation types, independent information registers, business processes and
tasks).
„„ The applied solution has an ordinary list form selected as the main or auxiliary
form.
„„ Ordinary forms are allowed to be used in  a managed application in  the applied
solution.
○○ No managed list or object form is  selected as the main or auxiliary form.
Working with files
„„ When you work with files in  Windows local file system note that full filepath
length can't exceed 260 characters.
Saving a  Spreadsheet Document
„„ If a  spreadsheet document contains multiple line text that is  centrally aligned
horizontally and exceeds cell borders, when this document is exported to
Microsoft Excel format this text will be cut by the left cell border and the right
cell border. To avoid this you should either create a  merged cell to fit the whole
text or you should place every line of multiple line text in  a separate spread-
sheet document row. It  is  not recommended to make a  separate row format for
a  row with multiple line text.
Appendix  10

AUTOMATIC FORM ELEMENT

NAME GENERATION RULES

When managed form elements, the context menu and the automatic command
bar are accessed as named Elements property elements, you can use standard
CommandBar, ContextMenu and Form prefixes in  both 1C:Enterprise script vari-
ants regardless of which variant was selected when the form was created.
TIP
If you need to manually generate form element names (e.g., when a  form is  cre-
ated programmatically), it is recommended to do this according to the same
rules used when the system does it  automatically. But it  is  not recommended to
change form element names generated by the system when the form is  designed
(e.g., when you are creating a  form element by dragging an attribute).
When an element name is  generated based on the path to linked data, the name
is  generated as follows: the name is  generated as the path to linked data with "."
characters excluded.
1. Elements linked with data (fields and tables) including elements linked to the
main form attribute. A name is  generated based on the full path to the data.
If the linked data belong to the main attribute, the main attribute name is  deleted
from the name.
Example:
The Products tabular section of the main attribute. Table name: Products.
Another object located in the AddObjectProducts attribute is edited
in  the form. The  table showing the Products tabular section of this object:
AddObjectProducts.
2-1262 1C:Enterprise 8.3. Developer Guide

2. Elements linked with data located in  a table (columns) or linked to the current
table data. Except for the tables linked to the main attribute. The name
is  generated according to the following rule: <TableElementName><PathToTa
bleAttributeData – PathToTableData>.

Example:
The Count attribute of the Products tabular section of the main form attribute:
ProductsCount.
The Count attribute of the Products tabular section of the attribute (not the
main attribute) AddObject: AddObjectProductsCount.
3. Elements linked with data located in  a table (columns) or linked to the current
table data. For the tables linked to the main attribute. If a  table directly shows
the main attribute, names are generated similar to how they are in  point 1. If the
table is  linked to an attribute of the main form attribute, names are generated
similar to how they are in  point 2.
Example:
The List table linked to a  dynamic list that is  the main form attribute contains
a  column showing the Date dynamic list attribute. Column name: ListDate.
A form contains a  table linked to the object tabular section shown by a  dynamic
list. The  tabular section is  named Products, and the tabular section attribute
is named Count. The  table form element name: Products, and the name of
this form element: ProductsCount.
4. Predefined elements (context menus and automatic
command bars): <ParentElementName>ContextMenu and
<ParentElementName>CommandBar.

Example:
The form command bar: FormCommandBar.
The context menu of the Count column linked to the Products tabular section
of the main form attribute: ProductsCountContextMenu.
5. The name of the group linked to the element that is a command source:
<SourceElementName>Actions.
6. The name of a  button located in  the form (not in  command bars or context
menus): <CommandName>. A prefix in the form of the element name is not
added for commands generated by an element.
Example:
The Write form command: Write.
The Change command of the Products tabular section: Change.
7. Name of a  button located in  the automatic command bar with the Autofill prop-
erty enabled: <CommandBarOwnerElementName><CommandName>.
Appendix 10. Automatic Form Element Name Generation Rules 2-1263

Example:
The Write form command: FormWrite.
8. The name of a  button located in  the automatic command bar with the Autofill
property enabled: <ContextMenuOwnerElementName>ContextMenu<Com-
mandName>. A prefix in the form of the element name is not added for
commands generated by an element.
Example:
The Pick context menu command of the Date field: DateContextMenuPick.
9. The name of a  group located in  the command bar or the context menu without
its own command source: <ParentElementCommandSourceName><Group
Name>. Group names do not affect child element names.
10. Name of the group located in a table linked to the main form attribute:
<FormTableName><GroupName>. Group names do not affect child element
names.
Example:
PriceAndCount in  the Table table: ProductsPriceAndCount.
11. Names of buttons and groups located in  non-automatic command bars with
a  source: similar to point 7. Names of buttons and groups located in  non-auto-
matic command bars without a  source: names are not modified.
12. The name of a button group located in command bars or context menus
with a  command source: <CommandBarParentElementName><Group
Name>. Every name is  generated according to the rules stated above. Having
a  command source does not affect name generation. For child elements they
become parent groups based on the rules stated above. The CommandBar prefix
is  not added.
Example:
A button group with the Form data source is  added in  the ServicesCount column
context menu. The standard group name is  ServicesCountContextMenuFor-
mActions.