Разработка:sync/soap

Плагин
Название	soap
Тип	sync

Описание

Веб-сервис для интеграции с другими системами по протоколу SOAP. Плагин использует инфраструктуру storages/sync для хранения соответствия внутренних и внешних id объектов и storages/synclog для логирования всех операций синхронизации.

Плагин объявляет SOAP-сервис, который располагается по адресам:

• /sync/soap/soap.php?do=wsdl - wsdl-файл
• /sync/soap/soap.php?do=service - сам сервис

У каждого метода присутствуют следующие обязательные служебные параметры:

• requestime - время генерации запроса, используется для устаревания запроса с целью защиты от атаки на "повторение перехваченного запроса"
• requestlogin - идентифицирует систему-отправитель запроса (задается в sync/soap/cfg/clients.php, вместе с паролем requestpassword и необязательными параметрами)
• requesthash - sha1-хеш от всех полей запроса в алфавитном порядке, включая предыдущие два, а так же поля requestpassword (в самом запросе не участвует). Используется для подтверждения подлинности запроса.

Имена полей soap-запросов должны совпадать с именами полей в справочниках: storages/metacontracts , storages/persons , storages/contracts

Во всех запросах используются только внешние id. Например, при создании персоны новая система передает свой уникальный id, которым она её обозначает. Этот id сохраняется в storages/sync . При создании контракта на обучение, внешняя система передает свой собственный id персоны (которая была создана ранее), плагин sync/soap конвертирует этот id во внутренний через справочник storages/sync и создает запись в storages/contracts . Если внешний id объекта не передан, запрос возвращает ошибку (объект не создается и не обновляется).

Служебные, специальные и автоматически-вычисляемые поля справочников не доступны для редактирования через SOAP-запросы (например adddate, status). Действия, которые запрещены пользователям системы через интерфейс, запрещены и через SOAP-запросы (например, нельзя сменить персону в уже созданном контракте).

Все запросы обрабатывают вложенный объект cov. Все поля внутри объекта cov сохраняются (обновляются) в справочнике storages/cov . Не упомянутые в запросе поля (ранее сохраненные в cov) игнорируются. Все имена полей, присутствующие в соответствующем справочнике зарезервированы и не могут быть переданы через объект cov (например, нельзя сохранить поле cov/status для объекта persons, потому что в нем уже есть поле status).

Подразделение для размещения объекта передается в SOAP-запросах через его код (code), а не id. Успешная операция для методов типа 'set_' возвращает следующую структуру данных:

• id - переданный в запросе id объекта
• dofid - внутренний id объекта
• modified - время изменения объекта
• hash - контрольная сумма из storages/sync
• errorcode - код ошибки, помогающий идентифицировать проблему при исполнении запроса

Для проверки SOAP-запросов используется хеширование по следующему алгоритму:

• requesthash == sha1(requestpassword + requesttime + requestlogin + json(vars) + json(cvars)), где

• • vars формируется следующим образом:
    • Из полей объекта для SOAP-запроса исключаются служебные данные — requesthash, requestlogin, requesttime и дополнительный объект cov
    • Поля сортируются в алфавитном порядке;
  • cvars — вложенный объект cov, поля которого так же сортируются в алфавитном порядке;
  • json() - функция для преобразования массива/объекта в json-строку.
  • Знаком "+" указана конкатенация строк.

Примечание: XML-структура SOAP-запроса для вложенных объектов, таких как cov, должна выглядеть следующим образом:

• <cov>
•     <addfield>RU</addfield>
•     <addfieldtwo>RU-MOS</addfieldtwo>
•     <addfieldtthree>Москва</addfieldtthree>
• </cov>

При использовании ассоциативных массивов, например, на PHP, при попытке передать их SOAP-клиенту произойдёт искажение представления:

• <cov>
•     <item>
•         <key>addfield</key>
•         <value>RU</value>
•     </item>
•     <item>
•         <key>addfieldtwo</key>
•         <value>RU-MOS</value>
•     </item>
•     <item>
•         <key>addfieldthree</key>
•         <value>Москва</value>
•     </item>
• </cov>

Поэтому при проверке на сервере хэш не совпадёт.

API

set_meta_contract($input)

Аргументы:

• input(object) - данные метаконтракта, переданные по SOAP. Содержит следующие поля
  • requestlogin(string) - Идентификатор системы-отправителя запроса
  • requesttime(int) - Время генерации запроса
  • requesthash(string) - sha1-хеш
  • id(int) - Внешний id метаконтракта
  • num(string) - Номер метаконтракта
  • departmentcode(string) - Код подразделения
  • cov(object) - Дополнительный объект cov, содержащий дополнительные поля к объекту

Возвращаемые значения:

• (object) - объект со следующими полями
  • id(int) - Внешний id объекта (переданный в запросе id)
  • dofid(int) - Внутренний id объекта
  • modified(int) - Дата модификации созданного или обновлённого объекта
  • hash(string) - Хеш операции в storage/sync
  • errorcode(string) - Код ошибки, если таковые возникли

set_person($input)

Аргументы:

• input(object) - данные персоны, переданные по SOAP. Содержит следующие поля
  • requestlogin(string) - Идентификатор системы-отправителя запроса
  • requesttime(int) - Время генерации запроса
  • requesthash(string) - sha1-хеш
  • id(int) - Внешний id метаконтракта
  • firstname(string) - Имя
  • middlename(string) - Отчество
  • lastname(string) - Фамилия
  • preferredname(string) - Префикс для имения (Mr. Dr. Г-н, Г-а)
  • dateofbirth(int) - Дата рождения в UTS
  • gender(string) - Пол (male, female, unknown)
  • email(string) - Основной адрес электронной почты
  • phonehome(string) - Домашний телефон
  • phonework(string) - Рабочий телефон
  • phonecell(string) - Сотовый телефон
  • passtypeid(int) - Тип удостоверения личности (1 - свидетельство о рождении, 2 - паспорт гражданина РФ, 3 - загранпасспорт, 4 - разрешение на временное проживание лица без гражданства, 5 - вид на жительство, 6 - военный билет, 7 - водительсткое удостоверение пластиковое, 8 - вод. удостоверение форма 1, 9 - вод. удостоверение международное)
  • passportserial(string) - Серия удостоверения личности (если предусмотрена типом документа)
  • passportnum(string) - Номер удостоверения личности
  • passportdate(int) - Дата выдачи удостоверения личности в UTS
  • passportem(string) - Название организации, выдавшей удостоверение личности
  • citizenship(string) - Гражданство
  • departmentcode(string) - Основной отдел, к которому приписан человек (может редактировать его данные в persons)
  • about(string) - Характеристика личности
  • skype(string) - Уникальный идентификатор в Skype
  • phoneadd1(string) - Дополнительный телефон 1
  • phoneadd2(string) - Дополнительный телефон 2
  • phoneadd3(string) - Дополнительный телефон 3
  • emailadd1(string) - Дополнительная электронная почта 1
  • emailadd2(string) - Дополнительная электронная почта 2
  • emailadd3(string) - Дополнительная электронная почта 3
  • passportaddr(object) - Адрес прописки по паспорту (для генерации документов)
  • address(object) - Текущий адрес (почтовый адрес)
  • birthaddress(object) - Адрес рождения персоны
  • cov(object) - Дополнительный объект cov, содержащий дополнительные поля к объекту

Формат объектов: passportaddr, address, birthaddress

• postalcode(string) - Почтовый индекс
• country(string) - Код страны проживания (по предъявленному паспорту) в ICO 3166-1:1997 (RU)
• region(string) - Код региона по ISO 3166-2 (RU-NGR, RU-MOS)
• county(string) - Административный район
• city(string) - Город
• streetname(string) - Название улицы
• streettype(string) - Тип улицы
• number(string) - Номер дома
• gate(string) - Подъезд
• floor(string) - Этаж
• apartment(string) - Квартира
• latitude(float) - Широта в градусах
• longitude(float) - Долгота в градусах

Возвращаемые значения:

• (object) - объект со следующими полями
  • id(int) - Внешний id объекта (переданный в запросе id)
  • dofid(int) - Внутренний id объекта
  • modified(int) - Дата модификации созданного или обновлённого объекта
  • hash(string) - Хеш операции в storage/sync
  • errorcode(string) - Код ошибки, если таковые возникли

set_contract($input)

Аргументы:

• input(object) - данные договора, переданные по SOAP. Содержит следующие поля
  • requestlogin(string) - Идентификатор системы-отправителя запроса
  • requesttime(int) - Время генерации запроса
  • requesthash(string) - sha1-хеш
  • id(int) - Внешний id договора
  • typeid(int) - Тип договора, если у учебного заведения предусмотрено несколько разных типов договоров
  • num(string) - Номер договора
  • numpass(string) - Номер пропуска, студенческого билета и т.п.
  • date(int) - Дата заключения
  • sellerid(int) - Менеджер по работе с клиентами (приемная комиссия, партнер) - добавляет договор, меняет статус до "подписан клиентом", отслеживает статус договора и ход обучения (id по таблице persons)
  • clientid(int) - Клиент, оплачивающий обучение (законный представитель, сам совершеннолетний ученик или куратор от организации, может принимать значение 0 или null, если клиент создается, а контракт имеет черновой вариант) (по таблице persons)
  • studentid(int) - Ученик (может принимать значение 0, если ученик создается, а контракт имеет черновой вариант) (по таблице persons)
  • notes(string) - Заметки
  • departmentcode(string) - Подразделение в таблице departments, к которому приписан контракт на обучение (например, принявшее ученика)
  • contractform(string) - Форма договора (шаблон)
  • curatorid(int) - Куратор или классный руководитель данного ученика (по таблице persons или не указан), отслеживает учебный процесс, держит связь с учеником, является посредником между учеником и системой, может быть внешней персоной.
  • enddate(int) - Дата окончания договора
  • metacontractid(int) - id метаконтракта, к которому привязан договор, в таблице metacontracts
  • cov(object) - Дополнительный объект cov, содержащий дополнительные поля к объекту

Возвращаемые значения:

• (object) - объект со следующими полями
  • id(int) - Внешний id объекта (переданный в запросе id)
  • dofid(int) - Внутренний id объекта
  • modified(int) - Дата модификации созданного или обновлённого объекта
  • hash(string) - Хеш операции в storage/sync
  • errorcode(string) - Код ошибки, если таковые возникли

Дополнительные методы

check_cov($cov, $fields = null)

Проверить дополнительный объект на предмет соответствия формату

Аргументы:

• cov(array) - дополнительный вложенный объект.
• fields(object) - поля объекта для проверки дублирующихся полей.

Возвращаемые значения:

• (bool) - true если ошибок не нашли,
• (string) - или код ошибки: [PI6-PI8], [SC3]

check_department($code)

Проверить, существует ли такое подразделение и актуальный ли у него статус

Аргументы:

• code(string) - код подразделения.

Возвращаемые значения:

• (bool) - true если ошибок не нашли,
• (string) - или код ошибки: [SP5-SP7]

check_email($email)

Проверяет, можно ли использовать переданный e-mail в системе

Аргументы:

• email(string) - электронная почта.

Возвращаемые значения:

• (bool) - true если ошибок не нашли,
• (string) - или код ошибки: [SP2], [PI4]

check_fields_($input)

Методы с таким префиксом проверяют объект SOAP-запроса на предмет некорректных значений полей

Аргументы: см. метод set_method()

• input(object) - содержит поля запроса

Возвращаемые значения:

• (bool) - true если ошибок не нашли,
• (string) - или код ошибки

check_hash($input)

Проверяет входящий запрос по sha1-хешу, сверяя наличие требуемых полей и выдаёт код ошибки при её наличии

Аргументы:

• input(object) - содержит поля запроса, а так же обязательные поля - id, requesttime, requestlogin, requesthash.

Возвращаемые значения:

• (bool) - true в случае успеха,
• (string) - иначе - код ошибки: [PR0-PR4], [PI3]

connect_sync($pcode, $provider, $substorage = null)

Создать соединение с объектом синхронизации по названию справочника и поставщику данных

Аргументы:

• pcode(string) - название плагина для синхронизации (metacontracts, persons, ...)
• provider(string) - название поставщика синхронизации
• substorage(string) - код внутреннего субсправочника

Возвращаемые значения:

• (bool) - false в случае ошибки, или
• (object) - объект подключения к синхронизации dof_storage_sync_connect

execute_($input)

Методы с таким префиксом исполняют действия, сопутствующие SOAP-запросу

Аргументы: см. метод set_method()

• input(object) - запрос, должен содержать поля справочника

Возвращаемые значения:

• (bool) - true если ошибок не нашли,
• (string) - или код ошибки

execute_additional_($input, $operation, $dofid = null)

Методы с таким префиксом исполняют дополнительные действия в SOAP-запросе

Аргументы: см. метод insert_object()

• input(object) - запрос, должен содержать поля справочника
• operation(string) - название операции: 'insert', 'update', ...
• dofid(int) - id объекта из справочника (если не null, то операция 'update', иначе - 'insert')

Возвращаемые значения:

• (bool) - операция прошла успешно
• (object) - возвращает дополнительные поля, которые надо присоединить к объекту в методе insert_object()
• (string) - или код ошибки

execute_set_base($input, $method)

Выполнить базовые действия метода set_:

• 1) Получить объект синхронизации
• 2) Получить объект для ответа
• 3) Просчитать хеш объекта (без служебных полей)
• 4) Есть ли объект синхронизации с таким id в базе?
• 4.1) Объект найден. Проверить, нужно ли производить синхронизацию
• 4.1.1) Синхронизация нужна
• 4.1.1.1) Обновить объект в базе (update_object()), объект синхронизации и сгенерировать ответ 'OK'
• 4.1.1.2) Логирование
• 4.1.1.3) Cгенерировать ответ 'OK', синхронизация успешна
• 4.1.2) Синхронизация не нужна, сгенерировать ответ 'ОК'
• 4.2) Объект не найден.
• 4.2.1) Добавить объект в базу (insert_object()), обрабатывая ошибки, объект синхронизации
• 4.2.2) Логирование
• 4.2.3) Cгенерировать ответ 'OK', синхронизация успешна
• 5) Вернуть ответ

Аргументы: см. метод insert_object() и update_object()

• input(object) - объект SOAP-запроса
• method(string) - метод API, который необходимо выполнить

Возвращаемые значения:

• (object) - объект $response (см. метод set_meta_contract())
• (string) - или код ошибки

get_fields($input, $storage)

Получить поля для вставки или обновления таблицы

Аргументы:

• input(object) - объект с определёнными полями одного из справочника
• storage(string) - название справочника: 'contracts', 'persons', ...

Возвращаемые значения:

• (bool) - false, в случае ошибки
• (object) - объект с полями для вставки/обновления записи в таблице

get_key($requestlogin)

Получить ключ идентификатора системы, используя логин.

Аргументы:

• requestlogin(string) - идентификатор системы (логин)

Возвращаемые значения:

• (bool) - false, если ключ не найден,
• (string) - ключ

get_response($type, $errorcode = 'OK')

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

Аргументы:

• type(string) - тип запроса ('set', 'get', ...)
• errorcode(string) - код ошибки

Возвращаемые значения:

• (bool) - false, если произошла ошибка
• (object) - объект для передачи ответа в SOAP-сообщениях

get_storage_error($method, $storage)

Получить код ошибки справочника по названию метода и таблицы

Аргументы:

• method(string) - название операции со справочником: 'insert', 'update', ...
• storage(string) - название справочника: 'contracts', 'persons', ...

Возвращаемые значения:

• (bool) - false, если такого сочетания "метод-справочник" не найдено
• (string) - код ошибки

get_table($method)

Получить название таблицы (справочника), с которым работает переданный метод

Аргументы:

• method(string) - название метода

Возвращаемые значения:

• (bool) - false, если такого метода не найдено
• (string) - название справочника

hash_object($input, $requestpassword)

Получить sha1-хеш пришедшего SOAP-запроса по описанному ранее алгоритму

Аргументы:

• input(object) - SOAP-запрос с обязательными полями id, requesttime, requestlogin, requesthash, объектом cov.
• requestpassword(string) - ключ идентификатора системы.

Возвращаемые значения:

• (bool) - false в случае ошибки
• (string) - sha1-хеш

hash_uphash($input)

Выполнить хеширование объекта для сравнения с uphash в storage/sync

Аргументы:

• input(object) - SOAP-запрос с полями справочника, без специальных полей request*

Возвращаемые значения:

• (bool) - false в случае ошибки
• (string) - sha1-хеш

insert_address($input)

Добавить новый адрес

Аргументы:

• input(object) - объект с полями справочника

Возвращаемые значения:

• (int) - id добавленного объекта
• (string) - код ошибки

insert_object($input, $method, $table)

Добавить объект в базу:

• Получить из запроса поля для вставки в таблицу: get_fields()
• Выполнить дополнительные действия: execute_additional_(), в случае ошибок сгенерировать ответ
• Вставить объект в базу, обработать ошибки
• Обработать объект cov: update_cov(), добавить поля в базу, обработать ошибки
• В соответствии с настройками выставить статус через set_status_route(), ошибки только логировать

Аргументы:

• input(object) - объект с полями справочника и другими дополнительными полями
• method(string) - метод API, который необходимо выполнить
• table(string) - название справочника: 'contracts', 'persons', ...

Возвращаемые значения:

• (int) - id добавленного объекта
• (string) - код ошибки

normalize_array($item)

Нормализует ошибочно переданный ассоциативный массив в объект

Аргументы:

• item(object) - объект с вложенным массивом item[], в котором находятся объекты:
  • item[0] = stdClass(),
  • item[0]->key,
  • item[0]->value,

Возвращаемые значения:

• (object) - объект, в котором поля {item[0]->key}, а значения: {item[0]->value}

set_method($input, $methodname)

Выполняет базовую проверку переданных параметров (контрольная сумма), проверяет, реализованы ли функции для проверки входных параметров и исполнения запроса, вызывает 'set' метод для переданного в качестве аргумента объекта запроса и метода. В случае возникновения ошибок составляет ответный запрос и выполняет логирование. Вызывает следующие методы:

• ->check_hash()
• ->check_fields_$methodname()
• ->execute_$methodname()

Аргументы:

• input(object) - объект SOAP-запроса (должны присутствовать служебные поля request*)
• methodname(string) - название функции, которую необходимо исполнить

Возвращаемые значения:

• (object) - объект содерщаший поля:
  • id - переданный в запросе id объекта
  • dofid - внутренний id объекта
  • modified - время изменения объекта
  • hash - контрольная сумма из storages/sync
  • errorcode - код ошибки

set_status_route($table, $dofid, $departmentid)

Установить статус согласно маршруту, заданному в конфиге

Аргументы:

• table(string) - название справочника: 'contracts', 'persons', ...
• dofid(int) - внутренний id объекта из таблицы $storage
• departmentid(int) - id из таблицы departments

Возвращаемые значения:

• (int) - id добавленного объекта
• (array) - код ошибки и описание: array('код_ошибки', 'описание ошибки')

update_address($input, $dofid)

Обновить адрес

Аргументы:

• input(object) - объект с полями справочника и другими дополнительными полями
• dofid(int) - внутренний id объекта в таблице addresses

Возвращаемые значения:

• (bool) - результат обновления
• (string) - код ошибки

update_cov($dofid, $inputcov, $plugincode)

Обновить вложенный объект cov для внутренних объектов

Аргументы:

• dofid(int) - внутренний id объекта в таблице $plugincode
• inputcov(object) - объект, по которому происходит перебор
• plugincode(string) - код плагина storage

Возвращаемые значения:

• (bool) - результат обновления
• (string) - код ошибки

update_object($input, $dofid, $method, $table)

Обновить объект в базе:

• Получить из запроса поля для вставки в таблицу: get_fields()
• Выполнить дополнительные действия: execute_additional_(), в случае ошибок сгенерировать ответ
• Обновить объект в базе, обработать ошибки
• Обработать объект cov: update_cov(), добавить поля в базу, обработать ошибки

Аргументы:

• input(object) - объект с полями справочника и другими дополнительными полями
• dofid(int) - внутренний id объекта в таблице $plugincode
• method(string) - метод API, который необходимо выполнить
• table(string) - название справочника: 'contracts', 'persons', ...

Возвращаемые значения:

• (int) - id добавленного объекта
• (string) - код ошибки

Коды ошибок

При успешном выполнении операции синхронизации возвращается код ошибки 'OK'. В ином случае, возвращается одна из следующих ошибок:

• Ошибки параметров запроса [P]:
• Обязательные [PR]
  • PR0 - Данные запроса пришли в некорректном формате
  • PR1 - Отсутствует идентификатор системы [requestlogin]
  • PR2 - Отсутствует время запроса [requesttime]
  • PR3 - Отсутствует контрольная сумма [requesthash]
  • PR4 - Отсутствует идентификатор объекта [id]
• Некорректные [PI]
  • PI3 - Контрольная сумма запроса не совпадает
  • PI4 - Недопустимые символы в e-mail
  • PI5 - Тип переменной подразделения должен быть строковый
  • PI6 - Тип переменной cov должен быть объектом
  • PI7 - Поля внутри переменной cov не должны быть массивами или объектами
  • PI8 - Поля внутри переменной cov не должны совпадать с полями справочника (например, status, adddate)
• Ошибки внутренние [S]:
• Некорректные параметры [SP]
  • SP1 - Контрольная сумма запроса не совпадает
  • SP2 - Данный e-mail не допустим в системе
  • SP3 - Данный e-mail уже зарегистрирован в системе
  • SP4 - Название подразделения не может быть пустым
  • SP5 - Подразделения с таким кодом не существует
  • SP6 - Подразделение не актуально
  • SP7 - Код подразделения должен быть строкового типа
  • SP8 - Неверно передан параметр с запросом
• Ошибки кодирования [SC]
  • SC1 - Не зарегистрирована функция проверки параметров запроса для данного метода
  • SC2 - Не зарегистрирована функция исполнения запроса для данного метода
  • SC3 - Не верно передан формат проверки полей вложенного объекта cov
  • SC4 - Для этого метода не задана таблица, с которой он работает
  • SC5 - Неверно указано название операции
• Ошибки целостности структуры (базы) [SI]
  • SI1 - Не удалось добавить запись в справочник metacontracts
  • SI2 - Не удалось обновить запись в справочнике metacontracts
  • SI3 - Не удалось добавить запись в справочник persons
  • SI4 - Не удалось обновить запись в справочнике persons
  • SI5 - Не удалось добавить запись в справочник contracts
  • SI6 - Не удалось обновить запись в справочнике contracts
  • SI7 - Не удалось обновить запись в справочнике cov
  • SI8 - Не удалось обновить запись в справочнике addresses
  • SI9 - Не удалось найти запись в справочнике addresses для обновления

Замечания, возможные проблемы

• Не совпадает контрольная сумма, ошибка [PI3]
  • Необходимо обязательно проверять наличие всех полей, описанных в параметрах функций. Все типы параметров должны соответствовать описанным в wsdl-файле. К примеру, если в PHP попытаться передать массив в параметр, принимающий только строки, произойдёт конвертация массива в строку.
• Ошибки при выполнении запроса, если не передан какой-либо параметр, либо передан лишний параметр
  • Желательно создавать класс (объект), в котором определены все поля и типы запроса, указанные в wsdl. От него создаётся экземпляр класса и поверх этих полей записываются значения. Таким образом, если поля не указаны, они автоматически должны заполняться значением null. Это позволит упростить процедуру хеширования и взаимодействия с сервером.

Расширение функционала

• Методы set
  • Рассмотрим на примере создания метода set_department(). Необходимо выполнить следующие действия:

• • 1) Добавить в blocks_dof_sync_soap_soapserver:
  • * set_department() - в нём один единственный вызов: return $this->dof->sync('soap')->set_method($input, __FUNCTION__);
  • * Задокументировать входные параметры, @return object для всех методов set_ пока одинаков

• • 2) Добавить в dof_sync_soap:
  • * check_fields_set_department($input) - проверки входных параметров, проверка возможности добавить объект в базу без ошибок
  • * execute_set_department($input) - основное тело исполнения запроса. Основные действия выполняются в функции execute_set_base(), поэтому рекомендуется использовать вызов: return $this->execute_set_base($input, 'set_department');
  • Если нужна более расширенная логика, метод можно написать самому (но желательно отталкиваться от общего алгоритма в execute_set_base().
  • * execute_additional_set_department($input, $operation, $dofif) - метод, который выполняется при вызове insert_object()
  • * При необходимости добавить смену статусов