Интеграция Zimbra и 1С

Обмен - Обмен с другими системами

В публикации описывается способ интеграции 1С с почтовым сервером Zimbra, используя SOAP сервис. Рассматривать вопрос интеграции будем на примере бизнес задачи, из блока CRM. Реализации общей адресной книги(GAL-Global Address List) между сотрудниками. Сотрудники(компания) ведет весь учет в 1С, в том числе и элементы CRM, а Zimbra выступает лишь в роли почтового сервиса. Сделать данную публикация побудило отсутствие в интернете готовых примеров совместной работы 1С и Zimbra. Надеюсь, она поможет кому-либо сократить время на реализацию похожей задачи.

Вступление

Zimbra Collaboration Suite — почтовый сервер, органайзер и персонализация пользователя. Это решение корпоративного класса для совместной работы с электронной почтой, календарем и офисными инструментами. Более детальное описание решения можно получить по этой Ссылке

Не так давно мы отказались от использования встроенного почтового клиента в УТ 11.2 и удачно переехали в Zimbra Open Source Edition, все пользователи стали счастливы.

Zimbra Open Source Edition, зарекомендовала себя положительно, по лицензированию отличный FAQ ссылка.

После у нас отвалился функционал из блока CRM, а именно:

  • Общая адресная книга email адресов контрагентов, среди всех сотрудников.
  • Автоматическая регистрация взаимодействий, по тем контрагентам, чей email есть в справочнике.
  • Отчеты показывающие активность общения сотрудников с контрагентами, по каналу интернет почты.

Ниже подробно расскажу как решить вопрос общей адресной книги если у Вас тоже 1С и Zimbra.

Для этого нам понадобится:

  • 1C Платформа. В момент написания публикации использовалась версия 8.3.11
  • SOAP UI. Он нам позволит быстро и легко выполнять тестовые вызовы soap сервиса Zimbra, а так же просматривать сами сообщения. Достаточно бесплатной версии Ссылка
  • Рабочая система Zimbra. Для тестов, на этап разработки, можно развернуть тестовый сервер на виртуальной машине под OS Linux, там же установить 1С. Как это сделать в интернете полно инструкций. 

Zimbra

Zimbra понравилась мне еще больше, после того как стало понятно, что она из коробки предоставляет функционал интеграции через SOAP. При этом больше всего радует, что в данном вопросе у этих ребят все задокументировано.

Из коробки у нас есть 7 soap сервисов, в данной публикации мы будем использовать только 2:

  • zimbraAccount - Включает в себя методы для извлечения, хранения и управления информацией учетной записи пользователя.
  • zimbraMail - Включает в себя методы для управления почтой и информацией календаря.

Узнать весь функционал, а так же описание всех методов, можно по данной Ссылке.

После установки почтового сервера, описание wsdl схем от soap Zimbra, у Вас будут доступны по ссылке вида:

https://mail.<Ваш домен>.ru/service/wsdl/ZimbraUserService.wsdl - Где ZimbraUserService это имя нужного сервиса 

Как пример ссылка на wsdl в интернете.

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

После установки автоматически создается учетная запись Gal Sync Account. Именно под ней создаются контакты, которые доступны всем пользователям. Все общие контакты хранятся в выделенной папке, по дефолту это "InternalGAL".А в настройках на сервере остается лишь включить её и выставить время, раз в которое сервер автоматически будет их синхронизировать у себя.

 
 Скрин из консоли администратора Zimbra, настройка GAL Sync Account.

Подробнее можно почитать тут Ссылка.

В нашей задаче все контакты(email адреса), хранятся и заводятся в 1С. А 1С уже через soap, будет их переносить в Zimbra, в регламентом задание. В папку "InternalGAL", используя GAL Sync Account.

Всем пользователям они будут доступны после внутренней синхронизации, которая у нас настроена на выполнение раз в 1 минуту.

Реализация

Выбор способа обращения к soap сервису из кода 1С.

Встретив слова soap, wsdl, сразу становится понятно что мы будем использовать такие объекты 1С платформы как "WS-ссылка","WSПрокси","XDTO".

Но нет, мы будем использовать объекты "HTTPЗапрос","HTTPСоединение", для формирования POST запросов к soap.

Связано это с тем что у Zimbra, для авторизации используется Token Authentication, подробнее можно почитать тут.

Перед вызовом какого либо метода у soap Zimbra, нам нужно авторизоваться, после авторизации мы получаем auth token. В дальнейшем мы должны его использовать при вызове методов.

auth token - Простыми словами, это уникальный ключ авторизации для нашей сессии. Существование, валидность, которого ограничена временем. 

Все мы знаем что структура сообщений, отправляемых через POST,GET запросы, имеет два основных раздела Header и Body.

Так вот Zimbra построила свой soap таким образом что authToken должен присутствовать в Заголовках("Header") сообщений.

А удобные объекты для работы с soap "WS-ссылка","WSПрокси","XDTO", не позволяют 1с разработчику задавать свои свойства в разделе "Header", только "Body".

Именно по этому мы их не используем, а будем использовать "HTTPЗапрос","HTTPСоединение".

При этом формировать сами сообщения, в формате xml, будем встроенным языком 1с. 

Авторизация

Для начала обмена с Zimbra нам нужно авторизоваться.Делать мы это будем под учетной записью GAL Sync Account, поскольку именно под ней мы будем управлять контактами.

Для авторизации soap сервис zimbraAccount предоставляет метод Auth, описание.

Для того что бы понять, какое сообщение нам нужно отправить через POST, мы обратимся к SOAP UI.

Данная публикация не затрагивает мануал по работе в SOAP UI. Для того что бы видеть все методы и формировать сообщения, Вам нужно создать новый проект тип SOAP, указав его название и ссылку на wsdl описание Zimbra.

 
 Под спойлером скриншот, который описывает сообщение в SOAP UI, для метода Auth.

Далее в публикации обращаться к SOAP UI больше не будем, Вы просто должны понимать, что он нужен для просмотра и тестирования сообщений отправляемых в soap сервис.

Хочется затронуть лишь одну деталь, связанную с ним, а именно ссылку которую он по дефолту формирует для сообщений. Она имеет вид "https://mail.<Ваш домен>.ru:8443/service/soap/".  При этом Ваш сервер Zimbra может быть настроен так, что порт 8443 не виден и сделана переадресация.  Верная ссылка будет "https://mail.<Ваш домен>.ru/service/soap/".

Для удобной отправки сообщений(вызов методов soap) и получение результата, реализуем метод:

 
ОтправитьЗапросSOAP(Запрос,SOAPAction)

Данный метод мы будем часто использовать для отправки SOAP сообщений и получения результата. По сути его можно назвать "ВызватьМетодSOAP".

Для авторизации, получения токена, будем использовать следующий метод:

 
 ПолучитьТокенАвторизации()

В данном Случае сам Запрос, сообщение, объявлено просто строкой, в статье это сделано специально, для наглядности. В релизе все xml сообщения лучше формировать стандартным объектом ЗаписьXML. По скольку он будет экранировать нужный символы под формат XML.

Получение всех созданных контактов

Как указано выше, все наши глобальные контакты, у Zimbra, хранятся в определенной папке "InternalGAL".Для того что бы создавать новые контакты, нам нужно знать уникальный ид данной папки.

Самое простое что бы это сделать, мы можем реализовать метод который получит все контакты, а затем мы найдем данную папку и узнаем её ид. Ниже метод который получает все контакты:

 
 ПолучитьКонтактыЗимбы(Токен)

Данный метод получит в ответе большой XML, в котором будут все созданные контакты, у учетной записи GAL Sync. Далее просто для удобства использования перенесет xml в ТаблицуЗначений, у которой каждая строка будет сам контакт, а колонки атрибуты из XML.

В рамках данной публикации из таблицы нам интересна только колонка "l", именно она несет ИД группы, в которой создан контакт. Это и будет ид нашей группы "InternalGAL".

Создание нового контакта

После того как мы узнали ИД группы, в которой будем создавать контакты, можем создать новый контакт.

Для этого zimbra предоставляет метод "CreateContact", у сервиса "zimbraMail", реализуем:

 
 ДобавитьНовыйКонтактВЗимбра(Токен,Контакт)

Данный метод принимает Токен авторизации и свою структуру Контакт, которая заполнена данными для создания. Далее отправляет сообщение в Зимбра и в случае успеха вернет ИД созданного контакта. Используя данный ид, можно выполнять обновление информации по данному контакту(см. ниже).

Что касается сообщения, его формат специально оставлен в данном методе, но для формирования используется:

 
 ПолучитьXMLСообщениеДляЗапроса(Токен,Контакт,ZimbraID=Неопределено,ЭтоГруппа=Ложь)

 Данный метод реализован специально для формирования XML сообщений, с целью экранировать такие символы например как "<",">" и т.д. При этом он сделан немного унифицировано, в том смысле что может формировать сообщение для Создания новых контактов, Обновления существующих, а так же формировать для Групп. Про группы в двух словах поговорим в конце публикации.

 
 Скриншот созданного из 1С контакта в зимбра

На нем видно что у нас папка для общих контактов называется "_zimbra". Персональные данные по понятным причинам замазаны.

Обновление созданного контакта

Для понимания с стороны 1С какие контакты у нас меняются пользователями, создаются, что и как нужно синхронизировать. Мы внесли изменения в конфигурацию, у справочников Контрагенты и КонтактныеЛицаПартнеров добавили два новых реквизита:

  • "ZimbraID" - Число - изначально у всех он равен 0, если ноль значит вызывается метод создать новый контакт. После создания мы в 1с запоминаем его ид из zimbra.
  • "ZimbraState" - Число - изначально у всех равен 0, что значит что он подлежит синхронизации. После синхронизации присваивается 1.

Дополнительно, в карточках Контрагентов и КонтактныхЛиц, в обработчике изменения email адресов на форме, мы дописали свой код. Который при смене пользователем адреса, у уже существующего элемента, присваивает ему ZimbraState=0. 

Таким образом, для того что бы найти в 1С те карточки, которые нужно выгрузить в zimbra, написан простой запрос в котором есть условие "Где ZimbraState=0". Он так же выбирает поле "ZimbraID" и если оно заполнено вызывается метод:

 
 ОбновитьКонтактВЗимбра(Токен,Контакт,ZimbraID)

Данный метод вызывает "ModifyContact" у "zimbraMail", возвращает истина или ложь. Для наглядности в методе оставил xml сообщение.

Работа с группами для рассылки

Так же существуют задачи по формированию Групп для рассылок. Группы могут быть как внешние(например разослать письмо всем покупателям товара "Стол") или внутренние по отделам, структуры компании, для внутренней рассылки.

Для этих целей так же используются методы CreateContact ModifyContact.

А для правильного формирования сообщения, у метода ПолучитьXMLСообщениеДляЗапроса(), последним параметром указываем что это группа. В структуре Контакт, добавляем свойство "СоставИД" это массив, который заполняем ид созданных контактов.

После чего на сервере zimbra будет создана группа, при её вводе пользователем, в поле Кому, сразу подставятся те адреса, ид которых Вы укажите в СоставИД.

Итог

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

От себя хочется добавить лишь пару слов об так называемых Zimlets.

По сути это аналог 1с - совских внешних обработок. Аналогично выполняют роль Zimlets, они позволяют без изменения основного кода системы, расширить её функционал. Ссылка на каталог.

При этом есть достаточно подробно задокументированное API, Ссылка.

Таким образом, если Вам нужно что бы Zimbra обращалась к 1С, Вы можете сделать свой Zimlet, чем мы и собираемся в ближайшее время заняться для решения остальных проблем.

Описание, что для этого нужно

См. также

Комментарии
1. Игорь Steelvan (Steelvan) 31 16.04.18 22:21 Сейчас в теме
Зашел на их сайт.
Документации на русском нет. Закрыл и забыл.

К сожалению, я знаю английский и даже приходится им пользоваться.
Тут дело в принципе. Приходите на рынок, извольте подготовить перевод сайта, программы и документации.
palsergeich; +1 4 Ответить
2. ЦШК «Гексагон» (Гексагон) 16.04.18 22:59 Сейчас в теме
(1)Если Вы подумали что это продвижение продукта на рынке, то Вы ошиблись.
В начале статьи специально выделил редакцию Open Source, она бесплатна и развивается в том числе сообществом.


(1)
К сожалению, я знаю английский и даже приходится им пользоваться.

Если Вы работаете в IT и для Вас сожаление знать английский.
Или читать документацию на английском, мне Вас жаль.
Рекомендую меньше смотреть телевизор.

In the debate on this issue do not intend to join...
A_Max; Shrayky; +2 Ответить
4. Андрей Уваров (oldcopy) 64 18.04.18 09:19 Сейчас в теме
(1) Если вы такой принципиальный, то можете открыть кошелек и купить Exchange. Либо можете помочь сообществу и перевести документацию.
5. Александр alex_2h2008 (alex_sh2008) 5 18.04.18 09:53 Сейчас в теме
(4)У Exchange большая часть технической документации написана на английском языке и ее никто не переводит, ну за исключением может сервиса bing который автоматически переводит.
6. Александр alex_2h2008 (alex_sh2008) 5 18.04.18 09:54 Сейчас в теме
(1)Самое лучшее правило писать всю техническую документацию на английском языке, если вы пишите на 1С и на русском вам этого не понять.
7. DenisCh Гейтс (DenisCh) 18.04.18 09:58 Сейчас в теме
(6)
)Самое лучшее правило писать всю техническую документацию на английском языке

А почему не на китайском или индийском (суахили), их же больше
8. Александр alex_2h2008 (alex_sh2008) 5 18.04.18 10:06 Сейчас в теме
(7)Из за своей особенности, пунктуальности, где слово имеет свое значение, в русском у одного слова несколько значений, английский широко распространен, и он принят за основу написания текстов прилолжений, и не важно на каком языке программирования оно написано.
9. DenisCh Гейтс (DenisCh) 18.04.18 11:19 Сейчас в теме
(8)
Из за своей особенности, пунктуальности, где слово имеет свое значение

Сколько значений имеет слово run?
10. Александр alex_2h2008 (alex_sh2008) 5 18.04.18 11:24 Сейчас в теме
(9)Вы в каждом случае лезете в бутылку.
11. DenisCh Гейтс (DenisCh) 18.04.18 11:27 Сейчас в теме
(10) ответ будет? Или будем переходить на личности? Не хотелось бы, хотя могу.
14. Александр alex_2h2008 (alex_sh2008) 5 18.04.18 11:36 Сейчас в теме
12. Андрей Уваров (oldcopy) 64 18.04.18 11:27 Сейчас в теме
(10) Да нет, это вы сделали опрометчивое заявление, вариативность значений слов и выражений в английском не меньшая, чем в русском. Но суть не в том, документация пишется на английском, потому как по факту это язык международного общения, т.е. это гарантирует, что ее худо бедно прочитают и русский, и китаец и негр преклонных годов.
13. Александр alex_2h2008 (alex_sh2008) 5 18.04.18 11:36 Сейчас в теме
(12)У нас намного выше, я в свое время общался с немцами, писал им на русском, они переводили так что ни кто ничего не понимал, получился сломанный телефон, написал на английском, все поняли. Так что в английском можно четко выразить мысль, без вариаций.
15. Андрей Уваров (oldcopy) 64 18.04.18 12:14 Сейчас в теме
(13) А кто вам мешал четко выразить мысль на русском? Вообще, при использовании чужого языка, если вы не являетесь его носителем, вариативность будет ниже, с этим я соглашусь, так как вы будете строить фразу по словарям и примерам из учебника. Которые от живого языка могут отличаться очень сильно.

Добавлю про немцев, я с ними плотно общаюсь и по работе и лично лет уже 7-8 и могу сказать, что в Германии, особенно восточной, найти человека понимающего русский - абсолютно не проблема. Там даже в ходу русско-немецкий суржик, когда в интернет магазин могут позвонить и попросить "забештеливать кавии" (заказать икры), это реальный случай.
16. Александр alex_2h2008 (alex_sh2008) 5 18.04.18 12:41 Сейчас в теме
(15)Я выражал мысль четко, но проблема была в том что они не были носителями языка, и даже их переводчик фразу строил со своего смыслового понимания фразы. Найти не проблема знающих русский, но вопрос в специфике общения и теме, Русский технический разговорный и тот же самый английский разговорный, или немецкий, сможет перевести только переводчик понимающий смысл о чем идет речь.
17. Александр alex_2h2008 (alex_sh2008) 5 18.04.18 12:48 Сейчас в теме
Или вот пример был с китайцами, заказывал у них антенну GPS/GLONASS, тоже поняли друг друга не с первого раза, я у них на русском по просил при изготовлении выбрать центральную частоту на границах диапазонов, соответственно они не поняли, пока не перешли на конкретные цифры и определи четкую центральную частоту
Оставьте свое сообщение