Работа с Microsoft Exchange Web Services
методы для работы с MS EWS
iRidi Server предоставляет возможности для взаимодействия с существующими корпоративными системами, построенными на базе Microsoft Exchange Server — программном продукте для обмена почтовыми сообщениями и совместной работы с календарем и задачам. Можно подключить iRidium server к системе Microsoft Exchange через Exchange Web Services API для:
- получения событий в календаре
- получение контактов
- создания встреч
- удаления элементов
Работа с MS EWS доступна только через скрипт.
Драйвер поддерживает Basic Authentication и NTLM.
- Во всех методах, имеющих параметры даты и времени, дата и время может задаваться в трёх разных форматах "2016-09-16T07:00:000**+05:00** " - формат указанного часового пояса. Время считается с поправкой между часовым поясом сайта и указанным часовым поясом
"2016-09-16T07:00:000Z " - Время считается как UTC+0 + часовой пояс сайта
"2016-09-16T07:00:000" - Предпочтительный формат. При наличии параметра Timezone у драйвера время считается с поправкой между часовым поясом сайта и часовым поясом драйвера (пользователя)
Методы
IR.CreateDevice()
Создание драйвера для работы с сервером Microsoft Exchange
Синтаксис:
IR.CreateDevice(IR.DEVICE_EWS, name, host, port, login, domain, password, AuthType, Timezone, SSL);
| На входе | Значение | Описание |
|---|---|---|
| name | "EwsDriver" | type: string Имя создаваемого драйвера |
| host | "192.168.0.12" | type: string IP адрес сервера Microsoft Exchange |
| port | 443 | type: number Порт, по умолчанию 80 |
| login | "admin" | type: string Логин от учетной записи Microsoft Exchange |
| domain | "company.local" | type: string Домен учетной записи Microsoft Exchange |
| password | "admin" | type: string Пароль от учетной записи Microsoft Exchange |
| AuthType | "IR.HTTP_NTLM_AUTH" | type: string Тип авторизации: IR.HTTP_BASIC_AUTH, IR.HTTP_DIGEST_AUTH, IR.HTTP_NTLM_AUTH |
| Timezone | 500 | type: number Часовой пояс. Смещение времени драйвера (пользователя) относительно UTC |
| SSL | 0 | type: number Метод шифрования сообщений между iRidium server и Microsoft Exchange Server: 0 - без шифрования (по умолчанию), 1 - TLS v1.2 (рекомендуется), 2 - SSL 2.3, 3 - SSL 3.0 |
| на выходе | - | - |
| - | - | - |
Пример
var device = IR.CreateDevice(IR.DEVICE_EWS, "EwsDriver", "192.168.0.12",
443, "admin", "iridi.local", "admin", IR.HTTP_NTLM_AUTH, 500,0);
IR.Log(device); // [object DevicePrototype]
В случае неуспешной попытки подключения к серверу Microsoft Exchange драйвер будет повторять попытки каждые 15 секунд.
.GetCalendar()
Получение событий календаря
Синтаксис:
.GetCalendar({FirstDate, LastDate, Email, Callback, UpdateTime});
| На входе | Значение | Описание |
|---|---|---|
| FirstDate | "2016-09-16T07:00:000" | type: string Дата и время начала события |
| LastDate | "2016-11-16T07:00:000" | type: string Дата и время окончания события |
| "admin@mycompany.ru" | type: string Адрес электронной почты, к которому привязано событие. Необязательный параметр для получения календаря текущего пользователя | |
| Callback | function(eventList, email) | type: function Функция, в которую сервер передаст список событий |
| UpdateTime | 0 | type: number Частота опроса сервера (мс.) 0 = единичный неповторяющийся запрос |
| на выходе | ||
| eventList | ID: "AAMkA", ChangeKey: "DwAAAB", Start: "2016-09-16T07:00:000", End: "2016-11-16T07:00:000", Subject: "IT Conference", Organizer: "K. Johnson", Room: "London" | type: object Список событий. Каждое событие имеет поля: ID (идентификатор элемента), ChangeKey (ключ элемента), Start (начало события), End (конец события), Subject (название встречи), Organizer (организатор), Room (место проведения) |
- Не задавайте малую частоту опроса (UpdateTime) сервера MS Exchange для экономии вычислительных ресурсов. Рекомендуемая частота опроса от 5 минут (300000 мс)
- Каждый отдельный вызов метода .GetCalendar() запускает новый цикл обновления согласно частоте опроса (UpdateTime) не останавливая предыдущие
Пример
function GetFirstEventData(eventList, email)
{
IR.Log("event id: " + eventList.items[0].ID);
IR.Log("event key: " + eventList.items[0].ChangeKey);
IR.Log("event start: " + eventList.items[0].Start);
IR.Log("event end: " + eventList.items[0].End);
IR.Log("event subject: " + eventList.items[0].Subject);
IR.Log("event organizer: " + eventList.items[0].Organizer);
IR.Log("event Room: " + eventList.items[0].Room);
}
device.GetCalendar({
FirstDate: "2016-09-16T07:00:000",
LastDate: "2016-09-20T07:00:000",
Email: "admin@admin.ru",
UpdateTime: 300000,
Callback: GetFirstEventData,
});
.GetContact()
Получение информации о контакте
Синтаксис:
.GetContact({Find, Callback});
| На входе | Значение | Описание |
|---|---|---|
| Find | "admin" | type: string Поисковая строка (часть имени или электронной почты) |
| Callback | function(contactList, find) | type: function Функция, в которую сервер передаёт список контактов |
| на выходе | ||
| contactList | Name: "L. Johnson", Company: "Iridium Ltd.", Email: "admin@admin.ru", Fax: "3435111222", BusinessPhone: "3435333222", Phone: "3435222333", MobilePhone: "+79001111111", Department: "R&D", Office: "General str. 1", JobTitle: "Trainer" | type: object Список контактов, которые подходят под поисковую строку. Каждый контакт имеет поля: Name (имя контакта), Company (компания), Email (почтовый адрес контакта), Fax (факс контакта), BusinessPhone (рабочий телефон), Phone (телефон), MobilePhone (мобильный телефон), Department (отдел), Office (адрес офиса), JobTitle (должность) |
| find | "admin" | type: string Поисковая строка |
Пример
function GetFirstContactData(contactList, find)
{
IR.Log("Contact Name: " + contactList.Items[0].Name);
IR.Log("Contact Company: " + contactList.Items[0].Company);
IR.Log("Contact Email: " + contactList.Items[0].Email);
IR.Log("Contact Fax: " + contactList.Items[0].Fax);
IR.Log("Contact BusinessPhone: " + contactList.Items[0].BusinessPhone);
IR.Log("Contact Phone: " + contactList.Items[0].Phone);
IR.Log("Contact MobilePhone: " + contactList.Items[0].MobilePhone);
IR.Log("Contact Department: " + contactList.Items[0].Department);
IR.Log("Contact Office: " + contactList.Items[0].Office);
IR.Log("Contact JobTitle: " + contactList.Items[0].JobTitle);
}
device.GetContact({Find: "admin", Callback: GetFirstContactData});
.CreateAppointment()
Создание встречи
Синтаксис:
.CreateAppointment({FirstDate, LastDate, Room, Subject, Callback});
| На входе | Значение | Описание |
|---|---|---|
| FirstDate | "2016-09-16T07:00:000" | type: string Дата и время начала события |
| LastDate | "2016-09-20T07:00:000" | type: string Дата и время окончания события |
| Room | "526" | type: string Комната, в которой будет проходить встреча |
| Subject | "Scrum meeting" | type: string Тема встречи |
| Callback | function(appointment) | type: function Функция, которая возвращает ответ от сервера |
| на выходе | ||
| appointment | ID: "AAMkA", ChangeKey: "DwAAAB" | type: object Объект, в котором хранится информация о созданной встрече: ID (идентификатор встречи), ChangeKey (ключ созданной встречи), Error (текст ошибки, если она есть) |
Пример
function FeedbackInfo(appointment)
{
IR.Log("ID: " + appointment.ID);
IR.Log("ChangeKey: " + appointment.ChangeKey);
IR.Log("Error: " + appointment.Error);
}
device.CreateAppointment({
FirstDate: "2016-09-16T07:00:000",
LastDate: "2016-09-20T07:00:000",
Room: "526",
Subject: "Scrum meeting",
Callback: FeedbackInfo});
.CancelAppointment()
Удаление элемента
Синтаксис:
.CancelAppointment({ID, ChangeKey, Callback});
| На входе | Значение | Описание |
|---|---|---|
| ID | "AAMkA" | type: string Идентификатор элемента |
| ChangeKey | "DwAAAB" | type: string Ключ элемента |
| Callback | function(itemStatus) | type: function Функция, которая вернёт ответ от сервера |
| на выходе | ||
| itemStatus | {Deleted: true} или {Error: "ResponseCode: ErrorNameResolutionNoResults, MessageText: No results were found."} | type: object Объект, в котором хранится информация об удалённом элементе: Deleted (флаг удаления), Error (текст ошибки, если она есть) |
Пример
function DeletingFeedback(itemStatus){
if (itemStatus.Deleted)
{
IR.Log("Deleted!");
}
else
{
IR.Log("Error: " + itemStatus.Error);
}
}
device.CancelAppointment({ID: "AAMkA", ChangeKey: "DwAAAB", Callback: DeletingFeedback});
.SendMail()
Отправка письма
Синтаксис:
.SendMail ({Email, Subject, Body, Callback});
| на входе | значение | описание |
|---|---|---|
| "admin@mycompany.ru" | type: string адрес электронной почты получателя | |
| Subject | "Subject" | type: string Тема письма |
| Body | "Message" | type: string Текст письма |
| Callback | function(SendingFeedback) | type: function функция, которая возвращает ответ от сервера |
| на выходе | ||
| MessageStatus | Sent: true | type: object Объект, в котором хранится информация об отправленном письме: Sent (флаг отправления) |
Пример
function SendingFeedback (MessageStatus)
{
IR.Log("Sent: " + MessageStatus.Sent);
}
device.SendMail({
Email: 'admin@admin.ru',
Subject: 'Subject',
Body: 'Message',
Callback: SendingFeedback });
.CreateMeeting()
Создание встречи (meeting) на несколько пользователей.
Синтаксис:
device.CreateMeeting({Email, EmailAttendees, FirstDate, LastDate, Room, Subject, Callback});
| на входе | значение | описание |
|---|---|---|
| EmailAttendees | ["user1@admin.ru", "user2@admin.ru", "user3@admin.ru"] | type: string адреса электронной почты приглашенных участников. Перечисление в массиве через символ , |
| FirstDate | "2016-09-16T07:00:000" | type: string дата и время начала события |
| LastDate | "2016-11-16T07:00:000" | type: string дата и время окончания события |
| Room | "526" / "room@admin.ru" | type: string Комната, в которой будет проходить встреча |
| Subject | "Scrum meeting" | type: string Тема встречи |
| Callback | function(Meeting) | type: function функция, которая возвращает ответ от сервера |
| на выходе | ||
| Meeting | {ID: "AAMkA",ChangeKey: "DwAAAB"} | type: object объект, в котором хранится информация о созданной встрече: ID (идентификатор встречи), ChangeKey (ключ созданной встречи), Error (текст ошибки, если она есть) |
- Room необходимо добавить и как приглашенного участника, чтобы отправлялись оповещения о занятости комнаты
- Параметры FirstDate и LastDate отображаются и конвертируются согласно установленному часовому поясу пользователя если заданы в формате "2016-11-16T07:00:000". Настроить часовой пояс можно в настройках:
Параметры учётной записи > Общие > Регион и часовой пояс
Пример
device.CreateMeeting({
EmailAttendees: ['user1@admin.ru, user2@admin.ru, user3@admin.ru']
FirstDate: '2016-09-16T07:00:000',
LastDate: '2016-11-16T07:00:000',
Room: 'room@admin.ru',
Subject: "Scrum meeting",
Callback: Meeting
});
.CancelMeeting()
Удаление/отмена встречи (meeting) с уведомлением всех пользователей.
Отменённое событие удаляется из календаря организатора. В календаре участника остаётся запись об отменённом событии.
Синтаксис:
device.CancelMeeting({ID, ChangeKey, Message, Callback});
| на входе | значение | описание |
|---|---|---|
| ID | "AAMkA" | type: string идентификатор элемента |
| ChangeKey | "DwAAAB" | type: string ключ элемента |
| Message | "Canceled by i3 Pro" | type: string Текст сообщения участникам об отмене встречи |
| Callback | function(Meeting) | type: function функция, которая вернёт ответ от сервера |
| на выходе | ||
| Meeting | {Deleted: true} или{Error: "ResponseCode: ErrorNameResolutionNoResults, MessageText: No results were found."} | type: object объект, в котором хранится информация об удалённом элементе: Deleted (флаг удаления), Error (текст ошибки, если она есть) |
- Важно - Для корректного удаления/отмены встречи необходимы и ID и ChangeKey.
Пример
device.CancelMeeting({
ID: 'AAMkA',
ChangeKey: 'DwAAAB',
Message: 'Canceled by i3 Pro',
Callback: function(Meeting)
});
.UpdateMeeting()
Обновление существующей встречи (Meeting) – возможно изменение только времени начала и времени окончания.
Синтаксис:
device.UpdateMeeting({ ID, ChangeKey, FirstDate, LastDate, Callback});
| на входе | значение | описание |
|---|---|---|
| ID | "AAMkA" | type: string идентификатор элемента |
| ChangeKey | "DwAAAB" | type: string ключ элемента |
| FirstDate | "2016-09-16T07:00:000" | type: string дата и время начала события |
| LastDate | "2016-11-16T07:00:000" | type: string дата и время окончания события |
| Callback | function(Appointment) | type: function функция, которая вернёт ответ от сервера |
| на выходе | ||
| Appointment | {ID: "AAMkA",ChangeKey: "DwAAAB"} | type: object объект, в котором хранится информация о созданной встрече: ID (идентификатор встречи), ChangeKey (ключ созданной встречи), Error (текст ошибки, если она есть) |
Пример
device.UpdateMeeting({
ID: 'AAMkA',
ChangeKey: 'DwAAAB',
FirstDate: '2016-09-16T07:00:000',
LastDate: '2016-11-16T07:00:000',
Callback: Appointment
});
.UpdateAppointment()
Обновление существующего события (Appointment) – возможно изменение только времени начала и времени окончания.
Синтаксис:
device.UpdateAppointment({ID, ChangeKey, FirstDate, LastDate, Callback});
| на входе | значение | описание |
|---|---|---|
| ID | "AAMkA" | type: string идентификатор элемента |
| ChangeKey | "DwAAAB" | type: string ключ элемента |
| FirstDate | "2016-09-16T07:00:000" | type: string дата и время начала события |
| LastDate | "2016-11-16T07:00:000" | type: string дата и время окончания события |
| Callback | function(Appointment) | type: function функция, которая вернёт ответ от сервера |
| на выходе | ||
| Appointment | {ID: "AAMkA",ChangeKey: "DwAAAB"} | type: object объект, в котором хранится информация о созданной встрече: ID (идентификатор встречи), ChangeKey (ключ созданной встречи), Error (текст ошибки, если она есть) |
Пример
device.UpdateAppointment({
ID: 'AAMkA',
ChangeKey: 'DwAAAB',
FirstDate: '2016-09-16T07:00:000',
LastDate: '2016-11-16T07:00:000',
Callback: Appointment
});