Сервис формирует отчет в формате OOXML (документы *.docx и *.xlsx) из документа-шаблона по HTTP-запросу в формате XML или JSON. Опционально возможна конвертация отчета в PDF.
Алгоритм работы: теги документа-шаблона заменяются конкретными данными, указанными в запросе.
Далее используются термины Word/Excel. Термин Word относится к текстовым документам, независимо от используемого текстового процессора, по имени программы Microsoft Word. Под Excel имеются в виду документы-электронные таблицы.
Формат возвращаемого ответа, схематично:
{
error: {
code
message
}
result: закодированный в base64 файл документа отчета, в формате docx/xlsx/pdf.
}
Формат ответа (JSON или XML) может быть задан двумя способами:
application/json
и application/xml
.response-format
. Поддерживаемые значения: json
и xml
.Приоритет имеет формат, указанный в теле запроса.
http://localhost:8085/word_report_xml
http://localhost:8085/word_report_json
http://localhost:8085/word_multi_report_1_N_xml
http://localhost:8085/word_multi_report_1_N_json
http://localhost:8085/excel_report_xml
http://localhost:8085/excel_report_json
<?xml version="1.0" encoding="UTF-8"?>
<request>
<template uri="…" id="…"/>
<input-data>
<tags>…</tags>
<tables>…</tables>
<lists>…</lists>
<images>…</images>
<blocks>…</blocks>
</input-data>
<options>…</options>
<response-format value="…"/>
</request>
Элемент template
имеет атрибуты (поля):
uri
- строка. Задает расположение файла документа-шаблона в зависимости от того, как трактуется параметр id
. Поддерживаемое значение: local
.id
- строка. Идентификатор шаблона. Путь к файлу документа-шаблона относительно директории сервиса templates
. Также используется для записи файла отчета в отладочном режиме и для идентификации запроса в логе.Элемент (объект) input-data
содержит сущности (в зависимости от формата запроса, XML или JSON):
На примере XML-запроса:
tags
содержит список дочерних элементов tag
с атрибутом name
(совпадает с некоторым тегом в шаблоне) и нужным конкретным значением, на который тег в шаблоне будет заменен при генерации отчета.tables
содержит список дочерних элементов table
с атрибутом name
(совпадает с некоторым тегом в шаблоне). Тег в шаблоне будет заменен на таблицу, созданную согласно описанию таблицы в запросе.lists
содержит список дочерних элементов list
с атрибутом name
(совпадает с некоторым тегом в шаблоне). Тег в шаблоне будет заменен параграфом, отформатированным как список с данными элементов из описателя списка в запросе.images
содержит список дочерних элементов image
с атрибутом name
(совпадает с некоторым тегом в шаблоне). Изображения в шаблоне будут заменены на данные изображений из запроса.blocks
содержит список дочерних элементов block
с атрибутом block-template
(совпадает с именем шаблона блока в документе-шаблоне). Блок имеет те же элементы, что и input-data
, кроме элементов изображений и блоков. Шаблоны блоков в документе-шаблоне будут использованы для вставки в документ произвольного количества экземпляров блоков с разными наборами данных. Места вставки определяются тегами экземпляра шаблона в документе-шаблоне. Детали в секции Word→Блоки.Для запросов в формате JSON отличие лишь в том, что вместо XML-элементов данные представлены как объекты и списки объектов. Имена тегов задаются именами полей объектов. Списки, таблицы, изображения - дочерние по отношению к объекту input-data
.
Элемент (объект) options
содержит элементы (поля):
enable-debug-report-save
- логическое значение. Указывает создавать ли копию отчета документа (имя файла - идентификатор шаблона) в локальной директории reports_debug
сервиса. Значение по умолчанию - false
.formatting
- объект опций форматирования. Поддерживается только для запросов word. Поля объекта: tables
- объект опций форматирования таблиц. Поля объекта: enable-cells-auto-merge
- логическое значение. Указывает, объединять ли подряд идущие ячейки с одинаковым значением в одном столбце по вертикали. Значение по умолчанию - true
.report-format
- строка. Указывает формат файла отчета, если он отличен от формата, упомянутого в url запроса. Единственное непустое поддерживаемое значение: “pdf
”. Значение по умолчанию: пустая строка. См. пункт “Конвертация отчета в PDF” ниже.<?xml version="1.0" encoding="UTF-8"?>
<request>
<template uri="local" id="Информационное письмо"/>
<input-data>
<tags>
<tag name="ORGANIZATION">АО «название организации»</tag>
</tags>
<tables>
<table name="TABLE">
<rows>
<row>
<cell tag="номер_пп">1</cell>
</row>
</rows>
</table>
</tables>
</input-data>
<response-format value="xml"/>
</request>
См. также “Запросы для формирования отчетов в формате .docx через Сервис отчетов” в примерах запросов.
Разница относительно Word - в формате определения таблиц. Формат Word избыточен, т.к. каждая ячейка содержит тег столбца. Для Excel теги задаются в элементе cell-tags
один раз для всей таблицы. Тег ячейки отображает тег столбца на индекс ячейки в массиве, задающем строку таблицы.
<?xml version="1.0" encoding="UTF-8"?>
<request>
<response-format value="xml"/>
<template uri="local" id="Информационное письмо"/>
<input-data>
<tags>
<tag name="ORGANIZATION">АО «название организации»</tag>
</tags>
<tables>
<table name="TABLE">
<cell-tags>
<cell-tag name="номер_пп" index="0"/>
</cell-tags>
<rows>
<row>
<cell>1</cell>
</row>
</rows>
</table>
</tables>
</input-data>
</request>
См. также “Запросы для формирования отчетов в формате .xlsx через Сервис отчетов” в примерах запросов.
В опциях запроса указать формат отчета "pdf". Пример:
<options>
<report-format>pdf</report-format>
</options>
Необходим установленный пакет Libre Office. Программа soffice
должна быть доступна для вызова. Возможно задать путь к ней в параметрах командной строки сервера отчетов.
Сервер отчетов сохраняет отчет в файл и вызывает утилиту soffice
со следующими параметрами, для примера
soffice --convert-to pdf report.docx --outdir temp_dir
затем высылает вместо оригинала отчета полученный файл PDF.
Путь к утилите soffice
ищется в директориях, заданных переменной среды PATH
. Можно указать прямой путь в аргументах командной строки сервера отчетов.
Файлообмен с soffice
идет через временную папку системы. Можно указать рабочую директорию в аргументах командной строки сервера отчетов.
См. вывод команды
reportserver --help
По умолчанию время исполнения команды
soffice --convert-to pdf
для пустого документа - 2.3 секунды (для cpu i7-3615M, ssd). Основное время тратится на инициализацию Libre Office.
Чтобы ускорить конверсию, можно воспользоваться режимом quick start
, то есть предварительным исполнением команды
soffice --quickstart
В этом режиме Libre Office все время находится в оперативной памяти, что экономит примерно 2 секунды.
Внимание: для Libre Office 6.3.4.2 в Ubuntu 19.10 soffice --quickstart
приводит к показу главного окна. Параметры --minimized
и --headless
не решают эту проблему, т.к. не позволяют пользоваться ускорением после однократной конверсии. В Windows 10 при таком запуске LO виден только в трее.
Документы шаблонов в форматах DOCX и XLSX хранятся локальной в директории templates
, расположенной в директории приложения сервиса.
Шаблоны для формирования документов Word должны быть сохранены в формате DOCX.
Шаблоны для формирования документов Excel должны быть сохранены в формате XLSX.
Для создания документов-шаблонов можно использовать текстовый процессор (такой как Libre Office Writer/Calc, Microsoft Word/Excel, Яндекс Документы и т.п.)
Выбор программы зависит от того, какая программа используется получателем отчетов. Гарантий 100% совместимости документов, созданных в разных версиях программ или разными программами, нет. В случае, когда необходимо единообразное представление документа для всех пользователей отчетов, рекомендуется использовать формат PDF.
Шаблоны для последующей конвертации в PDF должны быть сохранены в формате DOCX (желательно с использованием Libre Office, чтобы гарантировать совместимость с конвертером в PDF).
Шаблоны документов могут содержать теги, которые будут заменены входными данными из запроса.
Тег задается в квадратных скобках. Пример: [задолженность]
Входные данные содержатся в input-data
(см. примеры из пункта “Структура запроса”).
В запросе скобки не указываются (см. примеры из пункта “Структура запроса”).
Принцип работы с изображениями:
Теги изображений в шаблоне задаются в свойстве изображения "Замещающий текст" ("Alt text") без квадратных скобок.
Поддерживаемые форматы: JPEG, PNG.
Для документов Word доступны:
Поддерживаются следующие типы таблиц в шаблоне
Примечание: таблицы в колонтитулах документа поддерживаются.
Базовый алгоритм слияния - автоматическое слияние ячеек с одинаковым содержимым по вертикали.
Этого можно избежать при помощи опции запроса formatting.tables.enable-cells-auto-merge
. См. “Запросы для формирования отчетов в формате .docx через Сервис отчетов” в примерах запросов.
Для запросов в формате json поддерживается расширенные опции вертикального и горизонтального слияния.
Объект, описывающий строку таблицы, имеет опциональный объект formatting. Пример:
"formatting": {
"column tag value": {
"vertical_merge": "restart",
"column_span": 2
}
}
Имена полей этого объекта являются названиями столбцов таблицы, для которых нужно применить опцию слияния. Значения полей: объект опции слияния, который имеет поля:
vertical_merge
- строка. Управляет вертикальным слиянием ячейки. Поддерживаемые значения: “restart” - предотвращает слияние соседней ячейкой, расположенной в предыдущей строке того же столбца; “continue” - форсирование слияния с ячейкой выше по столбцу; “unset” - опция слияния будет унаследована от ячейки выше по столбцу;column_span
- целое число. Управляет горизонтальным слиянием ячейки. Значение задает количество ячеек для объединения справа от текущей ячейки (включительно).Примечание: это прямое управление настройками слияния в документе. Чтобы быстро понять, какие значения нужно выставить тем или иным ячейкам, нужно сперва настроить желаемое поведение в текстовом редакторе, сохранить docx документ, разархивировать его как zip архив и посмотреть, какие значения применяются в файле document.xml.
Поддерживаются одноуровневые списки типа "маркеры" и с нумерацией. Пример:
<lists>
<list name="BULLET_LIST">
<items>
<item>bullet item 1</item>
<item>bullet item 2</item>
<item>bullet item 3</item>
</items>
</list>
</lists>
Подробный пример можно найти в подразделе “Запросы для формирования отчетов в формате .docx через Сервис отчетов” в примерах запросов.
Добавление элементов возможно в произвольное место списка в шаблона. В случае пустого списка во входных данных, список удаляется из отчета.
См. в пункте “Формат тегов в шаблоне”.
Части текста шаблона могут быть исключены из отчета в зависимости от истинности условия в условном теге.
[#условие]условный текст шаблона[/условие]
Открывающий тег начинается с символа #, за которым следует условие. Закрывающий тег начинается с символа /, за которым следует условие открывающего тега.
Блок - это фрагмент отчета, содержащий текст/таблицы/списки (все, кроме изображений, в текущей версии). Создается из шаблона-блока (определенного фрагмента документа-шаблона) произвольное количество раз в произвольном месте шаблона с разными наборами входных данных.
Шаблон блока в документе-шаблоне определяется тегами [block-template:произвольное имя шаблона блока]
.
Шаблоны блока полностью удаляются из документа-шаблона перед заменой тегов на входные данные.
Места вставки блоков определяются тегами экземпляров шаблонов блока [block-instances:список имен шаблонов блоков через запятую]
документа-шаблона.
Контент шаблона блока вставляется в документ (с заменой тегов в нем) по месту нахождения тега экземпляра шаблона.
Каждый тег экземпляра шаблона блока указывает, какие именно шаблоны нужно взять за основу для создания блока в отчете (другими словами, инстанциировать шаблон блока). При этом рассматриваются все входные данные блоков по порядку. При замене тегов в шаблоне блока все значения тегов берутся только из объекта data
блока (актуально для текущей версии сервиса отчетов).
В запросе данные блоков определяются массивомblocks
, который содержит объекты block
с полямиblock-template
(совпадает с именем шаблона блока в документе-шаблоне) и полем объекта data
. Объект data
имеет те же дочерние объекты, что и объектinput-data
, кроме изображений и блоков.
Пример:
"blocks": [
{
"block-template": "block1",
"data": {
"таблица1": {
"rows": [{
}
]
},
"сумма_пени": "12 345,67",
"сумма_долга": "78 910,23",
"номер_договора": "1"
}
},
{
"block-template": "block2",
"data": {
"таблица1": {
"rows": [{
}
]
},
"сумма_пени": "76 543,21",
"сумма_долга": "987 654,32",
"номер_договора": "2"
}
},
{
"block-template": "block3",
"data": {
"номер_договора": "1",
"название_договора": "Название договора 1",
"дата_с": "01.01.2000",
"дата_по": "01.01.2100"
}
},
{
"block-template": "block3",
"data": {
"номер_договора": "2",
"название_договора": "Название договора 2",
"дата_с": "02.02.2020",
"дата_по": "02.02.2080"
}
}
]
Подробный пример запроса с использованием блоков и шаблон к нему можно найти в разделах “Запросы для формирования отчетов в формате .docx через Сервис отчетов” (в примерах запросов) и “Шаблоны для формирования отчетов в формате .docx через Сервис отчетов” (в примерах шаблонов).
Доступно создание единого отчета из одного шаблона на основе множества входных данных.
В текущей версии не поддерживаются нумерованные списки.
В текущей версии не поддерживается создание единого отчета из множества шаблонов.
http://localhost:8085/word_multi_report_1_N_xml
http://localhost:8085/word_multi_report_1_N_json
Пример можно найти в подразделе “Запросы для формирования отчетов в формате .docx через Сервис отчетов” в примерах запросов.
Теги в колонтитулах нужно использовать разумно, т.к. в Word нет возможности иметь собственные колонтитулы для каждого отчета.
Замена изображений поддерживается только глобально. Во всех подотчетах будет набор изображений, примененный последним. Это ограничение текущей версии сервиса.
Для документов Excel доступны:
Формат входных данных ячеек - текст и числа(целые или вещественные).
Ссылки на ячейки в формулах при генерации отчета не корректируются. Формулы могут стать неверными в случае добавления-удаления строк в отчет.
Условные выражения в текущей версии не поддерживаются.
API: /excel_report_json
Таблица с форматированием задается следующим образом:
Поддерживается возможность отображения одной строки входных данных на множество строк в документе. Это может понадобиться для таблиц, где в одной логической строке есть ячейки с объединением по вертикали. Количество строк шаблона на одну строку входных данных определяется как максимальное число строк объединенных по вертикали в любой ячейке из первой строки после строки с тегом самой таблицы (см. функцию getNumberOfSheetRowsPerInputDataRow
).
Пример шаблона можно найти в подразделе “Шаблоны для формирования отчетов в формате .xlsx через Сервис отчетов” в примерах шаблонов.
Внимание: на данный момент применение форматирования к сгенерированным строкам не включает в себя настройки шрифта. Поддерживается цвет фона и настройки границ ячеек(например, горизонтальное слияние ячеек).
API: /excel_report_json/v2
Таблица с форматированием задается следующим образом:
Примеры шаблонов в подразделе “Шаблоны для формирования отчетов в формате .xlsx через Сервис отчетов” в примерах шаблонов.:
template_example_cell_format_options.xlsx
template_example_cell_format_options_typed_cells.xlsx
Пример запроса: request_examples\excel\request_example_cell_format_options.json
Его также можно найти в подразделе “Запросы для формирования отчетов в формате .xlsx через Сервис отчетов” в примерах запросов.
Внимание: на данный момент применение форматирования к сгенерированным строкам не включает в себя настройки шрифта. Поддерживается цвет фона и настройки границ ячеек(например, горизонтальное слияние ячеек).
Базовый алгоритм слияния - применение горизонтального слияния генерируемых ячеек на основе слияния ячеек таблицы шаблона.
Поддерживается расширенные опции вертикального слияния, задается объектом с единственным полем
vertical_span
- целое число. Управляет вертикальным слиянием ячейки. Значение задает количество ячеек для объединения вниз от текущей ячейки (включительно)Опции могут быть привязаны к столбцам таблицы в шаблоне, задаваемым по индексу
"formatting": {
"template-cells": [
{
"vertical_span": 2
},
...
]
}
или к тегам ячеек (данный способ имеет приоритет, что удобно для избирательной коррекции опций слияния для части столбцов):
"formatting": {
"tags": {
"cell_tag_value": {
"vertical_span": 2
},
}
}
Формула в запросе задается объектом с полями
{
"type": "formula",
"format": "raw",
"value": "SUM(D1:D20)"
},
Преобразований номеров строк не выполняется. Предполагается, что номера строк актуальны для финального отчета, то есть после вставки строк таблицы, идущих перед строкой, содержащей формулу. Номер строк можно рассчитать на основе номеров строк таблицы в документе-шаблоне и количества строк таблицы на момент генерации строки с формулой в запросе.
Пример запроса: request_examples\excel\request_example_formula.json
Строки, заданные списком rows-to-add
будут добавлены в конец шаблона без сохранения/применения форматирования
См. пример запроса simple.json
в подразделе “Запросы для формирования отчетов в формате .xlsx через Сервис отчетов” в примерах запросов.
См. в пункте “Формат тегов в шаблоне”.
Возможен вывод строки текста в виде штрихкода. Для корректной работы в отчетах Word и Excel в операционной системе должны быть установлены шрифты семейства Libre Barcode. Доступны в репозитории librebarcode. Каждый шрифт представляет собой определенный формат штрихкода. Поддерживаются следующие форматы:
Шрифт может включать оригинальный текст непосредственно под штрихкодом (шрифты с суффиксом Text).
Рассмотрим применение на примере формата Code-128.
Шрифты для установки:
LibreBarcode128Text-Regular.ttf
, будет доступен под именем "Libre Barcode 128 Text"LibreBarcode128-Regular.ttf
, будет доступен под именем "Libre Barcode 128"В шаблоне для обычного тега выбрать шрифт. Например, "Libre Barcode 128 Text".
Word
curl --request POST --data-binary "@request_examples/word/barcode_code-128.json" http://localhost:8085/word_report_json
Excel
curl --request POST --data-binary "@request_examples/excel/barcode_code-128.json" http://localhost:8085/excel_report_json