Программный интерфейс к функциям комплекса общесистемных сервисов

Описание API КОСС

В настоящем документе описывается программный интерфейс к функциям комплекса общесистемных сервисов (КОСС). Его методы упрощают использование функций КОСС во внешних прикладных программах и программных системах. Реализован в форме модуля на языке php.

1. Используемые методы.

1.  Вызов сервиса отправки данных: sendData($task_id, $doc_type_id, $op_type, $user_id, $object_id, $user_roles, $text_detail, $doc_body, &$exception_mes)

Параметры (все обязательны):

• $task_id - (строка) идентификатор задачи. Является уникальным числом, определяющим задачу обмена в САУ ТО. Зарезервированное значение: 1 , используется для доставки произвольного текстового сообщения пользователям другого объекта. Значение должно быть указано в соотв. поле в одной или нескольких записях таблицы koss.route_objects_tasks;
• $doc_type_id - (строка) тип документа. Является уточнением маршрута передачи. Должно соответствовать ключу таблицы koss.doc_types. Значение должно быть указано в соотв. поле в записях таблицы koss.route_objects_tasks, отобранных по значению $task_id для однозначного выбора маршрута. Значение 1 зарезервировано для доставки произвольного текстового сообщения пользователям другого объекта;
• $op_type - (int) тип операции. Используется на приёмной стороне  для упрощения работы обработчика передаваемой информации. Возможные значения: "0": изменение; "1": добавление; "-1": удаление. Если не применимо, указывается значение "0";
• $user_id - (int) id пользователя – инициатора отправляемого сообщения обмена. Значение должно соответствовать таблице permission.users. Для системных обменов (например, web-сервис) указывается значение "-1";
• $object_id - (строка) id объекта-получателя. Должно соответствовать значению в таблице koss.objects_asu. Это значение используется для "ручной" маршрутизации - при поиске требуемого маршрута в таблице koss.route_objects_tasks в соотв. поле д.б. установлено "NULL". Параметр может принимато значение "NULL", в этом случае производится только автоматическая маршрутиазция, т.е. в табл.  koss.route_objects_tasks в соотв. поле д.б. установлено значение- идентификатор объекта;
• $user_roles - (массив строк) массив строк с номерами ролей пользователей в соответствии с таблицей permission.user_roles, которым требуется доставить данное сообщение обмена (например, ["1","8","11"]). При автоматической маршрутизации (например, при дублирующей отправке "Акта …" в адрес органа планирования) используются записи из табл. koss.route_users_message для автоматической подстановки получателей оповещения о данном документе. Если пользователи не участвуют в процессе обмена (например, синхронизация номенклатора, справочников), в качестве параметра должен быть указан пустой массив: [""] ;
• $text_detail - (строка) – текст уточняющего сообщения, подставляемого в автоматически формируемое оповещение пользователям на приёмной стороне. Например, при передаче документа, здесь нужно указать: «Акт приёма МТС № 155 от 01.02.16»;
• $doc_body - (строка) тело документа/справочника/сообщения пользователю. Допускается форматы гладкого текста, HTML, XML, Base64;
• $exception_mes – (строка, значение передаётся по ссылке) – в этот параметр будет помещён текст ошибки при отправке сообщения обмена. Этот текст следует отобразить пользователю для указания причины невозможности выполнить операцию обмена.

Возвращаемое значение: true, если сообщение передано успешно; false – при ошибке (сообщение не было отправлено).

Пример использования метода сервиса отправки приведен в файле koss/mes/send_message.php , строка 47.

1.  Вызов обработчика входящего сообщения обмена.

Обработчик входящего сообщения обмена может быть вызван двумя способами:

1. Web-сервером apache как функция в файле php (файловый способ);
2. http-сервером apache как URL-файл php (http способ).

В обоих случаях обработчик указывается записью в таблице koss.web_proc_files:

• web_proc_file_id (int) – идентификатор записи;
• path (строка) - путь к файлу с обработчиками, относительно корня web-сервера, например: /koss/mes/;
• name (строка) - имя файла с обработчиками, например: parse_msg.php;
• predefined (boolean) – признак предопределённой функции оповещения пользователей сервиса обмена (parse_msg2, ...). Признак должен стоять ТОЛЬКО У ОДНОЙ СТРОКИ!!!;
• comment (строка) - комментарий к файлу с функциями-обработчиками входных данных;
• is_url (boolean) – способ вызова обработчика. False – в строке указывается путь к обработчику с файловым способом вызова. True – обработчик вызывается как URL по http протоколу.

В таблице маршрутов koss.route_objects_tasks для записи соответствующего обработчика указываются поля:

• processor_receiver (строка) – имя функции в файле обработчика, используется только для файлового способа вызова;
• web_proc_file_id (int)  - ссылка на обработчик в таблице koss.web_proc_files;
• auto_message (boolean) – признак, что по факту выполнения обработчика данного сообщения обмена (например, приём документа) требуется автоматически создать оповещение пользователю;
• text_auto_message (строка) - заголовок автоматически создаваемого оповещения пользователю. Пользователи-получатели определяются ролями, указанными в таблице route_users_message (поиск по ключу route_id). В текст сообщения включаются постоянный текст из поля koss.route_objects_tasks  и уточняющий текст, созданный функц. программой отправителем (в поле detailed_text таблиц koss.log_mes_in и koss.log_mes_out).

1.  Вызов сервиса регистрации: write_syslog($user_id=-1, $ip_addr="", $tek_app="", $tek_level=0, $description="", $comment="")

Данный метод записывает диагностическую информацию в системный журнал (таблица koss.system_log). Все параметры являются необязательными.

• $user_id - (не обязат., int) – идентификатор текущего пользователя в соответствии  с таблицей permission.users. Для web-сервиса указываем значение "-1";
• $ip_addr - (не обязат., строка) - ip-адрес компьютера-источника. Если не пустая строка, пытаемся преобразовать его в тип inet. Если пустая строка, производится попытка определения ip-адреса вызывающего  компьютера;
• $tek_app - (не обязат., строка) – приложение. Условное наименование, например, «сервис обмена», «ИУ31» и т.д. Используется для фильтрации записей журнала регистрации при его анализе;
• $tek_level - (не обязат., int) – уровень важности (серьёзности ошибки) записи. Указывается число: 0-Норма/информация; 1-замечание; 2-логическая ошибка; 3-фатальная программная ошибка;
• $description - (не обязат., строка) – событие. Приводится текст – описание события, данных ошибки;
• $comment - (не обязат., строка) – комментарий. Текст – уточнение ошибки/детализация значений переменных программы/рекомендации администратору;

Возвращаемое значение: true, если запись в журнал регистрации проведена успешно; false – при ошибке записи.

Пример использования метода сервиса записb в журнал регистрации приведен в файле koss/mes/send_message.php , строка 50.