Методичка по созданию и обмену документами Mobile SMARTS при самостоятельной интеграции с учетной системой

Возможные средства интеграции

При установке на ПК любой конфигурации Mobile SMARTS вы можете воспользоваться одним из четырех вариантов организации обмена данными между учетной системой пользователя и сервером платформы Mobile SMARTS.

Рассмотрим отличия данных вариантов обмена и принципов их работы более подробно.

Обмен с базой данных «1С: Предприятия» и через собственную интеграцию на базе OLE/COM

Эти два варианта схожи по своей сути, т.к. для организации обмена данными между учетной системой пользователя и Mobile SMARTS применяются две специальные COM-компоненты. Установка и регистрация компонент выполняется автоматически при установке Mobile SMARTS из дистрибутива. В первом случае это COM-компонента, предназначена специально для работы с «1С:Предприятием» и некоторыми другими конфигурациями продуктов 1С (в зависимости от продукта). Во втором случае это неспециализированная универсальная компонента, которая может быть использована с любой учетной системой. Подробнее об этом можно узнать здесь.

В обоих случаях обращение к внешней системе происходит следующим образом:

Обмен через Excel/ CSV файлы

Помимо разнообразных вариантов интеграции с учётными системами, платформа Mobile SMARTS содержит в себе инструменты для интеграции на файлах CSV и Excel.

После установки платформы и развёртывания базы данных Mobile SMARTS становятся доступны следующие варианты обмена в формате CSV и Excel:

• утилиты Excel и CSV обмена;

  
  

• использование специального Excel/CSV коннектора.

  
  

В обоих случаях обмен происходит следующим образом:

1. Создаются файлы-шаблоны, содержащие заголовки полей, по которым будут разбираться файлы, содержащие данные. Эти файлы должны иметь такой же формат, в котором предполагается обмен.
2. В специальную папку обмена (по умолчанию «На терминал») помещаются файлы формата Excel или CSV, который содержат в себе номенклатуру, документы, таблицы и т. п. При этом структура этих файлов должна соответствовать созданным ранее шаблонам.
3. Производится синхронизация с мобильным устройством или базой данных Mobile SMARTS (в зависимости от режима работы базы). При этом на устройство или сервер выгружается номенклатура и документы из папки «На терминал», а обратно загружаются обработанные документы.
4. Обработанные документы при загрузке тоже разбираются по соответствующим файлам-шаблонам и конвертируются в формат Excel или CSV.

Подробнее о данном типе обмена можно узнать здесь.

Обмен данными через REST API

API (Application Programming Interface) — интерфейс для программирования приложений, позволяет удаленно обращаться к функциям приложения и выполнять какие-либо действия в нем. Чаще всего используется для получения данных для мобильных приложений, интернет порталов и интеграции с внешними системами (например, интернет-магазинами).

В качестве API в нашей системе используется REST API на основе протокола OData, в котором собраны наиболее популярные техники работы с данными через HTTP запросы (GET, POST, PUT, PATCH). Более подробную информацию по работе с OData (4.0) можно найти по ссылке.

Удобством использования REST является возможность проверки получаемых данных в обычном браузере, либо использованием стандартных приложений для выполнения HTTP запросов, например Advanced REST client (ARC).

В нашей системе также предусмотрена возможность просматривать структуру API и выполнять простые запросы, используя Swagger.

Подробнее о данном методе обмена вы можете узнать по ссылке.

Описание структуры документа и его основных переменных

В качестве примера будет рассматриваться документ «Приход на склад».

Документ «Приход на склад» используется в следующих бизнес-процессах:

• Приобретение товаров и услуг (проверка документа на ТСД)
• Приобретение товаров и услуг (на основании «Заказа поставщику»)
• Приходный ордер на товары (на основании «Заказа поставщику»)
• Приходный ордер на товары (на основании «Поступления товаров»)
• Приходный ордер на товары (проверка документа на ТСД)

Сам экземпляр документа «Приход на склад» физически представляет собой XML файл, хранящийся на сервере Mobile SMARTS, с данными в полях, определяемых конфигурацией сервера Mobile SMARTS для данного типа документа.

В разрезе обмена данными, в случае файлового обмена, данный документ представляет собой файл в формате XLS, CSV, XML и т. д., который загружается/выгружается из учетной системы и обратно через папки обмена, находящиеся по пути «…\XlsCsv» в корневой директории вашей базы. В общем случае для файлового обмена в XlsCsv предусмотрены следующие папки c указанным содержимым:

В случае использования других вариантов обмена, например COM-коннектора, данные папки и шаблоны не используются, так как данные передаются непосредственно в учетную систему, а шаблоны обмена данными и участвующие в ней поля определены в обработке/конфигурации со стороны самой учетной системы.

Структура и содержание документа «Приход на склад»

В общем смысле любой документ Mobile SMARTS содержит две основные логические части — «шапку» и «табличную часть» документа.

Первая, так называемая «шапка документа», содержит поля с общей информацией о самом документе и правилах его обработки. С точки зрения конфигурации Mobile SMARTS и программирования в ней — это набор полей данных, принадлежащих объекту {Document} и доступных в конфигурации через сам объект {Document} (например {Document.Name} и т. п.).

Вторая, «табличная» часть документа, содержит данные о самих товарах — декларативную (плановую) часть {Document.DeclaredItems} и текущую (фактическую) часть {Document.CurrentItems}, которые с точки зрения конфигурации и программирования, являются коллекцией специального типа данных для описания товаров — DocumentItemCollection и тоже принадлежат конкретному документу. Также табличная часть может содержать дополнительные произвольные табличные данные типа RowCollection и/или вычисляемые поля — это могут быть таблицы характеристик, остатков или серий товара, вычислимые поля для отображения в списках и т. п.

Документ «Приход на склад» с точки зрения обмена данными

Обратите внимание, что при обмене данными между учётной системой и Mobile SMARTS используются далеко не все поля, которые существуют у данного типа документа в конфигурации Mobile SMARTS.

При этом в табличной части шапки документа типа «Приход на склад» при выгрузке из учетной системы присутствуют следующие поля документа:

При выгрузке в обратном направлении (из Mobile SMARTS в учетную систему) набор полей шапки меняется.

Количество существующих и используемых в конфигурации полей намного больше, чем участвующих в обмене с учетной системой. Они нужны для обеспечения работы внутренней логики конфигурации Mobile SMARTS и их набор от конфигурации к конфигурации разнится.

Во случае выгрузки из учетной системы на сервер Mobile SMARTS используются поля таблицы с товарной плановой частью документа {Document.DeclaredItems}. В случае выгрузки уже обработанного и завершённого документа из Mobile SMARTS в учётную систему используется тот же перечень полей, но со смешанными данными из плановой и фактической частей документа {Document.CombinedItems}. Ниже представлено описание полей документа «Приход на склад», участвующих в обмене с учетной системой (для стандартных конфигураций «Склад 15», «Магазин 15»).

Также в конфигурации в документе «Приход на склад» присутствуют следующие поля, не используемые при обмене, но необходимые для обеспечения работы внутренней логики конфигурации.