Регламент обмена данными между информационными системами

Редакция 1.2 от 15.11.2007
Регламент обмена данными между информационными
системами
1. Общее описание процесса обмена данными
Данный регламент описывает механизм информационного обмена и формат
передаваемых и получаемых данных. В рамках проекта «Информатизация системы
образования» данный регламент реализован для обмена данными между
информационными системами администрирования деятельности образовательного
учреждения «1C:ХроноГраф Школа 2.5» (Система администрирования учреждения) и
организации и поддержки образовательного процесса «1С: Образование 4. Школа»
(Система организации процесса).
Регламент определяет формат обмена следующего набора данных:
из «Система администрирования учреждения» в «Систему организации процесса»
передаются:
 Общая
информация об учебном заведении;
 Информация
об учебном(ых) периоде(ах);
 Список
предметов в учебном заведении;
 Список
классов/групп учебного заведения;
 Список
преподавательского состава и учащихся с информацией распределения
по классам/группам;
 Список
журнальных страниц;
из «Системы организации процесса» в «Систему администрирования учреждения»
передаются:
 Список
тем уроков, сформированных в журнальных страницах в учебном
процессе;
 Список
проставленных оценок.
Передача и получение данных осуществляется (инициируется) «Системой
администрирования учреждения» посредством вызова программной утилиты
«Обработчик обмена данных» (Обработчика). Обмен данными осуществляется при
помощи xml-файлов, формат которых определяется данным регламентом ниже (пункты 35). При вызове «Обработчика» «Системой администрирования учреждения» в параметрах
вызова (в командной сороке) передаются два обязательных параметра: путь к xml-файлу
(command.xml), в котором описана операция, которую должен выполнить Обработчик и
путь к xml-файлу (result.xml), куда должны быть записаны результаты операции (см.
1
пункт «Вызов «Обработчика обмена данных» и описание общей части предаваемых и
возвращаемых данных»).
Для передачи первоначальной информации об «Обработчике» (название Обработчика,
путь, где находится Обработчик и с какими параметрами он должен быть вызван)
необходимо осуществить регистрацию Обработчика в «Системе администрирования
учреждения».
2. Регистрация «Обработчика обмена данных» в «Системе администрирования
учреждения»
Регистрация «Обработчика обмена данных» в «Системе администрирования учреждения»
осуществляется загрузкой средствами «Системы администрирования учреждения» файла
handler.xml, содержащего описание «Обработчика обмена данных». Файл handler.xml
должен поставляться вместе с «Системой организации процесса». Операция регистрации
«Обработчика обмена данных» должна быть произведена однократно после установки
«Системы организации процесса».
Формат xml-файла с описанием регистрационных параметров «Обработчика обмена
данных» (handler.xml)
<?xml version="1.0" encoding="windows-1251"?>
<product version=”Номер версии формата. Версия нужна, что бы можно было
отличить от предыдущей версии (значение=2)”>
<id>уникальный идентификатор продукта</id>
<title>наименование продукта</title>
<!— Список авторских прав -->
<copyright>авторское право 1</copyright>
...........
<copyright>авторское право N</copyright>
<!— Список названий издательств -->
<publisher>название издательства 1</publisher>
...........
<publisher>название издательства N</publisher>
<!-- дата издания -->
<date>дата издания</date>
<!-- описание обработчика -->
<userhandler uuid="идентификатор" name="название обработчика">
<description>описание обработчика</description>
<application>
<executable version="версия исполняемого файла">
<registry key="ключ реестра" value="значение"/>
или
<path value="Путь к исполняемому файлу"/>
</executable>
<params>
<!-- Предопределенный параметр. Имя файла, в который
осуществлена выгрузка данных для передачи в Систему и описание
операции синхронизации. См. пункт 3.1. -->
<param value='-D:"${input_filename}"'/>
2
<!-- Предопределенный параметр. Имя файла, в который будут
записаны данные Системой. См. пункт 3.2. -->
<param value='-R:"${result_filename}"'/>
</params>
</application>
</userhandler>
</product>
Замечания:
1. В приведенных ниже описаниях курсивом помечены фрагменты, которые
будут заменены на фактические данные.
2. В описании элемента <userhandler> в параметрах, передаваемых при запуске,
используется следующая конструкция: "${имя параметра}".
Например: <param value=’-D:”${input_filename}”’/>
В этом случае при вызове обработчика строка "${имя параметра}" должна быть
заменена на значение параметра.
Например: <param value=’-D:” C:\SchoolDemo\UsersTemp.xml”’/>
3. В пути к исполняемым файлам может быть использована конструкция
"%переменная окружения операционной системы%". При вызове она должна
быть заменена на реальное значение переменной окружения операционной
системы (так, если при задании пути к исполняемому файлу присутствует строка
"%SystemDrive%", она должна быть заменена на название системного диска,
например "С:").
5. В качестве идентификаторов объектов используются глобальные
идентификаторы (GUID).
6. Даты прописываются в виде YYYY-MM-DD.
Пример файла (handler.xml)
<?xml version="1.0" encoding="windows-1251" ?>
<product version=”2”>
<id>1CE4_System</id>
<title>Система организации и поддержки образовательного процесса</title>
<copyright>ЗАО "1С", 2006-2007</copyright>
<date>2007</date>
<publisher>ЗАО "1С"</publisher>
<userhandler
uuid="D79A28B6-F5ED-4FE0-9C97-FA252BD33D9B"
name="Система организации и поддержки образовательного процесса">
<description>
Система организации и поддержки образовательного процесса
</description>
<application>
<executable version="4.00.014">
<registry key="HKEY_LOCAL_MACHINE\SOFTWARE\1C\1C
Education\Products\1CE4\Applications\1CEduWeb"
value="UserImporter" />
</executable>
3
<params>
<param value='-D:"${input_filename}"' />
<param value='-R:"${result_filename}"' />
<param value="-l:sa" />
<param value="-p:" />
</params>
</application>
</userhandler>
</product>
3. Вызов «Обработчика обмена данных» и описание общей части предаваемых и
возвращаемых данных
После регистрации «Обработчика» из «Системы администрирования учреждения» могут
осуществляться запросы на выполнение определенных операций (команд). При этом
вызывается исполняемый файл, описанный в userhandler с передачей 2-х обязательных
параметров:
1. Путь к файлу, в который осуществлена выгрузка данных для передачи в «Систему
организации процесса» с указанием самой операции, которую надо проделать (см.
command.xml)
2. Путь к файлу, который будет создан «Системой организации процесса», и в
который будут записаны результаты запрашиваемой операции (см. result.xml)
3.1. Описание xml-формата, формируемого «Системой администрирования учреждения»
(command.xml)
<?xml version="1.0" encoding="windows-1251" ?>
<!-- command - корневой элемент запроса на выполнение операции -->
<command>
<!-- name - название операции
может принимать значения “ImportData” и “ExportData”) -->
<name>Название операции</name>
<!-- parameters - параметры, передаваемые для данной операции -->
<parameters>
<!-- param - параметр операции. Элементов param может быть
от 0 до N в зависимости от операции
param/@name - название параметра -->
<param name="название параметра">
<!--различные данные, (списки пользователей, групп, оценок и
пр.), структура зависит от конкретной операции -->
</param>
<param name="...">
...
</param>
...
</parameters>
</command>
4
3.2. Описание xml-формата, получаемого «Системой администрирования учреждения»
(result.xml)
<?xml version="1.0" encoding="windows-1251" ?>
<!-- result - корневой элемент результатов запрашиваемой операции -->
<result>
<!-- status - статус запрашиваемой операции -->
<status>
<!-- success - указывает на успешность операции. Может иметь
значения true или false
success=true - запрашиваемая операция прошла успешно. Если
при этом требуется вернуть какие-либо данные, то они будут
записаны в элементе "data", в противном случае элемент
"data" отсутствует
success=false - произошла ошибка. Описание ошибки см. в
элементе errordescription -->
<success>true|false</success>
<!-- errordescription - описание ошибки. Присутствует в том
случае, если при выполнении запрашиваемой операции произошла
ошибка (success=false)
short - краткое описание ошибки, которое будет показано
пользователю
detailed - более развернутое описание ошибки
-->
<errordescription>
<short>Краткое описание ошибки</short>
<detailed>Развернутое описание ошибки</detailed>
</errordescription>
</status>
<!-- data - данные, которые возвращаются -->
<data>
<!-- структура зависит от конкретной операции -->
</data>
</result>
4. Запрос на выполнение операции загрузки начальных данных из «Системы
администрирования учреждения» в «Систему организации процесса»
4.1. XML-формат передаваемого файла:
<?xml version="1.0" encoding="windows-1251" ?>
<command>
<!-- Название операции (в данном случае ImportData) -->
<name>ImportData</name>
<parameters>
<!-- Информация об образовательном учреждении -->
5
<param name="SchoolInfo">
<id>Идентификатор экземпляра приложения,
из которого выгружены данные</id>
<name>Название образовательного учреждения</name>
<city>Город, в котором находится учреждение</city>
<email>Адрес эл.почты (если есть)</email>
</param>
<!-- Список учебных периодов -->
<param name="TermList">
<!-- описание учебного года/периода. Атрибут isactive="true"
проставляется только у того периода, за который
осуществляется выгрузка -->
<term id=”Идентификатор учебного периода (года)”
name=”Название учебного года”
isactive = "true|false"
date_start=”Дата начала периода”
date_end=”Дата окончания периода”>
<term id=”Идентификатор учебного периода”
name=”Название учебного периода”
isactive = "true|false"
date_start=”Дата начала периода”
date_end=”Дата окончания периода”/>
...
</term>
</param>
<!-- Список предметов -->
<param name="SubjectList">
<!-- описание предмета -->
<subject id=”Идентификатор предмета”
name=”Название предмета” />
...
</param>
<!-- Список классов, подгрупп и групп второй половины дня -->
<param name="GroupList">
<!-- описание класса -->
<class id=”Идентификатор класса”
name=”Название класса”
parallel=”Номер параллели”/>
...
<!-- описание группы в классе -->
<subgroup id=”Идентификатор подгруппы ”
name=”Название подгруппы”
class_id=”Идентификатор класса”/>
...
<!-- описание групп второй половины дня -->
6
<group id=”Идентификатор группы”
name=”Название группы” />
...
</param>
<!-- Список пользователей -->
<param name="UserList">
<user id="идентификатор пользователя"
name="имя пользователя"
login="логин"
password="пароль"
firstname="имя"
secondname="отчество"
surname="фамилия"
birthdate="дата рождения"
gender="пол (Ж/М)"
personal_file_num="номер личного дела (строка)">
<!-- role – роль пользователя в Системе.
Может принимать значения: "Учащийся",
"Преподаватель" или "Администратор" -->
<role>роль пользователя</role>
<!-- subject - предметы, которые ведет пользователь
(заполняется только для пользователей с правами
"Учитель" или "Администратор") -->
<subject>Название предмета</subject>
...
<!-- Период нахождения учащегося в учебном заведении -->
<presence_period
date_start=”Дата начала периода”
date_end=”Дата окончания периода”
comment="Дополнительная информация"/>
<!-- Период отсутствия учащегося. Параметры lesson_start,
lesson_end, comment – необязательные.
В случае отсутствия lesson_start - учащийся освобожден
со своего первого урока на дне, в случае отсутствия
lesson_end - до своего последнего урока на дне. -->
<absence_period
date_start="Дата начала периода"
date_end="Дата окончания периода"
lesson_start="Номер урока, с которого
учащийся отпущен"
lesson_end="Номер урока, до которого
учащийся отпущен"
comment="Дополнительная информация"/>
...
7
<!-- у пользователей с ролью "Ученик" указываются
классы/группы, в которые они зачислены. У
пользователей с ролью "Учитель" или "Администратор"
- классы, в которых они ведут классное руководство
Пользователь не может быть включен в подгруппу, если
он не включен в класс, в котором находится данная
подгруппа.
-->
<class id=”Идентификатор класса, подгруппы или ГВПД”>
<!-- Период нахождения учащегося в конкретном
классе/группе.
В случае совпадения с периодом, к которому
прикреплен класс/группа - параметр отсутствует
Если период описан для класса, то данный период
распространяется и на все подгруппы, входящие в
класс
-->
<presence_period
date_start="Дата начала периода"
date_end="Дата окончания периода"
comment="Дополнительная информация"/>
...
<!-- Указание периодов присутствия или освобождения
пользователя по конкретному предмету (журнальной
странице). Если период присутствия совпадает с
периодом присутствия в классе, данный элемент не
прописывается -->
<journal id=”Идентификатор журнальной страницы”>
<!-- Период нахождения учащегося на журнальной
странице, в случае совпадения с периодом, к
которому прикреплена страница, отсутствует -->
<presence_period
date_start="Дата начала периода"
date_end="Дата окончания периода"
comment="Дополнительная информация"/>
...
<!-- Период освобождения -->
<absence_period
date_start="Дата начала периода"
date_end="Дата окончания периода"
comment="Дополнительная информация"/>
...
</journal>
</class>
...
</user>
</param>
8
<!-- Список журнальных страниц
<param name="JournalList">
-->
<!-- описание журнальной страницы. Здесь описаны идентификаторы
сущностей, определяющих журнальную страницу (Учебный
период, Предмет, Класс, Преподаватель) -->
<journal id=”Идентификатор журнальной страницы”
term_id=”Идентификатор учебного периода”
class_id=”Идентификатор класса или подгруппа”
subject_id=”Идентификатор предмета”
tutor_id=”Идентификатор преподавателя”/>
...
</param>
</parameters>
</command>
4.2. XML-формат получаемого обратно файла:
В случае успешного завершения операции:
<result>
<status>
<success>true</success>
</status>
<!-- Блок data отсутствует, т.к. возвращаемых данных нет -->
</result>
В случае ошибки:
<result>
<status>
<success>false</success>
<errordescription>
<short>Краткое описание ошибки</short>
<detailed>Развернутое описание ошибки</detailed>
</errordescription>
</status>
</result>
5. Запрос на выполнение операции получения оценок журнальных страниц
5.1. XML-формат передаваемого файла:
<?xml version="1.0" encoding="windows-1251" ?>
<command>
<!-- Название операции -->
<name>ExportData</name>
<parameters>
<!-- Учебный период, за который надо выгрузить оценки -->
<param name="Term">
<term id=”Идентификатор учебного периода” />
</param>
9
</parameters>
</command>
5.2. XML-формат получаемого обратно файла:
В случае успешного завершения операции:
<?xml version="1.0" encoding="windows-1251" ?>
<result>
<status>
<success>true</success>
</status>
<!-- data - данные, которые возвращаются -->
<data>
<journal id=”Идентификатор журнальной страницы”>
<task id=”Идентификатор темы (урока)”
name=”Название темы (урока)”
date=”Дата темы (урока)”
type=”Тип колонки ("урок", "контрольная",
"окончание_периода", "годовая", "экзамен",
"итоговая " и пр.)”>
<mark userId=”Идентификатор пользователя”
value=”Оценка по 5-тибальной шкале, либо пустая
строка, если оценка не проставлена, но заполнен
атрибут status”
status=”Статус ячейки (“был”, “не_был”, “болел”,
“опоздал”, “н_а”, “н_в”, “освобожден”)”>
...
</task>
...
</journal>
...
</data>
</result>
В случае ошибки:
<result>
<status>
<success>false</success>
<errordescription>
<short>Краткое описание ошибки</short>
<detailed>Развернутое описание ошибки</detailed>
</errordescription>
</status>
</result>
10