string(3) "394"
Document Generator for Self-Hosted Bitrix24
06.28.2017 22:05:00
Articles
394
The Document Generator for Self-Hosted Bitrix24 generates files with a .docx extension based on the user-created template, substituting text, tabular data and images into the fields.

Quick solution of the template question.

row1.png

Many Bitrix clients use the Business Process Designer in their daily work. Template business processes have made work much easier, but the formation of the same files manually after working out the business process still delayed the execution of the task. For example, such standard documents as a commercial offer or contract had to be filled manually with duplicate data — company names, employee names, requisites, etc. Filling such documents is not the most time consuming task, but inserting tables with multiple fields and columns is a more complicated task.

Target

row2.png

It was necessary to develop a solution that allows to automate the formation of template files by substituting data from business processes. When creating a document, which contains, for example, company data, you have to fill in a lot of fields — name, details, etc. Doing this manually each time is long, and there is a high probability of making an error when copying data. Therefore, we needed a solution that allows you to transfer data directly from the CRM to the final file.

It was also necessary to insert tabular data — for example, a list of goods in a commercial offer, which implied not only a tabular view of the output of data, but also multiple binding to other fields and pictures.

Difficulties in the course of implementation

row3.png

First, we tried to use the class to work with the template "substrate" with a variable, but it was not enough, because the variable may contain only text data without tabulation and formatting. That means, that the table could be created, only initially denoting the number of rows and columns. And it was required to create a universal tool that would independently create the necessary number of rows and columns, depending on the amount of output data of the business process. Then we have finalized this class the way, that there was an opportunity of insertion of tabular data with formatting and pictures.

The special value of the solution is that you get an unique ability to generate a file from any business process data, including table data, with multiple bindings to other fields with pictures.

The result

row4.png

As result, we have developed a new action for the Business Process Designer — "Document Generator", which generates a file with the extension .docx based on the template, created by the user, and sample data like details, names, amounts or tables with pictures are automatically inserted into the template fields after launch of business process.

Installation

1. Download the solution on the Marketplace.

2. Specify the installation path, click Install.

3. In the administrative part of Bitrix, click Download Updates, and then click Install.

4. After the installation is completed, a new action will appear in the Business Process Designer — Document Generator (in the system it may have a name — “word document from a template [mcart]”).

en1.jpg


Principle of operation (example)

First, you have to create a document with the extension .docx, which will be a template for generating files. In this file, you have to specify the field names for the substitution.

Field names are specified in curly brackets in Latin letters, for example: {COMP_NAME}. Place the fields with the names of the variables in the right places of the template file, save.

en2.jpg

Attention! If you work with MacOS, it is desirable to use MS Word for Windows to create templates.

Upload the completed template into the system. You can do this two ways — upload to Drive in the portal or in a folder in the administrative part. The first way, of course, is easier and more convenient. Let's consider both ways of loading:

1. Go to the Drive menu, select the folder for the template, and load your template file there.

en3-1.jpg

en3-2.jpg

2. In the administrative part of Bitrix, go to the Content Files and Folders section — for example, we take the “generator” folder. Click Download File — specify the path to your template.

en3.jpg

At any point of the business process chain, add the "Document Generator" activity (in the system it may have a name — “word document from a template [mcart]”):

en4.jpg

Open the activity settings. In the settings of the Generator, fields are prescribed, which data will be taken for substitution into the variables of the template fields.

en5-1.jpg

If you specify not the path to the template file, but its ID, the settings will look like this:

en5.jpg

You can see the ID of the template file here:

id_of_template.jpg

Let's take a closer look at the Generator settings fields:

  • Title — the name of this activity. This is especially relevant if there are several of Generators in the chain of the business process. In this case, the created files with the result will have different names that you set in the settings of each activity;

  • tick "Process Merge Field" should NOT be marked;

  • The path to the document template — the path to the downloaded template file. For example: /generator/template.docx or 523, where 523 – ID of file on the disk. If the letters are written in the field — the module recognizes the path, if the digits — finds a file with such ID;

  • The path to save files, and name — the path and name for the saved file with output data and extension .docx. You may write here the full path to the file and the format of its name, or you may specify only the name, specifying the path to the file in the fields below. Example of filling: /generator/kp_{=System:Date}.docx (in this case, the file name will contain the letters “kp”, an underscore, and the current date. If you specify only the format of the output file name, for example: kp_{=System:Date}.docx, then fill in the following fields:

  • ID drive — the ID of the disk on which you want to save the result file. How to find the ID of the disk is shown below.

  • ID folder on the disk — the ID of the folder to which you want to place the result file. How to view the folder ID is shown below.

  • Next, you have to add rules to replace the variables in the template file with the data. To substitute the template file for the variables in the settings of the activity, you have to write rules with the name of the variable and the name of the field from which the data will be taken. The name of the variable in the template is written on the left side, and the name of the field from where you want to retrieve the data is written on the right side. The data field can be selected from the list by clicking on the ellipsis button next to the field.

After filling all the fields of the Generator, click the Save button. Then, save the changes made to the business process (button below).

How to find the ID of the disk

You can find the ID of the disk this way: in the administrative part of Bitrix go to Settings Tables — select the table b_disk_storage from the list, find the disk you need by its name and look in its corresponding column ID:

en6.jpg

How to find the folder ID

en7.jpg

Go to the Drive menu, select the folder you need. Next to the name you will see the field with its ID. If there is no such field, go to the settings and add the display of this field:

en8.jpg

How to generate in the output file a table of arbitrary size

1. Create a layout of the future table in the template file. In this example, ITEMS is the field that you will have to specify in the Generator settings to access string data of the array, after the point the name of the column is indicated. So, in the Items.num field, the data from the Items [num] array will be placed line by line. In this example, this is the order number of the item in the table.

table_for_array.jpg

2. Form the array. It should have the following form:

[id] => Array

Then all the fields of the array are listed line by line in the format:

[name] => Array

[price] => Array

The number of values in the columns should be the same, otherwise the table will be formed incorrectly.

3. Serialize the array:

Serialize(your_array);

Suppose, an array was serialized to the variable table_items. In this case, setting the Generator parameters will look like this:

variable_for_array.jpg

Save the Generator settings.

How to display a set of images in a result file (for emample, pictures of products)

1. In the template, you have to create a variable in Latin letters, in curly brackets.

en9.jpg

2. The variable stringArrNewImage writes a serialized array of this type:

en10.jpg

3. In the settings, this variable will look like this:

en11.jpg

Starting a business process

After you have determined all the settings for the Generator, you have to start the business process, with which the file generation will be linked. In our example, the business process is performed on company data, so we select any company from the list and launch our business process for it:

en12.jpg

After starting the business process, the resulting file can be easily downloaded and printed or sent by e-mail.

en13.jpg

The resulting file completely saves the formatting you specified:

en14.jpg

Attention! Now it is possible to enter data into variables that are in the header/footer of the template document.


Conclusion

row5.png

Significantly reduced the time of drawing up documents! Also, the human factor is excluded, since it is easy to make a mistake when filling out a multitude of similar documents. And when data is taken automatically from the system, it is excluded. M. C. Art knows how to make your work more effective!


comments powered by Disqus