Разработка:sync/soap — различия между версиями

Материал из DOF
Перейти к: навигация, поиск
(Коды ошибок)
 
(не показано 6 промежуточных версий этого же участника)
Строка 14: Строка 14:
  
 
У каждого метода присутствуют следующие обязательные служебные параметры:
 
У каждого метода присутствуют следующие обязательные служебные параметры:
* requestime - время генерации запроса, используется для устаревания запроса с целью защиты от атаки на "повторение перехваченного запроса"
+
* requesttime - (UNIX timestamp) время генерации запроса, используется для устаревания запроса с целью защиты от атаки на "повторение перехваченного запроса"
 
* requestlogin - идентифицирует систему-отправитель запроса (задается в sync/soap/cfg/clients.php, вместе с паролем requestpassword и необязательными параметрами)
 
* requestlogin - идентифицирует систему-отправитель запроса (задается в sync/soap/cfg/clients.php, вместе с паролем requestpassword и необязательными параметрами)
 
* requesthash - sha1-хеш от всех полей запроса в алфавитном порядке, включая предыдущие два, а так же поля requestpassword (в самом запросе не участвует). Используется для подтверждения подлинности запроса.
 
* requesthash - sha1-хеш от всех полей запроса в алфавитном порядке, включая предыдущие два, а так же поля requestpassword (в самом запросе не участвует). Используется для подтверждения подлинности запроса.
 +
 +
'''Все параметры, в которых передаётся время, принимают UNIX timestamp, если в подписи к ним не написано иначе.'''
  
 
Имена полей soap-запросов должны совпадать с именами полей в справочниках: [[Разработка:storages/metacontracts | storages/metacontracts ]], [[Разработка:storages/persons | storages/persons ]], [[Разработка:storages/contracts | storages/contracts ]]
 
Имена полей soap-запросов должны совпадать с именами полей в справочниках: [[Разработка:storages/metacontracts | storages/metacontracts ]], [[Разработка:storages/persons | storages/persons ]], [[Разработка:storages/contracts | storages/contracts ]]
Строка 30: Строка 32:
 
* id - переданный в запросе id объекта
 
* id - переданный в запросе id объекта
 
* dofid - внутренний id объекта
 
* dofid - внутренний id объекта
* modified - время изменения объекта
+
* modified - время изменения объекта (UNIX timestamp)
 
* hash - контрольная сумма из storages/sync
 
* hash - контрольная сумма из storages/sync
 
* errorcode - код ошибки, помогающий идентифицировать проблему при исполнении запроса
 
* errorcode - код ошибки, помогающий идентифицировать проблему при исполнении запроса
Строка 39: Строка 41:
  
 
** vars формируется следующим образом:
 
** vars формируется следующим образом:
*** Из полей объекта для SOAP-запроса исключаются служебные данные — requesthash, requestlogin, requesttime и дополнительный массив cov
+
*** Из полей объекта для SOAP-запроса исключаются служебные данные — requesthash, requestlogin, requesttime и дополнительный объект cov
 
*** Поля сортируются в алфавитном порядке;
 
*** Поля сортируются в алфавитном порядке;
 
** cvars — вложенный объект cov, поля которого так же сортируются в алфавитном порядке;
 
** cvars — вложенный объект cov, поля которого так же сортируются в алфавитном порядке;
Строка 67: Строка 69:
 
Поэтому при проверке на сервере хэш не совпадёт.
 
Поэтому при проверке на сервере хэш не совпадёт.
  
=API=
+
=API (внешний) =
  
 
==='''set_meta_contract($input)'''===
 
==='''set_meta_contract($input)'''===
 
''Аргументы:''
 
''Аргументы:''
 
* input(object) - данные метаконтракта, переданные по SOAP. Содержит следующие поля
 
* input(object) - данные метаконтракта, переданные по SOAP. Содержит следующие поля
** requestlogin - Идентификатор системы-отправителя запроса
+
** requestlogin(string) - Идентификатор системы-отправителя запроса
** requesttime - Время генерации запроса
+
** requesttime(int) - Время генерации запроса (UNIX timestamp)
** requesthash - sha1-хеш
+
** requesthash(string) - sha1-хеш
** id - Внешний id метаконтракта
+
** id(int) - Внешний id метаконтракта
** num - Номер метаконтракта
+
** num(string) - Номер метаконтракта
** departmentcode - Код подразделения
+
** departmentcode(string) - Код подразделения
** cov - Дополнительный массив cov, содержащий дополнительные поля к объекту
+
** cov(object) - Дополнительный объект cov, содержащий дополнительные поля к объекту
 
''Возвращаемые значения:''
 
''Возвращаемые значения:''
 
* (object) - объект со следующими полями
 
* (object) - объект со следующими полями
** id - Внешний id объекта (переданный в запросе id)
+
** id(int) - Внешний id объекта (переданный в запросе id)
** dofid - Внутренний id объекта
+
** dofid(int) - Внутренний id объекта
** modified - Дата модификации созданного или обновлённого объекта
+
** modified(int) - Дата модификации созданного или обновлённого объекта
** hash - Хеш операции в storage/sync
+
** hash(string) - Хеш операции в storage/sync
** errorcode - Код ошибки, если таковые возникли
+
** errorcode(string) - Код ошибки, если таковые возникли
  
  
Строка 91: Строка 93:
 
''Аргументы:''
 
''Аргументы:''
 
* input(object) - данные персоны, переданные по SOAP. Содержит следующие поля
 
* input(object) - данные персоны, переданные по SOAP. Содержит следующие поля
** requestlogin - Идентификатор системы-отправителя запроса
+
** requestlogin(string) - Идентификатор системы-отправителя запроса
** requesttime - Время генерации запроса
+
** requesttime(int) - Время генерации запроса (UNIX timestamp)
** requesthash - sha1-хеш
+
** requesthash(string) - sha1-хеш
** id - Внешний id метаконтракта
+
** id(int) - Внешний id метаконтракта
** firstname - Имя
+
** firstname(string) - Имя
** middlename - Отчество
+
** middlename(string) - Отчество
** lastname - Фамилия
+
** lastname(string) - Фамилия
** preferredname - Префикс для имения (Mr. Dr. Г-н, Г-а)
+
** preferredname(string) - Префикс для имения (Mr. Dr. Г-н, Г-а)
** dateofbirth - Дата рождения в UTS
+
** dateofbirth(int) - Дата рождения в UTS
** gender - Пол (male, female, unknown)
+
** gender(string) - Пол (male, female, unknown)
** email - Основной адрес электронной почты
+
** email(string) - Основной адрес электронной почты
** phonehome - Домашний телефон
+
** phonehome(string) - Домашний телефон
** phonework - Рабочий телефон
+
** phonework(string) - Рабочий телефон
** phonecell - Сотовый телефон
+
** phonecell(string) - Сотовый телефон
** passtypeid - Тип удостоверения личности (1 - свидетельство о рождении, 2 - паспорт гражданина РФ, 3 - загранпасспорт, 4 - разрешение на временное проживание лица без гражданства, 5 - вид на жительство, 6 - военный билет, 7 - водительсткое удостоверение пластиковое, 8 - вод. удостоверение форма 1, 9 - вод. удостоверение международное)
+
** passtypeid(int) - Тип удостоверения личности (1 - свидетельство о рождении, 2 - паспорт гражданина РФ, 3 - загранпасспорт, 4 - разрешение на временное проживание лица без гражданства, 5 - вид на жительство, 6 - военный билет, 7 - водительсткое удостоверение пластиковое, 8 - вод. удостоверение форма 1, 9 - вод. удостоверение международное)
** passportserial - Серия удостоверения личности (если предусмотрена типом документа)
+
** passportserial(string) - Серия удостоверения личности (если предусмотрена типом документа)
** passportnum - Номер удостоверения личности
+
** passportnum(string) - Номер удостоверения личности
** passportdate - Дата выдачи удостоверения личности в UTS
+
** passportdate(int) - Дата выдачи удостоверения личности в UTS
** passportem - Название организации, выдавшей удостоверение личности
+
** passportem(string) - Название организации, выдавшей удостоверение личности
** citizenship - Гражданство
+
** citizenship(string) - Гражданство
** departmentcode - Основной отдел, к которому приписан человек (может редактировать его данные в persons)
+
** departmentcode(string) - Основной отдел, к которому приписан человек (может редактировать его данные в persons)
** about - Характеристика личности
+
** about(string) - Характеристика личности
** skype - Уникальный идентификатор в Skype
+
** skype(string) - Уникальный идентификатор в Skype
** phoneadd1 - Дополнительный телефон 1
+
** phoneadd1(string) - Дополнительный телефон 1
** phoneadd2 - Дополнительный телефон 2
+
** phoneadd2(string) - Дополнительный телефон 2
** phoneadd3 - Дополнительный телефон 3
+
** phoneadd3(string) - Дополнительный телефон 3
** emailadd1 - Дополнительная электронная почта 1
+
** emailadd1(string) - Дополнительная электронная почта 1
** emailadd2 - Дополнительная электронная почта 2
+
** emailadd2(string) - Дополнительная электронная почта 2
** emailadd3 - Дополнительная электронная почта 3
+
** emailadd3(string) - Дополнительная электронная почта 3
** passportadd(object) - Адрес прописки по паспорту (для генерации документов)
+
** passportaddr(object) - Адрес прописки по паспорту (для генерации документов)
 
** address(object) - Текущий адрес (почтовый адрес)
 
** address(object) - Текущий адрес (почтовый адрес)
 
** birthaddress(object) - Адрес рождения персоны
 
** birthaddress(object) - Адрес рождения персоны
** cov - Дополнительный массив cov, содержащий дополнительные поля к объекту
+
** cov(object) - Дополнительный объект cov, содержащий дополнительные поля к объекту
''Формат объектов: passportadd, address, birthaddress''
+
''Формат объектов: passportaddr, address, birthaddress''
* postalcode - Почтовый индекс
+
* postalcode(string) - Почтовый индекс
* country - Код страны проживания (по предъявленному паспорту) в ICO 3166-1:1997 (RU)
+
* country(string) - Код страны проживания (по предъявленному паспорту) в ICO 3166-1:1997 (RU)
* region - Код региона по ISO 3166-2 (RU-NGR, RU-MOS)
+
* region(string) - Код региона по ISO 3166-2 (RU-NGR, RU-MOS)
* county - Административный район
+
* county(string) - Административный район
* city - Город
+
* city(string) - Город
* streetname - Название улицы
+
* streetname(string) - Название улицы
* streettype - Тип улицы
+
* streettype(string) - Тип улицы
* number - Номер дома
+
* number(string) - Номер дома
* gate - Подъезд
+
* gate(string) - Подъезд
* floor - Этаж
+
* floor(string) - Этаж
* apartment - Квартира
+
* apartment(string) - Квартира
* latitude - Широта в градусах
+
* latitude(float) - Широта в градусах
* longitude - Долгота в градусах
+
* longitude(float) - Долгота в градусах
 
''Возвращаемые значения:''
 
''Возвращаемые значения:''
 
* (object) - объект со следующими полями
 
* (object) - объект со следующими полями
** id - Внешний id объекта (переданный в запросе id)
+
** id(int) - Внешний id объекта (переданный в запросе id)
** dofid - Внутренний id объекта
+
** dofid(int) - Внутренний id объекта
** modified - Дата модификации созданного или обновлённого объекта
+
** modified(int) - Дата модификации созданного или обновлённого объекта
** hash - Хеш операции в storage/sync
+
** hash(string) - Хеш операции в storage/sync
** errorcode - Код ошибки, если таковые возникли
+
** errorcode(string) - Код ошибки, если таковые возникли
  
  
Строка 150: Строка 152:
 
''Аргументы:''
 
''Аргументы:''
 
* input(object) - данные договора, переданные по SOAP. Содержит следующие поля
 
* input(object) - данные договора, переданные по SOAP. Содержит следующие поля
** requestlogin - Идентификатор системы-отправителя запроса
+
** requestlogin(string) - Идентификатор системы-отправителя запроса
** requesttime - Время генерации запроса
+
** requesttime(int) - Время генерации запроса (UNIX timestamp)
** requesthash - sha1-хеш
+
** requesthash(string) - sha1-хеш
** id - Внешний id договора
+
** id(int) - Внешний id договора
** typeid - Тип договора, если у учебного заведения предусмотрено несколько разных типов договоров
+
** typeid(int) - Тип договора, если у учебного заведения предусмотрено несколько разных типов договоров
** num - Номер договора
+
** num(string) - Номер договора
** numpass - Номер пропуска, студенческого билета и т.п.
+
** numpass(string) - Номер пропуска, студенческого билета и т.п.
** date - Дата заключения
+
** date(int) - Дата заключения
** sellerid - Менеджер по работе с клиентами (приемная комиссия, партнер) - добавляет договор, меняет статус до "подписан клиентом", отслеживает статус договора и ход обучения (id по таблице persons)
+
** sellerid(int) - Менеджер по работе с клиентами (приемная комиссия, партнер) - добавляет договор, меняет статус до "подписан клиентом", отслеживает статус договора и ход обучения (id по таблице persons)
** clientid - Клиент, оплачивающий обучение (законный представитель, сам совершеннолетний ученик или куратор от организации, может принимать значение 0 или null, если клиент создается, а контракт имеет черновой вариант) (по таблице persons)
+
** clientid(int) - Клиент, оплачивающий обучение (законный представитель, сам совершеннолетний ученик или куратор от организации, может принимать значение 0 или null, если клиент создается, а контракт имеет черновой вариант) (по таблице persons)
** studentid - Ученик (может принимать значение 0, если ученик создается, а контракт имеет черновой вариант) (по таблице persons)
+
** studentid(int) - Ученик (может принимать значение 0, если ученик создается, а контракт имеет черновой вариант) (по таблице persons)
** notes - Заметки
+
** notes(string) - Заметки
** departmentcode - Подразделение в таблице departments, к которому приписан контракт на обучение (например, принявшее ученика)
+
** departmentcode(string) - Подразделение в таблице departments, к которому приписан контракт на обучение (например, принявшее ученика)
** contractform - Форма договора (шаблон)  
+
** contractform(string) - Форма договора (шаблон)
** organizationid - Юридическое лицо в таблице organizations, оплачивающее договор, если ученик платит за себя сам - то не указывается.
+
** curatorid(int) - Куратор или классный руководитель данного ученика (по таблице persons или не указан), отслеживает учебный процесс, держит связь с учеником, является посредником между учеником и системой, может быть внешней персоной.
** curatorid - Куратор или классный руководитель данного ученика (по таблице persons или не указан), отслеживает учебный процесс, держит связь с учеником, является посредником между учеником и системой, может быть внешней персоной.
+
** enddate(int) - Дата окончания договора
** enddate - Дата окончания договора
+
** metacontractid(int) - id метаконтракта, к которому привязан договор, в таблице metacontracts  
** metacontractid - id метаконтракта, к которому привязан договор, в таблице metacontracts  
+
** cov(object) - Дополнительный объект cov, содержащий дополнительные поля к объекту
** cov - Дополнительный массив cov, содержащий дополнительные поля к объекту
 
 
''Возвращаемые значения:''
 
''Возвращаемые значения:''
 
* (object) - объект со следующими полями
 
* (object) - объект со следующими полями
** id - Внешний id объекта (переданный в запросе id)
+
** id(int) - Внешний id объекта (переданный в запросе id)
** dofid - Внутренний id объекта
+
** dofid(int) - Внутренний id объекта
** modified - Дата модификации созданного или обновлённого объекта
+
** modified(int) - Дата модификации созданного или обновлённого объекта
** hash - Хеш операции в storage/sync
+
** hash(string) - Хеш операции в storage/sync
** errorcode - Код ошибки, если таковые возникли
+
** errorcode(string) - Код ошибки, если таковые возникли
 +
 
 +
 
 +
=Дополнительные методы (внутренние)=
  
 +
===='''check_address($input)'''====
 +
 +
Проверить поля адреса
 +
 +
''Аргументы:''
 +
* input(object) - объект с полями справочника addresses
 +
''Возвращаемые значения:''
 +
* (bool) - true если ошибок не нашли,
 +
* (string) - или код ошибки: [SP19, SP21-SP23]
 +
 +
 +
===='''check_column_types_null($input, $table)'''====
 +
 +
Проверить поля запроса на предмет ненулевых значений и корректности типов справочника
 +
 +
''Аргументы:''
 +
* input(object) - объект SOAP-запроса
 +
* table(string) - название справочника,
 +
''Возвращаемые значения:''
 +
* (bool) - true если ошибок не нашли,
 +
* (string) - или код ошибки: [SC6-SC7], [PR5-PR6]
  
=Дополнительные методы=
 
  
 
===='''check_cov($cov, $fields = null)'''====
 
===='''check_cov($cov, $fields = null)'''====
  
Проверить дополнительный массив на предмет соответствия формату
+
Проверить дополнительный объект на предмет соответствия формату
  
 
''Аргументы:''
 
''Аргументы:''
* cov(array) - дополнительный вложенный массив.
+
* cov(array) - дополнительный вложенный объект.
 
* fields(object) - поля объекта для проверки дублирующихся полей.
 
* fields(object) - поля объекта для проверки дублирующихся полей.
 
''Возвращаемые значения:''
 
''Возвращаемые значения:''
Строка 247: Строка 271:
 
* (bool) - false в случае ошибки, или
 
* (bool) - false в случае ошибки, или
 
* (object) - объект подключения к синхронизации dof_storage_sync_connect
 
* (object) - объект подключения к синхронизации dof_storage_sync_connect
 +
 +
 +
===='''errorlog($input, $queryname=null)'''====
 +
 +
Записывает переданный объект в файл ('/dat/errorlog.txt') для последующей отладки
 +
 +
''Аргументы:''
 +
* input(mixed) - переменная для вывода в файл
 +
* queryname(string) - название запроса (какя именно операция выполняется)
 +
''Возвращаемые значения:''
 +
* (void)
  
  
Строка 346: Строка 381:
 
* (bool) - false, если такого сочетания "метод-справочник" не найдено
 
* (bool) - false, если такого сочетания "метод-справочник" не найдено
 
* (string) - код ошибки
 
* (string) - код ошибки
 +
 +
 +
===='''get_sync_object($table, $provider, $id, $direct = 'down')'''====
 +
 +
Проверить, существует ли объект синхронизации в справочнике storage/sync
 +
 +
''Аргументы:''
 +
* table(string) - справочник, по которому необходимо получить объект
 +
* provider(string) - внешний провайдер (поле storage/sync.upsubsubstorage)
 +
* id - id из таблицы storage/sync
 +
* direct - направление синхронизации
 +
''Возвращаемые значения:''
 +
* (bool) - false, если объект не найден
 +
* (string) - код ошибки
 +
* (object) - объект table с записью
  
  
Строка 364: Строка 414:
  
 
''Аргументы:''
 
''Аргументы:''
* input(object) - SOAP-запрос с обязательными полями id, requesttime, requestlogin, requesthash, массивом cov.
+
* input(object) - SOAP-запрос с обязательными полями id, requesttime, requestlogin, requesthash, объектом cov.
 
* requestpassword(string) - ключ идентификатора системы.
 
* requestpassword(string) - ключ идентификатора системы.
 
''Возвращаемые значения:''
 
''Возвращаемые значения:''
Строка 380: Строка 430:
 
* (bool) - false в случае ошибки
 
* (bool) - false в случае ошибки
 
* (string) - sha1-хеш
 
* (string) - sha1-хеш
 
  
  
Строка 400: Строка 449:
 
* Выполнить дополнительные действия: [[#execute_additional_($input, $operation, $dofid = null)|execute_additional_()]], в случае ошибок сгенерировать ответ
 
* Выполнить дополнительные действия: [[#execute_additional_($input, $operation, $dofid = null)|execute_additional_()]], в случае ошибок сгенерировать ответ
 
* Вставить объект в базу, обработать ошибки
 
* Вставить объект в базу, обработать ошибки
* Обработать массив cov: [[#update_cov($dofid, $inputcov, $plugincode)|update_cov()]], добавить поля в базу, обработать ошибки
+
* Обработать объект cov: [[#update_cov($dofid, $inputcov, $plugincode)|update_cov()]], добавить поля в базу, обработать ошибки
 
* В соответствии с настройками выставить статус через [[#set_status_route($table, $dofid, $departmentid)|set_status_route()]], ошибки только логировать
 
* В соответствии с настройками выставить статус через [[#set_status_route($table, $dofid, $departmentid)|set_status_route()]], ошибки только логировать
  
Строка 410: Строка 459:
 
* (int) - id добавленного объекта
 
* (int) - id добавленного объекта
 
* (string) - код ошибки
 
* (string) - код ошибки
 +
 +
 +
===='''is_sync_object_exists($table, $provider, $id, $direct = 'down')'''====
 +
 +
Проверить, существует ли объект синхронизации в справочнике storage/sync
 +
 +
''Аргументы:''
 +
* table(string) - название справочника
 +
* provider(string) - название клиента, с которым выполняется синхронизация
 +
* id(int) - id объекта, в зависимости от направления синхронизации
 +
* direct(string) - направление синхронизации ('up', 'down')
 +
''Возвращаемые значения:''
 +
* (bool) - результат операции
 +
* (string) - или код ошибки
  
  
Строка 472: Строка 535:
 
===='''update_cov($dofid, $inputcov, $plugincode)'''====
 
===='''update_cov($dofid, $inputcov, $plugincode)'''====
  
Обновить вложенный массив cov для внутренних объектов
+
Обновить вложенный объект cov для внутренних объектов
  
 
''Аргументы:''
 
''Аргументы:''
 
* dofid(int) - внутренний id объекта в таблице $plugincode
 
* dofid(int) - внутренний id объекта в таблице $plugincode
* inputcov(object) - массив или объект, по которому происходит перебор
+
* inputcov(object) - объект, по которому происходит перебор
 
* plugincode(string) - код плагина storage
 
* plugincode(string) - код плагина storage
 
''Возвращаемые значения:''
 
''Возвращаемые значения:''
Строка 489: Строка 552:
 
* Выполнить дополнительные действия: [[#execute_additional_($input, $operation, $dofid = null)|execute_additional_()]], в случае ошибок сгенерировать ответ
 
* Выполнить дополнительные действия: [[#execute_additional_($input, $operation, $dofid = null)|execute_additional_()]], в случае ошибок сгенерировать ответ
 
* Обновить объект в базе, обработать ошибки
 
* Обновить объект в базе, обработать ошибки
* Обработать массив cov: [[#update_cov($dofid, $inputcov, $plugincode)|update_cov()]], добавить поля в базу, обработать ошибки
+
* Обработать объект cov: [[#update_cov($dofid, $inputcov, $plugincode)|update_cov()]], добавить поля в базу, обработать ошибки
  
 
''Аргументы:''
 
''Аргументы:''
Строка 513: Строка 576:
 
** PR3 - Отсутствует контрольная сумма [requesthash]
 
** PR3 - Отсутствует контрольная сумма [requesthash]
 
** PR4 - Отсутствует идентификатор объекта [id]
 
** PR4 - Отсутствует идентификатор объекта [id]
 +
** PR5 - Отсутствует значение в ненулевом поле
 +
** PR6 - Некорректный тип переданного поля
 
* Некорректные [PI]
 
* Некорректные [PI]
 
** PI3 - Контрольная сумма запроса не совпадает
 
** PI3 - Контрольная сумма запроса не совпадает
Строка 525: Строка 590:
 
** SP2 - Данный e-mail не допустим в системе
 
** SP2 - Данный e-mail не допустим в системе
 
** SP3 - Данный e-mail уже зарегистрирован в системе
 
** SP3 - Данный e-mail уже зарегистрирован в системе
** SP4 - Название подразделения не может быть пустым
+
** SP4 - Название мета-контракта не может быть пустым
 
** SP5 - Подразделения с таким кодом не существует
 
** SP5 - Подразделения с таким кодом не существует
 
** SP6 - Подразделение не актуально
 
** SP6 - Подразделение не актуально
 
** SP7 - Код подразделения должен быть строкового типа
 
** SP7 - Код подразделения должен быть строкового типа
 
** SP8 - Неверно передан параметр с запросом
 
** SP8 - Неверно передан параметр с запросом
 +
** SP9 - Код подразделения не передан, и значения по-умолчанию не найдено
 +
* persons
 +
** SP9 - Имя не может быть пустым
 +
** SP10 - Фамилия не может быть пустой
 +
** SP11 - E-Mail не может быть пустым
 +
** SP12 - Укажите дату рождения персоны
 +
** SP13 - Укажите пол
 +
** SP14 - Укажите корректный пол: Мужской (male) или Женский" (female)
 +
** SP15 - Укажите правильный тип удостоверения личности
 +
** SP16 - Укажите серию паспорта
 +
** SP17 - Укажите номер паспорта
 +
** SP18 - Укажите место выдачи паспорта
 +
** SP19 - Укажите тип улицы
 +
** SP20 - Логин Skype содержит недопустимые символы
 +
** SP21 - В адресе некорректно указана страна
 +
** SP22 - В адресе некорректно указан регион
 +
** SP22 - Нельзя указать регион без страны
 +
** SP23 - Предыдущее поле старого ФИО не заполнено
 +
* contracts
 +
** SP24 - Укажите ученика
 +
** SP25 - Укажите законного представителя
 +
** SP26 - Укажите менеджера по работе с клиентами
 +
** SP27 - Укажите дату заключения договора
 +
** SP28 - Переданный id персоны в поле [Ученик] не найден в базе
 +
** SP29 - Переданный id персоны в поле [Законный представитель] не найден в базе
 +
** SP30 - Переданный id персоны в поле [Менеджер] не найден в базе
 +
** SP31 - Переданный id персоны в поле [Куратор] не найден в базе
 +
** SP32 - Менеджер по-умолчанию не найден
 +
** SP33 - Метаконтракт не найден
 +
** SP34 - Дата заключения договора не в корректном формате
 +
** SP35 - Не найден студент, на которого заключён договор
 +
** SP36 - Нельзя изменить студента, на которого заключён договор
 +
** SP37 - Номер договора должен быть уникальным
 
* Ошибки кодирования [SC]
 
* Ошибки кодирования [SC]
 
** SC1 - Не зарегистрирована функция проверки параметров запроса для данного метода
 
** SC1 - Не зарегистрирована функция проверки параметров запроса для данного метода
Строка 536: Строка 634:
 
** SC4 - Для этого метода не задана таблица, с которой он работает
 
** SC4 - Для этого метода не задана таблица, с которой он работает
 
** SC5 - Неверно указано название операции
 
** SC5 - Неверно указано название операции
 +
** SC6 - Такого справочника не существует
 +
** SC7 - Неизвестный тип переменной
 +
** SC8 - Не удалось получить поля для добавления/обновления объекта в базе
 +
** SC9 - Некорректные параметры в функции проверки объекта синхронизации справочника
 
* Ошибки целостности структуры (базы) [SI]
 
* Ошибки целостности структуры (базы) [SI]
 
** SI1 - Не удалось добавить запись в справочник metacontracts
 
** SI1 - Не удалось добавить запись в справочник metacontracts
Строка 546: Строка 648:
 
** SI8 - Не удалось обновить запись в справочнике addresses
 
** SI8 - Не удалось обновить запись в справочнике addresses
 
** SI9 - Не удалось найти запись в справочнике addresses для обновления
 
** SI9 - Не удалось найти запись в справочнике addresses для обновления
 +
** SI10 - Не удалось найти запись в справочнике persons
 +
* Ошибки рабочих процессов (при смене статусов, исполнении приказов, ...) (workflow) [SW]
 +
** SW1 - Не удалось изменить статус на $a
 +
** SW2 - Статуса с таким именем [$a] не обнаружено
  
 
=Замечания, возможные проблемы=
 
=Замечания, возможные проблемы=
Строка 553: Строка 659:
 
* Ошибки при выполнении запроса, если не передан какой-либо параметр, либо передан лишний параметр
 
* Ошибки при выполнении запроса, если не передан какой-либо параметр, либо передан лишний параметр
 
** Желательно создавать класс (объект), в котором определены все поля и типы запроса, указанные в wsdl. От него создаётся экземпляр класса и поверх этих полей записываются значения. Таким образом, если поля не указаны, они автоматически должны заполняться значением null. Это позволит упростить процедуру хеширования и взаимодействия с сервером.
 
** Желательно создавать класс (объект), в котором определены все поля и типы запроса, указанные в 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_($input)|check_fields_set_department($input)]] - проверки входных параметров, проверка возможности добавить объект в базу без ошибок
 +
** * [[#execute_($input)|execute_set_department($input)]] - основное тело исполнения запроса. Основные действия выполняются в функции [[#execute_set_base($input, $method)|execute_set_base()]], поэтому рекомендуется использовать вызов: return $this->execute_set_base($input, 'set_department');
 +
** Если нужна более расширенная логика, метод можно написать самому (но желательно отталкиваться от общего алгоритма в [[#execute_set_base($input, $method)|execute_set_base()]].
 +
** * [[#execute_additional_($input, $operation, $dofid = null)|execute_additional_set_department($input, $operation, $dofif)]] - метод, который выполняется при вызове [[#insert_object($input, $method, $table)|insert_object()]]
 +
** * При необходимости добавить смену статусов

Текущая версия на 13:14, 9 февраля 2015

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


Описание

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

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

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

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

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

Все параметры, в которых передаётся время, принимают UNIX timestamp, если в подписи к ним не написано иначе.

Имена полей 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 - время изменения объекта (UNIX timestamp)
  • 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) - Время генерации запроса (UNIX timestamp)
    • 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) - Время генерации запроса (UNIX timestamp)
    • 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) - Время генерации запроса (UNIX timestamp)
    • 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_address($input)

Проверить поля адреса

Аргументы:

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

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

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


check_column_types_null($input, $table)

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

Аргументы:

  • input(object) - объект SOAP-запроса
  • table(string) - название справочника,

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

  • (bool) - true если ошибок не нашли,
  • (string) - или код ошибки: [SC6-SC7], [PR5-PR6]


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


errorlog($input, $queryname=null)

Записывает переданный объект в файл ('/dat/errorlog.txt') для последующей отладки

Аргументы:

  • input(mixed) - переменная для вывода в файл
  • queryname(string) - название запроса (какя именно операция выполняется)

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

  • (void)


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_sync_object($table, $provider, $id, $direct = 'down')

Проверить, существует ли объект синхронизации в справочнике storage/sync

Аргументы:

  • table(string) - справочник, по которому необходимо получить объект
  • provider(string) - внешний провайдер (поле storage/sync.upsubsubstorage)
  • id - id из таблицы storage/sync
  • direct - направление синхронизации

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

  • (bool) - false, если объект не найден
  • (string) - код ошибки
  • (object) - объект table с записью


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) - код ошибки


is_sync_object_exists($table, $provider, $id, $direct = 'down')

Проверить, существует ли объект синхронизации в справочнике storage/sync

Аргументы:

  • table(string) - название справочника
  • provider(string) - название клиента, с которым выполняется синхронизация
  • id(int) - id объекта, в зависимости от направления синхронизации
  • direct(string) - направление синхронизации ('up', 'down')

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

  • (bool) - результат операции
  • (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' метод для переданного в качестве аргумента объекта запроса и метода. В случае возникновения ошибок составляет ответный запрос и выполняет логирование. Вызывает следующие методы:

Аргументы:

  • 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]
    • PR5 - Отсутствует значение в ненулевом поле
    • PR6 - Некорректный тип переданного поля
  • Некорректные [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 - Неверно передан параметр с запросом
    • SP9 - Код подразделения не передан, и значения по-умолчанию не найдено
  • persons
    • SP9 - Имя не может быть пустым
    • SP10 - Фамилия не может быть пустой
    • SP11 - E-Mail не может быть пустым
    • SP12 - Укажите дату рождения персоны
    • SP13 - Укажите пол
    • SP14 - Укажите корректный пол: Мужской (male) или Женский" (female)
    • SP15 - Укажите правильный тип удостоверения личности
    • SP16 - Укажите серию паспорта
    • SP17 - Укажите номер паспорта
    • SP18 - Укажите место выдачи паспорта
    • SP19 - Укажите тип улицы
    • SP20 - Логин Skype содержит недопустимые символы
    • SP21 - В адресе некорректно указана страна
    • SP22 - В адресе некорректно указан регион
    • SP22 - Нельзя указать регион без страны
    • SP23 - Предыдущее поле старого ФИО не заполнено
  • contracts
    • SP24 - Укажите ученика
    • SP25 - Укажите законного представителя
    • SP26 - Укажите менеджера по работе с клиентами
    • SP27 - Укажите дату заключения договора
    • SP28 - Переданный id персоны в поле [Ученик] не найден в базе
    • SP29 - Переданный id персоны в поле [Законный представитель] не найден в базе
    • SP30 - Переданный id персоны в поле [Менеджер] не найден в базе
    • SP31 - Переданный id персоны в поле [Куратор] не найден в базе
    • SP32 - Менеджер по-умолчанию не найден
    • SP33 - Метаконтракт не найден
    • SP34 - Дата заключения договора не в корректном формате
    • SP35 - Не найден студент, на которого заключён договор
    • SP36 - Нельзя изменить студента, на которого заключён договор
    • SP37 - Номер договора должен быть уникальным
  • Ошибки кодирования [SC]
    • SC1 - Не зарегистрирована функция проверки параметров запроса для данного метода
    • SC2 - Не зарегистрирована функция исполнения запроса для данного метода
    • SC3 - Не верно передан формат проверки полей вложенного массива cov
    • SC4 - Для этого метода не задана таблица, с которой он работает
    • SC5 - Неверно указано название операции
    • SC6 - Такого справочника не существует
    • SC7 - Неизвестный тип переменной
    • SC8 - Не удалось получить поля для добавления/обновления объекта в базе
    • SC9 - Некорректные параметры в функции проверки объекта синхронизации справочника
  • Ошибки целостности структуры (базы) [SI]
    • SI1 - Не удалось добавить запись в справочник metacontracts
    • SI2 - Не удалось обновить запись в справочнике metacontracts
    • SI3 - Не удалось добавить запись в справочник persons
    • SI4 - Не удалось обновить запись в справочнике persons
    • SI5 - Не удалось добавить запись в справочник contracts
    • SI6 - Не удалось обновить запись в справочнике contracts
    • SI7 - Не удалось обновить запись в справочнике cov
    • SI8 - Не удалось обновить запись в справочнике addresses
    • SI9 - Не удалось найти запись в справочнике addresses для обновления
    • SI10 - Не удалось найти запись в справочнике persons
  • Ошибки рабочих процессов (при смене статусов, исполнении приказов, ...) (workflow) [SW]
    • SW1 - Не удалось изменить статус на $a
    • SW2 - Статуса с таким именем [$a] не обнаружено

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

  • Не совпадает контрольная сумма, ошибка [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()
    • * При необходимости добавить смену статусов