Short_info

Сводная информация о проекте Пандора
Цель проекта
Обеспечить клиентам возможность автоматического получения данных проекта WebIndex.
Общие условия
1. Разрабатываемые клиентами программные средства должны взаимодействовать по
протоколу http путем формирования запросов методами POST и GET на заранее
оговоренные URL.
2. Все расчеты ведутся на основании базы данных комплекса iStar, что накладывает
требования:
a. Объекты измерения должны быть организованы в виде стандартного
четырехуровневого дерева: Holdings-Projects-Sections-Subsections
b. Ведение этого дерева (добавление/изменение/удаление объектов) проводится
стандартным образом – силами наших менеджеров, после согласования всех
деталей с клиентом
Основные объекты и концепция системы:
Отчет - это именно то, что необходимо посчитать и что называется отчетом в iStar.
Шаблон отчета – это набор данных, описывающих структуру отчета.
Задача - это тот контекст, в рамках которого производится расчет одного или нескольких
отчетов.
Шаблон задачи – список шаблонов отчетов, многократно запускаемых в рамках одной задачи
Клиент – компания, использующая Пандору для своих нужд.
Пользователь – представитель клиента, работающий в Пандоре. При доступе к защищенным
частям системы использует собственный логин и пароль. Имеет собственный пул потоков на
сервере (размер пула определяется администратором Пандоры), а также свой набор доступных
для просмотра сайтов.
Ресурсы пользователя
К персональным ресурсам пользователя относятся
- набор шаблонов отчетов
- набор шаблонов задач
- набор результатов вычислений задач
- собственная очередь задач и пул потоков для их выполнения.
Одновременно выполняется только число задач, равное размеру пула потоков пользователя.
Если задач больше – они ставятся в очередь. Просмотр и управление очередью задач доступны
из web-интерфейса и, отчасти, через web-методы (см. раздел «http-сервис»)
Выполнение задачи
Перед добавлением задачи пользователь должен указать следующие параметры:
- период времени, для которого вычисляются все отчеты задачи
- набор отчетов (точнее их шаблонов), которые надо посчитать
При добавлении задачи (это можно сделать как из web-интерфейса, так и вызвав web-метод) она
либо ставится в очередь задач клиента, либо, если один из потоков в пуле свободен, немедленно
запускается на исполнение.
В процессе выполнения задачи последовательно рассчитываются все включенные в нее отчеты.
После завершения вычислений все результаты сохраняются в БД и могут быть извлечены
пользователем в любое время (просмотрены визуально или получены в формате XML).
С помощью http-сервиса (команда run_custom_report) можно создать задачу для расчета отчета,
шаблон которого передается в команде в формате xml.
http-сервис
http-сервис позволяет осуществлять управление вычислениями и извлечение результатов
автоматически. Для удобства настройки автоматов на web-сайте Пандоры сделан раздел
«Примеры http-обращений к сервису», где можно посмотреть и прямо «руками» попробовать
вызывать web-методы и посмотреть возвращаемый ими XML.
http-cервис предоставляет следующие методы:
vars_get – возвращает список демографических переменных с идентификаторами,
необходимый для анализа результатов вычислений (в XML результата переменные и их
значения представлены идентификаторами)
media_get – возвращает список медиа-объектов, также необходимый для анализа результатов
вычислений.
report_id_get – возвращает список названий и идентификаторов шаблонов отчетов клиента.
Идентификаторы шаблонов отчетов необходимы для указания в методе task_add.
data_status_get – возвращает даты, по которые есть данные.
DataExistLastDate – последняя дата, на которую есть данные. Так как данные выкладываются
понедельно, это всегда последний день недели.
ClosedMonthLastDate – последний день последнего закрытого месяца.
ClosedMonthWithUcpLastDate – последний день последнего закрытого месяца, для которого уже
были добавленные данные по сайтам, измеряемым с помощью User-Centric подхода.
months_get – возвращает список месяцев с флагами готовности данных.
weeks_get – возвращает список недель, для которых есть данные.
data_reloads_get – возвращает список повторных выгрузок данных задним числом.
Подробности см. ниже в разделе «выгрузки данных задним числом».
task_add - добавляет в систему задачу вычисления одного или нескольких отчетов. Параметры
– диапазон дат и список идентификаторов отчетов. Возвращает идентификатор добавленной
задачи.
task_delete - удаляет задачу по ее идентификатору (идентификатор возвращается методом
task_add). Если задача стоит в очереди или выполняется – она отменяется и удаляется. Если
задача уже выполнена – удаляется задача и ее результаты.
run_custom_report - добавляет в систему задание по вычислению пользовательского отчета.
Параметры – диапазон дат и шаблон отчета в формате xml (передается в POST-потоке данных).
Возвращает идентификатор добавленной задачи.
get_task_status – возвращает XML статуса задачи по ее идентификатору.
<State>
<Code>[код статуса задачи]</Code>
<Text>[описание состояния/текст ошибки]</Text>
</State>
Возможные значения кода статуса задачи: NOT_EXIST, IN_QUEUE, IN_PROGRESS,
COMPLETED, TERMINATED.
get_task_result – возвращает результат выполнения задачи по ее идентификатору. Резльтат
выполнения задачи представляет собой XML следующего вида:
<TaskResult>
<ReportOutput/>
<ReportOutput/>
…
<ReportOutput/>
</TaskResult>
Т.е. выдаются все результаты выполнения отчетов, вычисленных в рамках задания. Формат
выходных данных отчета (ReportOutput) описан в отдельном документе.
get_task_report_templates – возвращает шаблоны вычисленных в задании отчетов по
идентификатору задания. Результат команды выглядит так:
<TaskReportTemplates>
<ReportDescription/>
<ReportDescription/>
…
<ReportDescription/>
</TaskReportTemplates>
Каждый тег ReportDescription представляет собой стандартный для системы XML шаблона
отчета.
Вспомогательная команда error_sample при выполнении только порождает исключение,
сообщение о котором возвращается пользователю серверной системой обработки исключений.
Т.е. предоставляет достоверный пример сообщения сервиса об ошибке выполнения команды.
Выгрузки данных задним числом
Выполняются редко и только в случае ошибок в первоначальных данных. Данные за некий
период времени удаляются и заменяются новыми. Для получения информации о таких
выгрузках можно использовать команду data_reloads_get, которая возвращает XML-список
следующего вида:
<DBReloadTable>
<Reloads>
<Reload FinishDay="YYYY-MM-DD" StartDay=" YYYY-MM-DD " ReloadDate=" YYYY-MM-DD ">
<Comments>[Комментарий]</Comments>
</Reload>
</Reloads>
</DBReloadTable>
Здесь атрибуты StartDay и FinishDay обозначают период, за который были повторно выгружены
данные. ReloadDate – день, когда была произведена повторная выгрузка.
Сохранность вычислений
В случае остановки WEB-сервера Пандоры для технических работ, либо внеплановой
остановки, все пользовательские очереди и пулы заданий восстанавливаются после запуска
сервера из базы данных и будут доведены до конца. Сохранение заданий в БД происходит в
момент их добавления пользователем.
В случае необходимости отменить (или удалить) свои задания пользователь может
воспользоваться WEB-интерфейсом. Есть средства как для отмены заданий по одному, так и
для массовой отмены/удаления заданий.
Старые задачи и их результаты хранятся на сервере не более 90 дней. По истечении этого срока
задачи и их результаты автоматически удаляются.
Обработка ошибок сервиса
В случае возникновения ошибки в процессе выполнения команды сервиса вместо штатного xml
возвращается xml ошибки следующего вида:
<Error>
<ErrType>UNKNOWN</ErrType>
<Message>
EXCEPTION: Пробное исключение INNER EXCEPTION: Пробное вложенное исключение
</Message>
</Error>
В процессе выполнения сервисом команд возникают ошибки, зачастую обусловленные
некорректными параметрами команд. Для автоматизации обработки таких ошибок наиболее
частые ошибки типизированы. Сервис распознает тип ошибки и добавляет в xml сообщения об
ошибке строковый тип ошибки (ErrType).
Возможные значения типа ошибки:
UNKNOWN – неизвестный тип ошибки
WRONG_METHOD – попытка вызова несуществующего метода http-сервиса
WRONG_INTERVAL – неверный временной интервал (команды task_add и run_custom_report)
USER_CANCELLATION – задание отменено пользователем
REPORT_TEMPLATE_UNKNOWN – неизвестный шаблон отчета (команда task_add)
Служба уведомлений об изменении данных
На сервере Пандоры работает служба, отправляющая подписанным клиентам сообщения об
обновлениях/изменениях в данных. См. документ Notification_service.docx в разделе
«документация» сайта Пандоры.