Документация для интеграции в внешними системами (API v.1.2)

Версия 1.2 от 10.4.2017

Содержание

Протокол обмена

Общее описание протокола и точки подключения

Grotem.Mobile имеет удобный API-интерфейс, позволяющий с помощью специальных запросов обмениваться данными со сторонними системами.

Обмен данными осуществляется посредством передачи сжатых в gzip JSON документов POST запросом по протоколу HTTP.

• Точка подключения находится по адресу:

http(s)://{адрес сервера GROTEM}/{имя решения}/admin/SyncSolutionDatabase - для отправки и получеия данных

• Порт подключения зависит от конфигурации web-сервера
• Используется BASIC-авторизация:
  • имя пользователя - всегда admin
  • пароль - от решения на сервере Grotem.Mobile
• Кодировка файла - UTF-8
• Обязательные заголовки для HTTP-запроса:
  • ‘content-type’: “application/json”,
  • ‘configname’: “GrotemExpress”,
  • ‘configversion’: “1.1.0.0”,
  • ‘deviceId’: “{идентификатор внешнего клиента}”

{идентификатор внешнего клиента} - уникальный идентификатор внешней БД. Должен быть уникальным и фискированным для каждой внешней системы.

Алгоритм синхронизации

Общее описание

При синхронизации сервер GROTEM.Mobile позволяет отслеживать изменения. Для этих целей у всех объектов в БД Grotem.Mobile используется служебное поле Timestamp, где хранится время последнего изменения. При обмене данными в структуре файла обмена предусмотрены поля TimestampFrom и TimestampTo.

В поля Timestamp, TimestampFrom, TimestampTo - записывается время в формате тиков.

Значение этого свойства представляет количество 100-наносекундных интервалов, истекших с полуночи в 12:00:00, 1 января 0001 года (00:00:00 UTC 1 января 0001 по григорианскому календарю)

Пример получения даты в формате тиков на платформе 1С

// Получает время TimeStamp

Функция   ПолучитьТики()

  // Получаем Универсальную дату в миллисекундах (с учетом часового пояса), затем приводим к наносекундам

  Тики = (ТекущаяУниверсальнаяДатаВМиллисекундах() + СмещениеСтандартногоВремени(ЧасовойПояс(),ТекущаяУниверсальнаяДата())* 1000)* 10000;

  Возврат Число(Тики);

КонецФункции // ПолучитьТики()

• Обмен инициируется со стороны клиента (внешней системы).

• Клиент отправляет свой документ с данными и заполненным полем TimestampFrom, в нем передается время последней успешной синхронизации с сервером. Если это поле = 0, то синхронизация считается начальной и клиент получит полный набор данных с сервера.

• Сервер обрабатывает полученные данные:

  • получает документ с данными
  • заполняет в нём поле TimestampTo текущей датой
  • выполняет обновление записей или помечает их как удаленные
  • всем затронутым (обновленным или удаленным) записям присваивается одно и то же значение Timestamp = TimestampTo

• Сервер формирует набор данных для клиента:

  • получает список записей из всех таблиц изменённых после TimestampFrom (у которых Timestamp >= TimestampFrom)
  • дополняет список записей связанными сущностями (подробнее см. “Выгрузка связанных данных")
  • производит фильтрацию данных в соответствии с настроенными для каждой таблицы фильтрами (подробнее см. “Фильтрация данных”)
  • исключает из выгрузки объекты, которые пришли со стороны клиента в рамках текущей сессии обмена
  • формирует JSON-файл, сжимает и возвращает клиенту.

• Клиент обрабатывает полученные данные

  • измененные записи обновляются в БД
  • записи к удалению - удаляются из БД

КлиентКлиентСерверСерверВыборка данных и формирование файлаПередача сформированного JSON (HTTP-POST)Обработка полученных данных (обновление записей и Timestamp)Выборка и фильтрация измененийПодготовка файла ответаОтправка файла в теле ответа HTTP-Code: 200Обработка полученного файлаСохранение полученного TimestampTo (для передачи в следующем обмене)

Выгрузка связанных данных

У всех объектов БД добавлено служебное поле KeyFieldTimestamp. При выгрузке сервер анализирует значение времени в этом поле. И если хотя бы у одного объекта это поле попадает в условия выгрузки (KeyFieldTimestamp >= TimestampFrom):

• сервер анализирует структуру базы данных и получает все связанные таблицы (опираясь на ForeignKey)
• для всех связанных таблиц получает связанные дерево связанных данных по ссылочным полям
• дополняет список выгрузки полученными объектами

Внимание

Установка поля KeyFieldTimestamp может приводить к увеличению времени синхронизации.

Фильтрация данных

Для уменьшения объема передаваемых данных, а также для ограничения доступа к ним на стороне сервера используется фильтрация выгружаемых клиенту данных.

Фильтрация основывается на данных пользователя, авторизованного при подключении к точке входа (см. “Общее описание протокола и точки подключения”)

Фильтры формируются на этапе проектирования структуры данных. Текущие фильтры описаны в разделе “Типовые фильтры”.

Структура файла обмена

Общее описание

Файл обмена формируется и получается в JSON-формате (кодировка UTF-8).

Структура файла обмена одинакова и не зависит от направления обмена.

Общий формат файла выглядит следующим образом:

{
    "Id":"2aedcc06-3d1b-4b29-b5af-d5bacf8326c7",
    "TimestampFrom":0,
    "TimestampTo":636062561934757950,
    "DeletedEntities":[],
    "ChangedEntities":[],
    "FiltersToApply":[]
}

Описание параметров:

• "Id" - уникальный идентификатор сессии обмена. По этому идентификатору также в дальнейшем можно получать информацию о сессии.
• "TimestampFrom" - начальная граница промежутка времени для получения изменений (см. “Общее описание алгоритма синхронизации”)
• "TimestampTo" - конечная граница промежутка времени для получения изменений (обычно сюда передается текущее время). Будет установлено в качестве метки времени “Timestamp” для всех объектов, переданных в файле
• "DeletedEntities"- список удаленных объектов (подробнее см. “Формат выгрузки объекта”)
• "ChangedEntities"- список измененных объектов (подробнее см. “Формат выгрузки объекта”)
• "FiltersToApply" - перечень фильтров (не используется и в текущей версии протокола игнорируется)

Формат выгрузки объекта

Для передачи в файле обмена в секциях "DeletedEntities" и "ChangedEntities" используются списки объектов. Каждый элемент списка представляет собой следующий формат

...
"ChangedEntities":[
    {
        "Id": "f365b190-1690-11e6-b0e4-6c71d97753d2",
        "IsDeleted": false,
        "Timestamp": 636217442594783700,
        "Tablename": "Catalog.Contacts",
        "SyncFilter": null,
        "Fields": {
            ...
            ...
        },
    }
]
...

Описание полей:

• Обязательные поля для всех объектов (независимо от типа)

  • "Id" - Идентификатор объекта (в формате GUID)
  • "IsDeleted" - признак удаления объекта (такие объекты будут удалены из БД)
  • "Timestamp" - метка времени изменения объекта
  • "Tablename" - имя таблицы, к которой принадлежит объект (подробнее см. “Описание таблиц и полей”)
  • "SyncFilter" - в текущей версии протокола не используется и игнорируется

• "Fields" - поля объекта, характерные для каждой таблицы (подробнее см. “Описание таблиц и полей”)

Пример файла выгрузки

Приведенный пример отображает передачу / получение измененных объектов таблиц:

• Клиент
• Список контактов, связанных с клиентом
• Контактные лица

{
    "Id": "055c2053-8e2f-4b78-b83f-f60b9ecff815", 
    "TimestampFrom": 0,
    "TimestampTo": 636219989844656600,
    "DeletedEntities": [],
    "ChangedEntities": [
        {
            "Id": "f4a4d5d0-1dd3-11e6-b0e7-6c71d97753d2",
            "IsDeleted": false,
            "Timestamp": 636219989755439200,
            "Tablename": "Catalog.Client",
            "SyncFilter": null,
            "Fields": {
                "Id": "f4a4d5d0-1dd3-11e6-b0e7-6c71d97753d2",
                "IsDeleted": false,
                "Timestamp": 636219989755439200,
                "KeyFieldTimestamp": 636217442594783700,
                "Predefined": false,
                "DeletionMark": false,
                "Description": "Иванов Михаил Петрович",
                "Code": "000000003",
                "Latitude": 0,
                "Longitude": 0,
                "Address": "г. Санкт-Петербург, ул. Почтамтская, д. 3-5",
                "Contractor": null
            }
        },
        {
            "Id": "9e0d9b3d-71ef-4568-810f-d8e2bfdea923",
            "IsDeleted": false,
            "Timestamp": 636217442594783700,
            "Tablename": "Catalog.Client_Contacts",
            "SyncFilter": null,
            "Fields": {
                "Id": "9e0d9b3d-71ef-4568-810f-d8e2bfdea923",
                "IsDeleted": false,
                "Timestamp": 636217442594783700,
                "KeyFieldTimestamp": 636217442594783700,
                "Ref": "f4a4d5d0-1dd3-11e6-b0e7-6c71d97753d2",
                "LineNumber": 1,
                "Contact": "f4a4d5cd-1dd3-11e6-b0e7-6c71d97753d2",
                "Actual": false
            }
        },
        {
            "Id": "f4a4d5cd-1dd3-11e6-b0e7-6c71d97753d2",
            "IsDeleted": false,
            "Timestamp": 636217442594783700,
            "Tablename": "Catalog.Contacts",
            "SyncFilter": null,
            "Fields": {
                "Id": "f4a4d5cd-1dd3-11e6-b0e7-6c71d97753d2",
                "IsDeleted": false,
                "Timestamp": 636217442594783700,
                "KeyFieldTimestamp": 636217442594783700,
                "Predefined": false,
                "DeletionMark": false,
                "Description": "Иванов Михаил",
                "Code": "000000002",
                "Position": "",
                "Tel": "+7 (812) 325-49-49",
                "EMail": ""
            }
        }
    ],
    "FiltersToApply":[]
}

Примеры отправки запроса (полная синхронизация)

В приведенных ниже примерах HTTP-заголовок для авторизации ‘authorization’ считаем заранее известным

Предполагаем, что точка входа находится по адресу http://server.ru/grotem/admin/SyncSolutionDatabase

Формируемый файл запроса будет иметь следующий вид:

{
    "Id":"f8685de0-b174-44ea-9d89-b36bab8e8043",
    "TimestampFrom":0,
    "TimestampTo":636219988969526110,
    "DeletedEntities":[],
    "ChangedEntities":[],
    "FiltersToApply":[]
}

Python:

import http.client

server_name = "server.ru"
connection_point = "/grotem/admin/SyncSolutionDatabase"

conn = http.client.HTTPConnection(server_name)

payload = { "Id":"f8685de0-b174-44ea-9d89-b36bab8e8043", 
            "TimestampFrom":0, 
            "TimestampTo":636219988969526110, 
            "DeletedEntities":[], 
            "ChangedEntities":[], 
            "FiltersToApply":[]}

headers = {
    'content-type': "application/json",
    'configname': "GrotemExpress",
    'configversion': "1.1.0.0",
    'authorization': "Basic RGV2MTpEZXYx",
    'deviceId': "66baa76a-71fe-4395-b4a6-0b77bee9526d"
    }

conn.request("POST", connection_point, payload, headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

C#:

var client = new RestClient("http://server.ru/grotem/admin/SyncSolutionDatabase");
var request = new RestRequest(Method.POST);
request.AddHeader("authorization", "Basic RGV2MTpEZXYx")
       .AddHeader("configversion", "1.1.0.0")
       .AddHeader("configname", "GrotemExpress")
       .AddHeader("content-type", "application/json")
       .AddHeader("deviceId", "66baa76a-71fe-4395-b4a6-0b77bee9526d")
       .AddParameter("application/json", "{\"Id\":\"f8685de0-b174-44ea-9d89-b36bab8e8043\",\"TimestampFrom\":0,\"TimestampTo\":636219988969526110,\"DeletedEntities\":[],\"ChangedEntities\":[],\"FiltersToApply\":[]}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);

Описание таблиц и полей

Типы данных

Перечисления (ENum)

Для всех перечислений структура таблиц единая

Enum.ChequeType

Значения:

Enum.PositionPaymentType

Значения:

Enum.CheckListStatus

Значения:

Enum.FoReminders

Значения:

Enum.ResultEvent

Значения:

Enum.StatsNeedNum

Значения:

Enum.StatusEquipment

Значения:

Enum.StatusImportance

Значения:

Enum.StatusTasks

Значения:

Enum.StatusyEvents

Значения:

Enum.TypesDataParameters

Значения:

Enum.TypesEvents

Значения:

Enum.VATS

Значения:

Enum.Webactions

Значения:

Catalog.Accounts

Список полей:

Catalog.Actions

Список полей:

Catalog.Actions_ValueList

Список полей:

Catalog.Client

Список полей:

Catalog.Client_Contacts

Список полей:

Catalog.Client_Files

Список полей:

Catalog.Client_Parameters

Список полей:

Catalog.ClientOptions

Список полей:

Catalog.ClientOptions_ListValues

Список полей:

Catalog.Contacts

Список полей:

Catalog.Equipment

Список полей:

Catalog.Equipment_Equipments

Список полей:

Catalog.Equipment_EquipmentsHistory

Список полей:

Catalog.Equipment_Files

Список полей:

Catalog.Equipment_Parameters

Список полей:

Catalog.EquipmentOptions

Список полей:

Catalog.EquipmentOptions_ListValues

Список полей:

Catalog.EventOptions

Список полей:

Catalog.EventOptions_ListValues

Список полей:

Catalog.ListOfPayments

Список полей:

Catalog.Positions

Список полей:

Catalog.RIM

Список полей:

Catalog.Roles

Список полей:

Catalog.RoleWebactions

Список полей:

Catalog.ServiceAgreement

Список полей:

Catalog.SettingMobileApplication

Список полей:

Catalog.SKU

Список полей:

Catalog.TypesDepartures

Список полей:

Catalog.User

Список полей:

Catalog.User_Bag

Список полей:

Catalog.User_RemainsNorms

Список полей:

Document.CheckList

Список полей:

Document.CheckList_Actions

Список полей:

Document.Event

Список полей:

Document.Event_CheckList

Список полей:

Document.Event_Equipments

Список полей:

Document.Event_EventFiskalProperties

Список полей:

Document.Event_Files

Список полей:

Document.Event_Parameters

Список полей:

Document.Event_Photos

Список полей:

Document.Event_ServicesMaterials

Список полей:

Document.Event_TypeDepartures

Document.Cheque

Список полей:

Document.Cheque_Nomenclature

Список полей:

Document.Cheque_Payment

Список полей:

Document.Cheque_ChequePhoto

Список полей:

Document.EventHistory

Список полей:

Document.NeedMat

Список полей:

Document.NeedMat_Matireals

Список полей:

Document.Reminder

Список полей:

Document.Reminder_Photo

Список полей:

Document.Task

Список полей:

Document.Task_Status

Список полей:

Document.Task_Targets

Список полей:

Типовые фильтры

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

Ниже приведены фильтры, наложенные на основные таблицы. На таблицы, связанные с основными (у которых имя представляет собой <ИмяОсновной>_<ИмяСвязанной>) - дублируются фильтры основных таблиц

Таблица: “Catalog.TypesDepartures”

Описание фильтра:

“Типы выездов” никак не фильтруются - на все устройства таблица с типами выездов попадает полностью.

Запрос для фильтрации (в формате SQL):

<отсутствует>

Таблица: “Catalog.RIM”

Описание фильтра:

“Услуги и материалы” не фильтруются. На все устройства попадают все “Услуги и материалы”, чтобы мобильные сотрудники могли в рамках Наряда отгружать клиенту любые услуги и материалы.

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

Запрос для фильтрации (в формате SQL):

<отсутствует>

Таблица: “Document.Reminder”

Описание фильтра:

Уведомления не фильтруются. Их передача осуществляется только с мобильного приложения на сервер

Запрос для фильтрации (в формате SQL):

<отсутствует>

Таблица: “Document.Event”

Описание фильтра:

На мобильное устройство уходят Наряды, соответствующие следующим условиям:

• назначенный исполнитель соотвествует пользователю, авторизованному на мобильном устройстве
• плановая дата Наряда находится текущая либо в будущем и статус один из: ....
• плановая дата Наряда на 31 день в прошлом и статус один из: …

Запрос для фильтрации (в формате SQL):

t.[Id] IN(SELECT DISTINCT EV.[Id] FROM [Document].[Event] EV JOIN [Enum].[StatusyEvents] SE ON EV.[Status] = SE.[Id] LEFT JOIN [Document].[EventHistory] EH ON EH.Event = EV.Id WHERE (EV.[UserMA] = @UserId OR (EH.UserMA = @UserId AND EH.Date >(getDate()-30))) AND EV.[StartDatePlan] >(getDate() - 31) AND (NOT (SE.[Name] = 'New')) AND (NOT (SE.[Name] = 'Done' OR SE.[Name] = 'Cancel' OR SE.[Name] = 'DoneWithTrouble' OR SE.[Name] = 'Close' OR SE.[Name] = 'NotDone' OR SE.[Name] = 'OnTheApprovalOf') OR ((SE.[Name] = 'Done' OR SE.[Name] = 'Cancel' OR SE.[Name] = 'DoneWithTrouble' OR SE.[Name] = 'Close' OR SE.[Name] = 'NotDone' OR SE.[Name] = 'OnTheApprovalOf') AND EV.[ActualEndDate] >(getDate() - 1)))) 

Таблица: “Document.EventHistory”

Описание фильтра:

“История по нарядам” не фильтруется. Любой сотрудник может увидеть, что происходило по любому наряду, который ему назначен. Доступ к истории возможен только из Наряда, которые в свою очередь фильтруются. Таким образом сотрудник не получит доступа к чужим Нарядам.

Запрос для фильтрации (в формате SQL):

<отсутствует>

Таблица: “Catalog.SKU”

Описание фильтра:

“Номенклатура” попадет на мобильное устройство только та, которая используется в привязанных к Наряду “Услугах и материалах”

Запрос для фильтрации (в формате SQL):

t.Id IN (SELECT DE.SKU FROM [Document].[Event_ServicesMaterials] DE WHERE DE.Ref IN (SELECT SE.Id FROM [Document].[Event] SE WHERE SE.UserMA = @UserId))

Таблица: “Catalog.ServiceAgreement”

Описание фильтра:

На мобильное устройство выгружаются только те “Договоры”, которые привязаны к Оборудованию, имеющемуся в Нарядах текущего пользователя.

Запрос для фильтрации (в формате SQL):

t.Id IN (SELECT SE.CantractService FROM [Catalog].[Equipment_Equipments] SE WHERE SE.Clients IN (SELECT DE.Client FROM [Document].[Event] DE WHERE DE.UserMA = @UserId))

Таблица: “Catalog.EquipmentOptions”

Описание фильтра:

“Параметры оборудования” не фильтруются и полностью уходят на мобильные устройства.

Запрос для фильтрации (в формате SQL):

<отсутствует>

Таблица: “Catalog.Equipment”

Описание фильтра:

На мобильное устройство выгружается только “Оборудование”, имеющееся в Нарядах текущего пользователя

Запрос для фильтрации (в формате SQL):

t.Id IN (SELECT DE.Equipment FROM [Catalog].[Equipment_Equipments] DE WHERE DE.Clients IN (SELECT SE.Client FROM [Document].[Event] SE WHERE SE.UserMA = @UserId))

Таблица: “Catalog.Client”

Описание фильтра:

На мобильное устройство выгружаются “Клиенты” имеющиеся в Нарядах текущего пользователя

Запрос для фильтрации (в формате SQL):

t.Id IN (SELECT DE.Client FROM [Document].[Event] DE WHERE DE.UserMA = @UserId)

Таблица: “Catalog.SettingMobileApplication”

Описание фильтра:

Настройки мобильного приложения не фильтруются и попадают на все мобильные устройства всем пользователям

Запрос для фильтрации (в формате SQL):

<отсутствует>

Таблица: “Catalog.User”

Описание фильтра:

На мобильное устройство выгрузятся только “Сотрудники”, которые участвовали в истории оборудования, связанного с Нарядами текущего пользователя

Запрос для фильтрации (в формате SQL):

t.[Id] = @UserId OR t.[Id] IN (SELECT Executor FROM [Catalog].[Equipment_EquipmentsHistory] WHERE Equipments IN ( SELECT DE.Equipment FROM [Catalog].[Equipment_Equipments] DE WHERE DE.Clients IN (SELECT SE.Client FROM [Document].[Event] SE WHERE SE.UserMA = @UserId))) OR t.[Id] IN (SELECT [Author] FROM [Document].[Event] WHERE [UserMA] = @UserId)

Таблица: “Catalog.Accounts”

Описание фильтра:

“Контрагенты” не фильтруются и попадают на все мобильные устройства. В рамках решения эти данные на мобильном устройстве нигде не отображаются и служат лишь для сохранения целостности данных

Запрос для фильтрации (в формате SQL):

<отсутствует>

Таблица: “Catalog.ClientOptions”

Описание фильтра:

“Параметры клиента” не фильтруются и выгружаются всем мобильным пользователям

Запрос для фильтрации (в формате SQL):

<отсутствует>

Таблица: “Catalog.EventOptions”

Описание фильтра:

“Параметры нарядов” не фильтруются и выгружаются на все мобильные устройства

Запрос для фильтрации (в формате SQL):

<отсутствует>

Таблица: “Document.CheckList”

Описание фильтра:

На мобильнее устройства выгружаются только те “Чек-листы”, которые присутствуют в Нарядах текущего пользователя

Запрос для фильтрации (в формате SQL):

t.Id IN (SELECT DEC.[CheckListRef] FROM [Document].[Event_CheckList] DEC LEFT JOIN [Document].[Event] DE ON DEC.Ref = DE.Id WHERE DE.[UserMA] = @UserId)

Таблица: “Catalog.Actions”

Описание фильтра:

“Вопросы чек-листов” уйдут на мобильное устройство только при условии, что они присутствуют в Чек-листе или в Наряде, назначенном текущему пользователю

Запрос для фильтрации (в формате SQL):

t.Id IN (SELECT DEC.Action FROM [Document].[Event_CheckList] DEC LEFT JOIN [Document].[Event] DE ON DEC.Ref = DE.Id WHERE DE.[UserMA] = @UserId)

Таблица: “Catalog.Contacts”

Описание фильтра:

“Контактные лица” не фильтруются

Запрос для фильтрации (в формате SQL):

<отсутствует>

Таблица: “Document.NeedMat”

Описание фильтра:

“Заявки на материалы” - выгружаются только созданные текущим пользователем

Запрос для фильтрации (в формате SQL):

t.[SR] = @UserId

Таблица: “Document.Task”

Описание фильтра:

“Задачи” не фильтруются, так как могут быть связаны не только с Нарядами, но и с Клиентами и Оборудованием. Пожтому они все должны быть доступны всем пользователям

Запрос для фильтрации (в формате SQL):

<отсутствует>

Таблица: “Catalog.Roles”

Описание фильтра:

“Роли” не фильтруются - контроль прав должен выполняться для всех ролей

Запрос для фильтрации (в формате SQL):

<отсутствует>

Таблица: “Catalog.RoleWebactions”

Описание фильтра:

“Права ролей” - выгружаются полностью для корректного контроля прав

Запрос для фильтрации (в формате SQL):

<отсутствует>

Настройки мобильного приложения

Настройки мобильного приложения являются общими для всех устройств и не зависят от текущего пользователя.

Версии документа и внесенные изменения

• Document.CheckList