orig-crc32 Оригинальный CRC32 файла. for-export Разрешен экспорт данного файла. export-doc-filename Служебное, автоматически генерируемое, имя файла

Realty-Robot
Версия 6.81.86

Руководство поЛЬЗОВАТЕЛЯ

Ревизия руководства: 6





13 TOC \o "1-3" \h \z \u 1413 LINK \l "_Toc492931417" 141. Назначение и основные характеристики 13 PAGEREF _Toc492931417 \h 1421515
13 LINK \l "_Toc492931418" 142. Установка и подготовка к работе 13 PAGEREF _Toc492931418 \h 1421515
13 LINK \l "_Toc492931419" 143. Совместимость с другим программным обеспечением 13 PAGEREF _Toc492931419 \h 1431515
13 LINK \l "_Toc492931420" 144. Файл настроек Realty-Robot.xml 13 PAGEREF _Toc492931420 \h 1451515
13 LINK \l "_Toc492931421" 145. Сценарии и задачи 13 PAGEREF _Toc492931421 \h 1481515
13 LINK \l "_Toc492931422" 146. Сценарии 13 PAGEREF _Toc492931422 \h 1491515
13 LINK \l "_Toc492931423" 146.1. Файл-индикатор готовности 13 PAGEREF _Toc492931423 \h 1491515
13 LINK \l "_Toc492931424" 146.2. Общие настройки сценариев 13 PAGEREF _Toc492931424 \h 1491515
13 LINK \l "_Toc492931425" 146.3. Сценарий экспорта 13 PAGEREF _Toc492931425 \h 14131515
13 LINK \l "_Toc492931426" 146.3.1. Настройки 13 PAGEREF _Toc492931426 \h 14131515
13 LINK \l "_Toc492931427" 146.3.2. Алгоритм 13 PAGEREF _Toc492931427 \h 14171515
13 LINK \l "_Toc492931428" 146.3.3. Формат Realty-Robot 13 PAGEREF _Toc492931428 \h 14181515
13 LINK \l "_Toc492931429" 146.4. Сценарий экспорта 13 PAGEREF _Toc492931429 \h 14211515
13 LINK \l "_Toc492931430" 146.5. Сценарий импорта 13 PAGEREF _Toc492931430 \h 14221515
13 LINK \l "_Toc492931431" 146.5.1. Настройки 13 PAGEREF _Toc492931431 \h 14221515
13 LINK \l "_Toc492931432" 146.5.2. Алгоритм 13 PAGEREF _Toc492931432 \h 14251515
13 LINK \l "_Toc492931433" 146.6. Сценарии копирования между локальным каталогом и FTP-каталогом 13 PAGEREF _Toc492931433 \h 14251515
13 LINK \l "_Toc492931434" 146.6.1. Общие настройки сценариев и 13 PAGEREF _Toc492931434 \h 14251515
13 LINK \l "_Toc492931435" 146.6.2. Алгоритм сценария 13 PAGEREF _Toc492931435 \h 14271515
13 LINK \l "_Toc492931436" 146.6.3. Алгоритм сценария 13 PAGEREF _Toc492931436 \h 14271515
13 LINK \l "_Toc492931437" 146.7. Сценарий выполнения внешней программы 13 PAGEREF _Toc492931437 \h 14281515
13 LINK \l "_Toc492931438" 146.8. Составной сценарий 13 PAGEREF _Toc492931438 \h 14291515
13 LINK \l "_Toc492931439" 146.9. Заказные сценарии 13 PAGEREF _Toc492931439 \h 14291515
13 LINK \l "_Toc492931440" 147. Шаблоны сценариев в Realty-Robot.xml 13 PAGEREF _Toc492931440 \h 14301515
13 LINK \l "_Toc492931441" 148. Рекомендации по разработке сценариев для распространенных ситуаций 13 PAGEREF _Toc492931441 \h 14311515
13 LINK \l "_Toc492931442" 148.1. Ситуация: анонимный импорт из xls-файла 13 PAGEREF _Toc492931442 \h 14311515
13 LINK \l "_Toc492931443" 148.2. Ситуация: обмен данными с компаниями-партнерами 13 PAGEREF _Toc492931443 \h 14321515
13 LINK \l "_Toc492931444" 148.3. Ситуация: обмен данными между главным офисом компании и филиалами 13 PAGEREF _Toc492931444 \h 14321515
13 LINK \l "_Toc492931445" 149. Рекомендуемый алгоритм работы скрипта импорта на сайте 13 PAGEREF _Toc492931445 \h 14331515
13 LINK \l "_Toc492931446" 1410. Работа с Realty-Robot 13 PAGEREF _Toc492931446 \h 14341515
13 LINK \l "_Toc492931447" 1411. Протоколирование действий Realty-Robot 13 PAGEREF _Toc492931447 \h 14351515
13 LINK \l "_Toc492931448" 1411.1. Протокол задач 13 PAGEREF _Toc492931448 \h 14351515
13 LINK \l "_Toc492931449" 1411.2. Системный протокол 13 PAGEREF _Toc492931449 \h 14351515
15



Назначение и основные характеристики

Программа Realty-Robot (исполняемый файл Realty-Robot.exe) предназначена для выполнения в автоматическом режиме различных задач в рамках системы Агентство недвижимости (исполняемый файл Realty.exe) варианта «Люкс».

Основные возможности Realty-Robot:
Выполнение стандартных сценариев:
Сценарий экспорта в формате Realty-Robot
Сценарий экспорта в формате YRL (Yandex Realty Language) для сервиса Яндекс.Недвижимость
Сценарий импорта из формата Realty-Robot
Сценарий копирования из локального каталога в каталог на FTP-сервере
Сценарий копирования из каталога на FTP-сервере в локальный каталог
Сценарий запуска внешних программ.
Составной сценарий, позволяющий задать последовательность запуска других сценариев.
Возможна разработка заказных сценариев.
Способ запуска задач по выполнению сценариев может быть указан как:
По расписанию
Через заданный интервал
Немедленно по запросу пользователя
В главном окне Realty-Robot отображается список задач на текущий день с возможностью установки фильтра по их статусам: Ожидает, Работает, Завершена, Не выполнены условия запуска, Ошибка.

Примечание: Realty-Robot предлагается как универсальная замена всех имевшихся к данному моменту способов обмена данными в системе Агентство недвижимости.
Установка и подготовка к работе

Во время установки системы Агентство недвижимости программы Realty.exe и Realty-Robot.exe по умолчанию копируются в общий каталог:
<Диск>:\Program Files\Realty-Soft.ru\Realty\Realty.exe
<Диск>:\Program Files\Realty-Soft.ru\Realty\Realty-Robot.exe

Ярлыки для запуска Realty.exe и Realty-Robot.exe автоматически помещаются на рабочий стол. После установки необходимо предоставить все права на каталог \Realty-Soft.ru и его подобъекты для пользователя, который будет работать с программой. Один из простых способов удовлетворить это требование – указать в свойствах этих ярлыков возможность запуска от имени администратора: правая кнопка мыши на ярлыке ( Свойства ( Совместимость ( Выполнять эту программу от имени администратора.










Для работы Realty-Robot требуется платформа Microsoft .NET Framework 4.6. В Windows 10 эта платформа уже установлена. Если же компьютер работает под управлением одной из ОС:
Windows Vista с пакетом обновления 2 (SP2) (x86 и x64)
Windows 7 с пакетом обновления 1 (SP1) (x86 и x64)
Windows 8 (x86 и x64)
Windows 8.1 (x86 и x64)
Windows Server 2008 с пакетом обновления 2 (SP2) (x86 и x64)
Windows Server 2008 R2 с пакетом обновления 1 (SP1) (x64)
Windows Server 2012 (x64)
Windows Server 2012 R2 (x64)

и на момент первого запуска Realty-Robot платформа еще не установлена – будет выведено соответствующее сообщение. Платформу можно бесплатно скачать и установить с официального сайта Microsoft по ссылке: [ Cкачайте файл, чтобы посмотреть ссылку ].

Перед началом повседневной (не демонстрационной) работы с Realty-Robot необходимо отредактировать файл настроек Realty-Robot.xml, в т.ч. настроить сценарии в соответствии с требованиями бизнес-процессов компании (см. следующие разделы).
Совместимость с другим программным обеспечением

Если на компьютере установлены Kaspersky Internet Security или Kaspersky Total Security, возможно блокирование с их стороны запросов к FTP-серверам (в процессе работы сценариев копирования на/с FTP). Для разблокировки нужно сделать следующие настройки (на примере KTS 2016):

Настройка:














Дополнительно:



Сеть:

















Контролировать только выбранные порты ( Выбрать:


И отключить контроль активности порта 21.
Файл настроек Realty-Robot.xml

При установке Realty-Robot.exe в один с ним каталог помещается файл настроек Realty-Robot.xml.
Наличие и корректное содержание данного файла являются необходимыми для запуска и работы Realty-Robot.

Пример структуры верхних элементов xml-документа:




true
600<
·
·
·
·
·
·
·
·
·
·
·
·
·
·
·
·
·
·
·
·
·
·
·
·
·
·
·
·
·
·
·
·
·
·
·
·
·
·
·
·
·
·
·
·
·
·
·
·
·
·
·
·
·
·
·
·
·
·
·
·
·
·
·
·
·
·
·
·
·
·
·
·
·
·
·
·
·
·
·
·
·
·
·
·
·
·
·
·
·
·
·
·
·
·
·
·
·
·
·
·
·
·
·
·
·
·
·
·
·
·
·
·
·
·
·
·
·
·
·
·
·
·
·
·
·
·
·
·
·
·
·
·
·
·
·
·
·
·
·
·
·
·
·
·
·
·
·
·
·
·
·
·
·
·
·
·
·
·
·
·
·
·
·
·
·
·
·
·
·
·
·
·
·
·
·
·
·
·
·
·
·
·
·
·
·
·
·
·
·
·
·
·
·
·
·
·
·
·
·
·
·
·
·
·
·
·
·
·
·
·
·
·
·
·
·
·
·
·
·
·
·
·
·
·
·
·
·
·
·>Импорт от Компании А



Экспорт для Компании Б








Элемент содержит настройки приложения Realty-Robot в целом:

Элемент
Комментарий

window-height
Назначение:
Хранят расположение и размеры главного окна Realty-Robot для восстановления при следующем запуске программы.

Тип значения:
Целое

Пример:
600
1200
100
100

При отсутствии:
Создаются автоматически со значениями: 600, 1200, 360, 340 (под монитор Full-HD)

window-width


window-left


window-top


font-family
Назначение:
Семейство шрифта в окнах Realty-Robot

Тип значения:
Строка

Пример:
Arial

При отсутствии:
Считается Arial

font-size
Назначение:
Размер шрифта в окнах Realty-Robot

Тип значения:
Целое

Пример:
16

При отсутствии:
Считается 12

auto-start
Назначение:
Необходимость автозапуска таймера Робота при старте приложения. Если при старте приложения необходимо сразу же запустить таймер Робота для отслеживания времени запуска задач и их запуск в нужное время, необходимо установить значение в true. По умолчанию установлено значение false, т.е. после старта приложения пользователь для запуска таймера Робота должен воспользоваться кнопкой Старт.

Тип значения:
Булево: true, false

Пример:
true

При отсутствии:
Считается false

db-connection-string
Назначение:
Строка подключения к базе данных системы Агентство недвижимости.

Тип значения:
Строка

Пример:

data source=localhost; initial catalog=c:\Program Files\Realty-Soft.ru\Realty\realty7777.fdb;
dialect=3;user id=sysdba;password=masterkey;character set=WIN1251;
pooling=False


При отсутствии:
Realty-Robot будет читать строку подключения из файла Realty.sys, который используется для этой же цели и программой Realty.exe. Такой способ является рекомедуемым, т.к. открытое указание user id и password в строке подключения значительно снижает защищенность базы данных.

log-mode-service
Назначение:
Если установлено значение true – Realty-Robot включает сервисный (очень подробный) режим протоколирования своих действий с сохранением их в лог-файл. Режим может быть полезен для диагностики проблемных ситуаций. Следует учесть, что включение режима несколько замедляет работу Realty-Robot. Подробнее о протоколировании см. в следующих разделах.

Тип значения:
Булево: true, false

Пример:
true

При отсутствии:
Считается false


Элементы сценариев , и др. (имена начинаются с «scenario-») содержат настройки конкретных сценариев и подробно рассматриваются далее.
Сценарии и задачи

Основными объектами, которыми оперирует Realty-Robot, являются сценарии и задачи.
Сценарий – формализованное описание некоторого набора типовых действий. Задача – выполнение сценария с некоторой привязкой ко времени/условиям. Описания сценариев и способы запуска задач хранятся в файле Realty-Robot.xml.

Например, пусть имеется следующий файл Realty-Robot.xml:




false
600
1200
360
340


Импорт из АН Пирамида
interval
600
true
c:\Realty\import\ИмпортИзАНПирамида
c:\Realty\arc
false
true




В этом файле описан некоторый сценарий импорта под именем Импорт из АН Пирамида. Указан интервальный способ запуска с периодичность 600 сек (10 мин). Перед непосредственным импортом заявок в БД все заявки, которые ранее были импортированы в БД от узлов-источников, которые встретятся в импортируемых заявках, удаляются. Полагается, что импортируемые данные уже находятся в локальном каталоге c:\Realty\import\ИмпортИзАНПирамида. По завершении импорта в БД создается их архивная копия в каталоге c:\Realty\arc, а сам локальный каталог очищается.

Таким образом то, что формализовано в элементе , является сценарием. А задачи для импорта по этому сценарию будут динамически создаваться и запускаться роботом каждые 10 минут. Если бы способ запуска был указан как schedule, т.е. по расписанию, то вместо элемента 600 в сценарии должен был присутствовать элемент примерно такого содержания:

10:00
14:00
17:00

т.е. задачи импорта динамически создавались и запускались бы каждые сутки в 10:00, 14:00, 17:00.

Визуальное отображение запланированных на сегодня задач и состояние их выполнения отображаются в главном окне Realty-Robot (см. далее).




Сценарии
Файл-индикатор готовности

Перед дальнейшим рассмотрением сценариев (экспорта, импорта и копирования) необходимо упомянуть о служебном файле-индикаторе готовности, имеющем имя ready.flag. Содержимое файла не важно (Realty-Robot всегда создает его пустым), важно только его наличие/отсутствие. Предназначение файла-индикатора – исключение коллизий совместного доступа разных сценариев/процессов при доступе к одному и тому каталогу: на локальном компьютере или на FTP-сервере .

Основные правила применения файла-индикатора таковы:
Если задача должна записывать в каталог, она может это начать делать, только
если каталог (подкаталоги не имеют значения) пуст. Задача должна максимально быстро
записать в каталог первый файл. После окончания записи самым последним действием
в своей работе задача должна создать в каталоге файл ready.flag, что означает завершенность работы. Маловероятная коллизия может произойти только в случае, когда две стороны проверили каталог на пустоту и одновременно начали записывать в него.
Если задача читает из каталога, она может начать это делать только если в каталоге есть
файл ready.flag. При этом самым первым своим действием задача должна удалить этот флаг, чтобы
никакая другая задача (если таковая может стартовать) также не сочла каталог "готовым" и не начала
производить с ним операции чтения/записи.

Флаги , , , , регулируют, кто из сторон, совместно использующих каталог, берет на себя ответственность за его очистку. Лучшим представляется вариант: кто читает, тот за собой и очищает.

Общие настройки сценариев

Некоторые элементы настройки используются более, чем в одном типе сценария. Во избежание повторного рассмотрения этих элементов в каждом сценарии в следующей таблице они сведены вместе с указанием, в каких сценариях могут быть использованы.

Элемент
Комментарий
Где используется

scenario-name
Назначение:
Имя сценария. Сценариям, описываемым в файле Realty-Robot.xml, во избежание различных коллизий следует назначать различные имена.

Тип значения:
Строка

Пример:
Импорт из АН Пирамида

При отсутствии:
Элемент обязателен.
Во всех сценариях

start-mode
Назначение:
Способ запуска задачи:
schedule: Задачи для данного сценария запускаются в назначенные моменты времени каждые сутки
interval: Задачи для данного сценария запускаются в цикле с интервалом минут
manually: Задачи для данного сценария могут быть запущены только пользователем вручную (в главном окне Realty-Robot кнопка Однократно).

Тип значения:
Перечисление: schedule, interval, manually

Пример:
interval

При отсутствии:
Считается manually
Во всех сценариях

run-schedule
Назначение:
Запуск задач для данного сценария Realty-Robot будет пробовать осуществить в моменты, указанные во вложенных элементах . Принимается во внимание если указано: schedule

Тип значения:
Для подэлементов – время в формате hh:mm

Пример:
Если указано:

10:00
14:00
17:00

то задачи по данному сценарию будут запускаться 3 раза каждые сутки в указанное время. Если в эти моменты времени окажется, что выполняется другая задача, Realty-Robot дождется ее окончания и сразу запустит задачу по данному сценарию.

При отсутствии:
Для schedule элемент обязателен.
Во всех сценариях

run-interval
Назначение:
Периодичность, в секундах, запуска задач для данного сценария. Принимается во внимание если указано: interval

Тип значения:
Целое

Пример:
Если указано:
600
то задачи по данному сценарию будут запускаться каждые 10 минут. Если в эти моменты времени окажется, что выполняется другая задача, Realty-Robot дождется ее окончания и сразу запустит задачу по данному сценарию.

При отсутствии:
Для interval элемент обязателен.
Во всех сценариях

hidden
Назначение:
Сценарий будет доступен для запуска только в составе составного сценария (тип ). В Realty-Robot в списке для запуска сценариев в режиме «Однократно» отображаться не будет.

Тип значения:
Булево: true, false

Пример:
true

При отсутствии:
Считается false
Во всех сценариях

local-dir
Назначение:
Каталог на локальном компьютере или в локальной сети. Для сценариев экспорта: в этот каталог данные будут экспортироваться из БД. Для сценария импорта: из этого каталога данные будут импортироваться в БД. Для сценария копирования на FTP: это каталог-источник. Для сценария копирования с FTP: это каталог-назначение.

Внимание!
Каталог не может быть вложенным в каталог (см. далее)!

Тип значения:
Строка

Пример:
c:\Realty\import-from-555

При отсутствии:
Элемент обязателен
scenario-export
scenario-yandex-export
scenario-import
scenario-copy-to-ftp
scenario-copy-from-ftp

arc-dir
Назначение:
Каталог, в который может помещаться архивная копия экспортируемых или импортируемых данных после завершения задачи. Архивные данные будут располагаться не непосредственно в каталоге , а в автоматически создаваемых его подкаталогах – каждый такой подкаталог предназначается для отдельной задачи и в своем имени содержит название сценария и время запуска задачи.

Внимание!
Каталог не может быть вложенным в каталог !

Тип значения:
Строка

Пример:
c:\Realty\arc
Пример полного имени созданного архивного подкаталога:
c:\Realty\arc\2016.05.26-10.30.00-Импорт из 5555

При отсутствии:
Архивная копия не создается
scenario-export scenario-yandex-export scenario-import

clear-local-dir-before
Назначение:
Управляет очисткой каталога local-dir перед выполнением задачи.

Тип значения:
Булево: true, false

Пример:
false

При отсутствии:
Считается true
scenario-export scenario-yandex-export scenario-copy-from-ftp

clear-local-dir-after
Назначение:
Управляет очисткой каталога local-dir после выполнения задачи

Тип значения:
Булево: true, false

Пример:
false

При отсутствии:
Считается true
scenario-import scenario-copy-to-ftp

Сценарий экспорта

Сценарий экспортирует данные в формате Realty-Robot. Данные в этом формате затем могут быть импортированы сценарием на другом узле.
Настройки

Элемент
Комментарий

include-parameters
Назначение:
Перечень реквизитов описания заявок, которые нужно включить в экспорт. Ситуация, противоположная exclude-parameters. Имеет смысл использовать, когда число включаемых реквизитов меньше числа исключаемых. См. также рекомендации для элемента exclude-parameters.

Пример:

query
action-type
object-type
city
municipal-district
district
street
rows
row
rooms
total-area
comments
node


При отсутствии:
Не учитывается

Внимание:
Одновременное указание в сценарии непустых элементов exclude-parameters и include-parameters является нелогичным и приводит к остановке выполнения сценария.

exclude-parameters
Назначение:
Перечень реквизитов описания заявок, которые нужно исключить из экспорта. Имеет смысл использовать, когда число исключаемых реквизитов меньше числа включаемых.Рекомендации:
Экспорт своему удаленному подразделению или полностью доверенному партнеру: можно не использовать
Экспорт не полностью доверенному партнеру: имеет смысл включить в exclude-parameters те реквизиты, которые являются конфиденциальными (представляют коммерческую ценность)
Экспорт на сайты объявлений: п.2 + те реквизиты, которые сайтом не принимаются

Пример:
Если нужно исключить из экспорта реквизиты «Номер квартиры» и «Себестоимость», необходимо указать:

flat-n
first-cost


При отсутствии:
Не учитывается

Внимание:
Одновременное указание в сценарии непустых элементов exclude-parameters и include-parameters является нелогичным и приводит к остановке выполнения сценария.


Экспортируемые заявки автоматически проверяются на попадание в следующий фильтр:
Заявка находится в активной области
Реквизит «Для экспорта» равен «Да»
Реквизит «Номер заявки на обмен» равен 0, т.е. заявка не входит в какую-либо заявку на обмен
Если заявка в фильтр не попадает, она не экспортируется. Для задания дополнительных условий фильтрации экспортируемых заявок предусмотрены следующие элементы:























Элемент
Комментарий

actions-objects
Назначение:
Пары «Действие» – «Объект недвижимости», для которых будет осуществляться экспорт заявок.

Тип значения:
См. пример.

Пример:
Если нужно экспортировать только заявки о продаже домов и продаже участков, необходимо указать:




Допустимые значения для action-type:
"Продажа"
"Покупка"
"Сдача в аренду"
"Наем"
Допустимые значения для object-type:
"Квартира"
"Комната"
"Дом"
"Участок"
"Нежилое помещение"
"Нежилое строение"

При отсутствии:
Не учитывается, т.е. экспортируются заявки для всех возможных пар.

filter-only-this-node
Назначение:
Экспортировать только заявки, созданные на данном (на котором запускается Realty-Robot) узле. Рекомендации:
В большинстве случаев имеет смысл указывать true, т.е. экспортировать только заявки, созданные на данном узле.
Указывать false, т.е. экспортировать все заявки, независимо от их принадлежности, имеет смысл в такой ситуации: данный узел импортирует заявки от различных узлов, т.е. выступает в роли агрегатора, а затем экспортирует их все на какой-то сайт объявлений.

Тип значения:
Булево: true, false

Пример:
Если нужно экспортировать заявки и созданные на данном узле и импортированные от всех других узлов:
false

При отсутствии:
Считается true

last-update-days
Назначение:
Ограничение экспорта по дате последнего обновления заявок.
Примечание: при создании заявки первоначальная дата её обновления устанавливается равной дате создания.

Тип значения:
Целое – больше или равно 1

Пример:
3
Будут экспортироваться только заявки, обновленные в БД сегодня, вчера и позавчера.

При отсутствии:
При отсутствии или менее 1 считается, что ограничений по дате последнего обновления заявок нет.

export-files
Назначение:
Необходимость экспорта файлов, прикрепленных к заявкам. Если false, то экспортируется только текстовая часть заявок, если true – также экспортируются все присоединенные к заявке документы (файлы), которые имеют установленный признак «Для экспорта».

Тип значения:
Булево: true, false

Пример:
true

При отсутствии:
Считается false

export-filename-format
Назначение:
Позволяет задавать шаблон создания имен экспортируемых файлов.
Потенциальная проблема при экспорте файлов состоит в том, что в разных заявках могут содержаться файлы изображений с одинаковыми именами, например: «Кухня.jpg», «Вид во двор.jpg» и т.д. Если не предпринимать никаких действий, такие файлы будут перезаписывать друг друга в каталоге и, следовательно, в итоге возникнет несоответствие между содержимым заявок и изображениями к ним. Шаблон можно конструировать из следующих макросов:
@qu – чистый номер заявки, к которой относится данный файл (уникальный в БД)
@doc – чистый номер документа (уникальный в БД)
@node – номер узла-владельца заявки
@name – оригинальное имя файла без расширения
@transname – транслитерированное оригинальное имя файла без расширения
@ext – расширение (с лидирующей точкой)
Макросы допустимо использовать в любых комбинациях, вставляя между ними любые символы (см. пример).
Особый комментарий необходимо сделать по поводу макроса @transname. Некоторые FTP-сервера не принимают имена файлов с использованием не латинских символов (такие символы при копировании файла на FTP-сервер заменяются, например, на знаки вопроса), либо требуют специфических настроек. Для того, чтобы сохранить в подобных ситуациях хотя-бы некоторую информативность имен файлов, и предназначен макрос @transname (см. пример).

Тип значения:
Строка

Примеры:
Для шаблона: @[email protected][email protected][email protected]@extимя файла получится следующим: 5=14=2500=кухня.jpgгде 5 – чистый номер заявки, 14 – чистый номер документа, 2500 – номер узла-владельца заявки, Кухня.jpg – оригинальное имя файла
Для шаблона: @[email protected][email protected][email protected]@ext
имя файла получится следующим: 5=14=2500=kuxnya.jpg
При отсутствии:
Считается @[email protected][email protected][email protected]@ext


Алгоритм

Если clear-local-dir-before установлен в true, Робот очищает каталог local-dir.
Если clear-local-dir-before установлен в false, но каталог loсal-dir не пуст, задача не стартует и для нее будет установлен статус «Не выполнены условия запуска».
Робот формирует набор файлов для экспорта (main.xml и файлы документов) и сохраняет их в каталог local-dir.
Если задан arc-dir, Робот создает в каталоге arc-dir подкаталог вида yyyy.mm.dd-hh:mm:ss- и копирует (не перемещает) в него все файлы из local-dir.



Формат Realty-Robot

Приведем описание самого формата Realty-Robot, оно может понадобиться при разработке пользователями собственных механизмов использования экспортируемых данных.

Данные каждой экспортируемой заявки представлены:
В виде элемента в файле main.xml
Набором файлов, которые были присоединены к заявке, и в которых отмечен реквизит «Для экспорта»

Файл main.xml имеет структуру:


2016-05-25T21:15:02+03:00

Реквизиты заявки (см. далее)


Реквизиты заявки (см. далее)





– элемент, содержащий подэлементы – по одному на каждый реквизит экспортируемой заявки. В следующей таблице все такие подэлементы рассмотрены подробно:

Элемент
Назначение

Общие


id
Уникальный (в рамках БД узла-владельца) номер заявки

trade-query-id
Уникальный (в рамках БД узла-владельца) номер заявки на обмен, в формулу которой входит данная заявка

url
Web-адрес, по которому располагается описание заявки в сети интернет.

node-name
Полное имя узла-владельца (экспортера)

action-type
Операция с объектом недвижимости:
«Не определено»
«Продажа»
«Покупка»
«Сдача в аренду»
«Наем»
«Обмен»

object-type
Тип объекта недвижимости:
«Не определено»
«Квартира»
«Комната»
«Дом»
«Участок»
«Нежилое помещение»
«Нежилое строение»
«Деньги» (для использования в формулах обмена)

comments
Общее примечание

internal-comments
Скрытое примечание

Финансы


first-cost
Себестоимость (цена владельца)

cost
Цена (предложения)

first-cost-m
Себестоимость за 1 кв.м.

cost-m
Стоимость за 1 кв.м.

Движение


query-date
Дата поступления заявки

query-source-type
Источник поступления заявки

query-state-type
Состояние заявки («Не проверено», «На проверке», )

last-call-date
Дата последней прозвонки

exclusive
Заявка является эксклюзивной

for-export
Разрешен экспорт заявки

arc-flag-type
Область хранения заявки: «Актив» – предопределенная область. Другие значения добавляются по необходимости

arc-flag-date
Время последней смены области хранения заявки

last-update-date
Время последнего редактирования заявки

География


city
Город

municipal-district
Муниципальный округ (в городе)

district
Район (в городе)

street
Улица

house-n
Номер дома

flat-n
Номер квартиры

metro
Ближайшее метро

metro-on-foot
До метро пешком, мин

metro-on-transport
До метро на транспорте, мин

latitude
Широта

longitude
Долгота

Здание


wall-type
Материал стен

rows
Этажность

build-year
Год постройки

Квартира


row
Этаж

high-bottom-row
Высокий первый этаж

rooms
Число комнат

flat-type
Тип квартиры («Сталинка», «Брежневка», )

total-area
Общая площадь

living-area
Жилая площадь

kitchen-area
Площадь кухни

toilet-type
Туалет («Раздельный», «Совмещенный», )

rooms-setting-type
Планировка комнат («Смежные», «Изолированные», )

floor-type
Покрытие пола («Паркет», «Линолеум», )

heating-type
Отопление («Центральное», «Печное», )

water-type
Вода («Колодец», «Скважина»)

hot-water-type
Горячая вода («Нет», «Бойлер», )

kitchen-stove-type
Кухонная плита («Газовая», «Электрическая», )

windows-setting-type
Расположение окон («На улицу», «Во двор», )

flat-state-type
Состояние квартиры («Евроремонт», «Нужен косметический ремонт», )

balcony-type
Балкон («Балкон», «Лоджия», )

corner-flat
Угловая квартира («Да», «Нет», )

telephone-type
Стационарный телефон («Есть», «Нет», )

entrance-security-type
Охрана подъезда («Нет», «Домофон», )

garbage-chute-type
Мусоропровод («Да», «Нет», )

lift-type
Лифт («Да», «Нет», )

Поиск


total-area-max
Общая площадь максимум, кв.м.

living-area-max
Жилая площадь максимум, кв.м.

kitchen-area-max
Площадь кухни максимум, кв.м.

land-area-max
Площадь участка максимум, кв.м.

except-bottom-row
Кроме нижнего этажа

except-top-row
Кроме верхнего этажа

Контакты


owner-name
Ф.И.О. клиента

owner-telephones
Телефоны клиента

owner-company
Компания клиента

owner-group
Группа клиентов

Участок


land-area
Площадь участка

road-type
Дорога («Асфальт», «Грунт», )

land-number
Номер участка

land-state-type
Состояние участка («Ландшафтный дизайн», «Неухоженный», )

land-use-type
Назначение участка («ИЖС», «Производство», )

land-titul-type
Титул участка («Собственность», «Бессрочное пользование», )

Дом


dacha
Это дача (true, false)

cellar-area
Площадь подвала, м.кв.

ceiling-height
Высота потолка, м.

roof-type
Покрытие крыши («Черепица», «Шифер», )

basement-type
Фундамент ()

floor-deck-type
Материал перекрытий ()

electric-type
Электросеть («220», «380», )

developer-finish-time
Срок сдачи

Нежилое помещение/строение


commerce-use-type
Назначение нежилого помещения/строения («Магазин», «Склад», )

move-to-commerce-type
Возможен перевод в нежилое («Да», «Нет», )

Юридические вопросы


registration-type
Прописка («Чистая», «Есть прописанные», )

residence-type
Проживание («Выселена», «Есть проживающие»)

ownership-form-type
Форма собственности («Собственность», «Приватизация», )

Аренда


rent-prepayment
Аренда: требуется предоплата, руб

rent-furniture-type
Аренда: имеется мебель («Да», «Нет», )

rent-tv-type
Аренда: имеется телевизор («Да», «Нет», )

rent-refrigerator-type
Аренда: имеется холодильник («Да», «Нет», )

rent-free-date
Аренда: будет свободно (дата)

Сделки


deal-number
Номер сделки

deal-form-type
Форма сделки («Купля-продажа квартиры», «Купля-продажа дома», )

deal-name
Наименование сделки (произвольно)

deal-open-date
Дата открытия сделки

deal-close-date
Дата закрытия сделки

deal-comments
Комментарии к сделке

Присоединенные документы


documents
Элемент, содержащий подэлементы

doc
Элемент, описывающий один присоединенный к заявке документ (файл)

id
Уникальный (в рамках БД узла-владельца) номер документа

query-id
заявки, к которой присоединен данный документ

doc-filename
Оригинальное имя файла, например: DSC12345.JPG

doc-name
Альтернативное имя файла, например: «Баня, вид южной стороны»

orig-file-size
Оригинальный размер файла

orig-crc32
Оригинальный CRC32 файла

for-export
Разрешен экспорт данного файла

export-doc-filename
Служебное, автоматически генерируемое, имя файла, которое будет использоваться для целей экспорта. Имеет формат, зависящий от настройки (см. выше). По этому имени при импорте можно найти соответствующий файл, находящийся в одном каталоге с файлом main.xml.


Имена присоединенных файлов могут образовываться различным образом в зависимости от настройки (см. выше). Ссылки на присоединенные файлы содержатся в файле main.xml в элементах (см. выше), собственно файлы экспортируются в каталог ·dir>.
Сценарий экспорта

Сценарий экспортирует данные в формат YRL (Yandex Realty Language), разработанный Яндексом для сервиса Яндекс.Недвижимость. Все элементы настроек для сценария применимы и к данному сценарию. Имеется одна специфическая настройка:


Элемент
Комментарий

ftp-dir-url
Назначение:
Конструирование полного пути к экспортируемым изображениям. YRL требует задавать для изображений полные имена, например:
http://www.realty-soft.ru/export/5=14=2500=кухня.jpg
Поэтому еще на этапе создания файла main.xml Realty-Robot должен знать, в какой каталог на каком ресурсе в интернете в конечном итоге будут скопированы файлы изображений, т.е. откуда они будут доступны сервису Яндекс.Недвижимость. Для приведенного выше примера в сценарии необходимо объявить:
http://www.realty-soft.ru/export/

Тип значения:
Строка

При отсутствии:
Обязательно, если экспортируется хотя бы одно изображение.


После выполнения сценария появившиеся в каталоге файлы необходимо скопировать в каталог , доступный сервису Яндекс.Недвижимость. Возможны как минимум 2 варианта:
Скопировать вручную, используя какой-либо FTP-клиент
Создать составной сценарий (см. далее), который сначала запускает сценарий , а затем сценарий .

Сценарий разработан таким образом, чтобы выходной xml-документ main.xml проходил валидацию на странице [ Cкачайте файл, чтобы посмотреть ссылку ]. Результат проверки должен быть «XML соответствует схеме XSD».
















Сценарий импорта

Сценарий выполняет импорт данных в формате Realty-Robot. Если исходный формат иной – необходимо разрабатывать утилиту или заказной сценарий, выполняющие конвертацию данных в формат Realty-Robot.

Настройки

Элемент
Комментарий

delete-previous-requests
Назначение:
Если true, то перед импортом все заявки, принятые ранее от узлов-экспортеров, заявки от которых находятся в данном импорте, будут удалены. Рекомендации:
Если каждый раз узел-экспортер отправляет данному узлу все свои актуальные заявки, то имеет смысл указывать true – в БД после каждого импорта будут присутствовать только заявки, которые еще актуальны.
Исходная ситуация аналогично п.1, но есть необходимость накапливать вообще все заявки, когда-либо принятые от данного узла-экспортера. Тогда следует указать false.
Если каждый раз узел-экспортер отправляет данному узлу только новые заявки, можно указать false – накопление заявок будет происходить аналогично п.2.
По возможности, следует отдавать предпочтение п.1, иначе в БД будет накапливаться большое число заявок, со временем становящихся неактуальными.
Напоминание: импортированную заявку нельзя редактировать, в т.ч. и перенести в архивную область, ее можно только удалить или создать собственную новую заявку копированием из импортированной.

Тип значения:
Булево: true, false

Пример:
true
Например, если в рамках задачи импортируются заявки от узлов (node-id) 2100, 2200, 2300, то перед началом сохранения в базу данных принятых заявок, все заявки от этих узлов из базы данных будут удалены.

При отсутствии:
Считается true


Прежде, чем пояснить использование других элементов настройки сценария, введём некоторые термины.

Узел – информационная система (система «Агентство недвижимости» или иная система), участвующая в обмене заявками с другими узлами.

Узел-экспортер – узел, экспортирующий заявки, которые затем принимаются неким узлом-импортером (узлами-импортерами).

Узел-импортер – узел, импортирующий заявки, ранее экспортированные другим узлом.

Номер узла (node-id) – четырех-пятизначный номер, уникальным образом идентифицирующий узел с точки зрения алгоритмов работы Realty-Robot. Номера узлов в рамках системы «Агентство недвижимости» находятся в диапазоне 100089999. Другое название номера узла при распространении системы «Агентство недвижимости» – лицензионный номер. Номер узла в ситуации т.н. анонимного импорта (см. далее) назначается особым образом из специального диапазона 9000091000.

Узел-владелец заявки – узел, на котором данная заявка была впервые создана, и который владеет ей. Владение заявкой означает возможность её редактирования.
Если заявка была создана в системе «Агентство недвижимости», то узлом-владельцем для нее, очевидно, является узел, на котором установлена конкретная копия системы «Агентства недвижимости»; номер узла в таком случае – это лицензионный номер.
Если заявка была создана в другой системе или, например, просто была вручную внесена в excel-файл, из которого затем был произведен импорт, то такой узел, очевидно, не имеет никакого номера в рамках системы «Агентство недвижимости». Далее будет пояснено, что в таком случае для целей импорта номер узла-владельца назначается искусственно.

Чистый номер заявки – номер, автоматически сопоставляемый системой «Агентство недвижимости» каждой вновь создаваемой заявке на конкретном узле. Нумерация последовательная, начиная с 1, с шагом 1. Очевидно, что на разных узлах со временем появится множество заявок, имеющих одинаковые номера, хотя и имеющие совершенно разное содержание.

Полный номер заявки – это чистый номер заявки, справа к которому приписан номер узла node-id, расширенный до 5 значащих разрядов. Например, номер узла 2500 будет расширен до 02500. Если чистый номер заявки был 148, то полный номер получится 14802500. Именно полный номер заявки сохраняется в составе заявки в базе данных. Поскольку
все базы данных клиентов системы «Агентство недвижимости» имеют уникальные node-id и
предполагается, что для анонимного импорта указываются node-id из специального диапазона,
то автоматически обеспечивается бесконфликтное хранение в БД заявок от разных узлов-владельцев, даже если чистые номера заявок в них совпадают.

Импорт заявки в зависимости от указания в ней узла-владельца делится на две категории:
Адресный импорт – импортируемая заявка создавалась на узле-владельце в системе «Агентство недвижимости». В этом случае в элементе заявки присутствуют подэлементы , , , . Для сохранения такой заявки в базу данных не требуется дополнительных идентифицирующих сведений.
Анонимный импорт – импортируемая заявка создавалась не в системе «Агентство недвижимости». В элементе подэлемент (или , см. далее) указан, а подэлементы , , с большой вероятностью отсутствуют и такая заявка не может быть непосредственно сохранена в базу данных, т.к. неизвестен ее узел-владелец. Тем не менее, для поддержания возможности такого импорта в сценарии импорта можно указать эти три элемента явным образом и все заявки, в которых будет отсутствовать свой , будут считаться имеющими узел-владелец , указанный в сценарии.


Каждая импортируемая заявка к моменту её непосредственного импорта в БД должна быть идентифицирована. Возможные варианты:
Импорт по .
Адресный импорт (см. выше). Заявка создавалась на узле-владельце в системе «Агентство недвижимости». Это означает, что заявке изначально сопоставлен корректный чистый номер , который Realty-Robot при импорте может корректно расширить до полного номера и сохранить в БД. Наиболее простой вариант.
Анонимный импорт (см. выше). Заявка создавалась на узле-владельце не в системе «Агентство недвижимости». Но, тем не менее, заявка идентифицирована – указан уникальный в рамках узла-владельца (экспортера). Этот вариант Realty-Robot также может обработать стандартным образом, расширив до полного номера, основываясь на указанном в сценарии импорта .
Импорт по . Анонимный импорт (см. выше). Заявка создавалась на узле-владельце не в системе «Агентство недвижимости». Возможны 2 подварианта:
Заявка импортируется с какой-либо рекламной площадки (агрегатора рекламных площадок) и в описании заявки отсутствует , но присутствует web-адрес (URL), по которому заявка доступна в сети интернет. Realty-Robot может рассматривать этот web-адрес как уникальный строковый идентификатор заявки. При импорте в БД Realty-Robot пробует идентифицировать такую заявку в БД по её . Если подобный не найден, робот создаёт новую заявку, где генерируется как «местный», а извлекается из сценария.
Все остальные источники заявок. Готового автоматизированного способа импорта подобных заявок нет. Если возникает такая потребность, необходимо разрабатывать заказной сценарий импорта, который по некоторому алгоритму будет генерировать уникальные идентификаторы для подобных «безымянных» заявок.

Realty-Robot автоматически распознаёт ситуацию для того, чтобы выбрать вариант генерации полного номера заявки ( + ) в процессе её импорта:
В заявке присутствует чистый номер . Наличие/отсутствие не имеет значения.
В заявке присутствует номер узла-владельца . Полный номер заявки: + .
В заявке отсутствует номер узла-владельца . В сценарии импорта наличие номера узла-владельца обязательно.Полный номер заявки: + .
В заявке отсутствует чистый номер . Наличие в заявке обязательно. В сценарии импорта наличие номера узла-владельца обязательно. рассматривается как уникальный строковый идентификатор импортируемой заявки. При добавлении такой заявки в БД автоматически генерируется «местный» . Полный номер заявки: <сгенерированный id> + .

Элемент
Комментарий

node-id
Назначение:
Каждая заявка, сохраняемая в БД, должна содержать указание на узел-владелец node-id. Цель – предотвращение смысловых конфликтов в БД при импорте от различных источников.

Важно: Для анонимного импорта значение node-id следует назначить любым из диапазона 9000091000. При этом значения node-id, назначаемые в сценариях на данном узле-импортере различным узлам-экспортерам, во избежание путаницы не должны совпадать!

Если в процессе импорта очередной заявки Realty-Robot обнаруживает, что в базу данных еще не импортировались заявки от узла node-id, он добавляет в справочник «Фирмы» новый элемент, который будет содержать номер узла node-id, полное наименование узла node-name и сокращенное наименование узла node-short-name.

Тип значения:
Целое. Разрешенный диапазон указан выше.

Пример:
1800

При отсутствии:
Обязателен

node-name
Назначение:
Полное имя узла-экспортера

Тип значения:
Строка.

Пример:
Агентство недвижимости «Солнышко»

При отсутствии:
Обязателен, если указан

node-short-name
Назначение:
Краткое имя узла-экспортера. Используется в таблице заявок для отображения узла-источника заявки.

Тип значения:
Строка.

Пример:
Солнышко

При отсутствии:
Обязателен, если указан


Алгоритм

Если в local-dir отсутствует файл-индикатор ready.flag, значит файлы еще не готовы для импорта и задача не стартует, для нее будет установлен статус «Не выполнены условия запуска».
Робот импортирует заявки из файлов каталога local-dir в БД.
Если задан arc-dir, Робот создает в каталоге arc-dir подкаталог вида yyyy.mm.dd-hh:mm:ss- и копирует в него все файлы из local-dir.
Если clear-local-dir-after установлен в true, Робот очищает каталог local-dir.

Сценарии копирования между локальным каталогом и FTP-каталогом
Общие настройки сценариев и 

Эти сценарии обычно используются как части составных сценариев, когда после выполнения сценария экспорта необходимо скопировать получившиеся файлы на некий FTP, и наоборот – перед выполнением сценария импорта необходимо сначала получить импортируемые файлы с некоего FTP.

Элемент
Комментарий

ftp-host
Назначение:
Адрес FTP-сервера.

Тип значения:
Строка

Пример:
101.102.103.104

При отсутствии:
Обязателен.

ftp-user
Назначение:
Логин для подключения к FTP-серверу

Тип значения:
Строка

Пример:
superadmin

При отсутствии:
Обязателен

ftp-psw
Назначение:
Пароль для подключения к FTP-серверу

Тип значения:
Строка

Пример:
qwerty

При отсутствии:
Обязателен

ftp-dir
Назначение:
Каталог на FTP-сервере, в который данные будут экспортироваться (в сценарии копирования на FTP) или из которого данные будут импортироваться (в сценарии копирования с FTP).

Тип значения:
Строка

Пример:
/www/test/from5555

При отсутствии:
Обязателен

ftp-op-before-pause
Назначение:
Максимальное число команд, отправляемых на FTP-сервер в одном сеансе подключения.
Некоторые FTP-сервера могут обрывать соединение, если число операций в одном сеансе оказывается слишком большим. В таких случаях можно экспериментально подобрать комбинацию (шт.) и (сек.), которая предотвратит подобные обрывы. Иначе большой (по числу файлов) сценарий копирования может так никогда и не быть завершен.

Тип значения:
Число, штук

Пример:
30

При отсутствии:
Считается равным 50

ftp-pause-length
Назначение:
Пауза в секундах между двумя соседними последовательностями в команд, отправленных на FTP-сервер. См. также описание

Тип значения:
Число, секунд

Пример:
5

При отсутствии:
Считается равным 3

clear-ftp-dir-before
Назначение:
ftp-dir нужно очистить перед выполнением задачи. В стандартных ситуациях следует указывать true. Применим только при копировании на FTP. Если указано false, то
экспортируемые файлы будут перезаписываться в FTP-каталоге поверх уже существующих с совпадающими именами
в FTP-каталоге останутся те файлы, которые были там раньше, но не экспортировались в процессе данной задачи копирования.

Тип значения:
Булево: true, false

Пример:
true

При отсутствии:
Считается true

clear-ftp-dir-after
Назначение:
ftp-dir нужно очистить после выполнения задачи. Применим только при копировании с FTP.

Тип значения:
Булево: true, false

Пример:
true

При отсутствии:
Считается true


Алгоритм сценария

Если в каталоге local-dir не обнаружен файл-индикатор ready.flag, задача не стартует с установкой статуса «Не выполнены условия запуска».
Робот подключается к серверу FTP, используя ftp-host, ftp-user, ftp-psw.
Если clear-ftp-dir-before установлен в true, Робот очищает каталог ftp-dir.
Если clear-ftp-dir-before установлен в false, но каталог ftp-dir не пуст, задача не стартует и для нее будет установлен статус «Не выполнены условия запуска»
Робот копирует все файлы из local-dir в ftp-dir.
Если clear-local-dir-after установлен в true, Робот очищает каталог local-dir.
Алгоритм сценария

Если в каталоге ftp-dir не обнаружен файл-индикатор ready.flag, задача не стартует с установкой статуса «Не выполнены условия запуска».
Если clear-local-dir-before установлен в true, Робот очищает каталог local-dir.
Если clear-local-dir-before установлен в false, но каталог local-dir не пуст, задача не стартует и для нее будет установлен статус «Не выполнены условия запуска»
Робот подключается к серверу FTP, используя ftp-host, ftp-user, ftp-psw.
Робот копирует все файлы из ftp-dir в local-dir.
Если clear-ftp-dir-after установлен в true, Робот очищает каталог ftp-dir.





Сценарий выполнения внешней программы

Запуск внешней программы может быть востребован в ситуации, когда компания собственными силами разрабатывает некую программу (например, работающую в режиме командной строки) для осуществления специфических преобразований данных в дополнение к другим сценариям (стандартных или заказных). Как правило, является частью составного сценария (см. далее). Следующие элементы специфичны для сценария выполнения внешней программы:

Элемент
Комментарий

file-name
Назначение:
Полный путь к программе. В дополнение к полному пути программы можно указать нужные аргументы (см. далее элемент ).

Тип значения:
Строка.

Пример:
Пусть внешняя программа представляет собой конвертер заявок, скачиваемых с некоторого сайта [ Cкачайте файл, чтобы посмотреть ссылку ] в формат Realty-Robot. Конвертер преобразует набор исходных файлов, располагающихся в каталоге c:\Realty\import-from-abc-ru и помещает их преобразованный эквивалент в этот же каталог. Тогда настройка сценария для запуска конвертера может выглядеть так:

Конвертер www.abc.ru

c:\Program Files\Realty-Soft.ru\Realty\Converters\ConverterFromAbcRu.exe


c:\Realty\import-from-abc-ru


При выполнении задачи по такому сценарию Realty-Robot будет действовать следующим образом:
Запустит на выполнение команду: c:\Program Files\Realty-Soft.ru\Realty\Converters\ConverterFromAbcRu.exe c:\Realty\import-from-abc-ru
Дождется ее выполнения

При отсутствии:
Обязателен

arguments
Назначение:
Аргументы к запускаемой внешней программе.

Тип значения:
Строка.

Пример:
c:\Realty\import-from-abc-ru
Обычно аргументы необходимы, т.к., например, любому конвертеру необходимо предоставить информацию, в каком каталоге искать исходные файлы и в какой каталог помещать результирующие.

При отсутствии:
Не учитывается








Составной сценарий

Составной сценарий является удобным способом задать последовательность выполнения других сценариев. Следует иметь в виду, что при возникновении ошибки в процессе выполнения очередного сценария в составе составного, последующие сценарии выполняться уже не будут.

Элемент
Комментарий

scenarios
Назначение:
Задаёт последовательность выполнения других сценариев.

Пример:
Предположим, в некоторой компании необходимо по определенному расписанию осуществлять импорт заявок с некоторого сайта [ Cкачайте файл, чтобы посмотреть ссылку ]. Причем импортируемые файлы имеют формат Realty-Robot, т.е. на узле-экспортере создаются в системе «Агентство недвижимости». Тогда имеет смысл использовать составной сценарий вида:

Копирование с сайта www.abc.ru
Импорт www.abc.ru

где:
«Копирование с сайта www.abc.ru» – имя сценария стандартного типа ,
«Импорт www.abc.ru» – имя сценария стандартного типа .
Обратите внимание, что в элементах указываются не типы, а имена сценариев.

При выполнении задачи по данному сценарию Realty-Robot будет действовать следующим образом:
Проверит условия запуска сценария «Копирование с сайта [ Cкачайте файл, чтобы посмотреть ссылку ]. Если условия запуска выполнены – запустит этот сценарий, в результате чего файлы для импорта окажутся в каталоге сценария «Копирование с сайта www.abc.ru»
Если предыдущий сценарий был выполнен без ошибок, запустит сценарий импорта «Импорт [ Cкачайте файл, чтобы посмотреть ссылку ].

При отсутствии:
Обязателен


Заказные сценарии

По запросам клиентов могут разрабатываться заказные сценарии для специфических бизнес-процессов, например, обмен данными между Realty-Robot и площадками объявлений, взаимодействие со сторонними системами и т.д. Такие заказные сценарии затем могут использоваться как части составных сценариев либо, если таково их назначение, выполняться самостоятельно.

Общие рекомендации выбора между использованием стандартного сценария  и заказными сценариями:
Если компания решает самостоятельно реализовать некую специфическую функциональность, расширяющую возможности Realty-Robot, она может это сделать, разработав отдельную программу, которая затем будет выполняться в сценарии . Такое решение, очевидно, является внешним по отношению к Realty-Robot.
Если компания останавливается на заказном сценарии, этот сценарий разрабатывается разработчиком Realty-Robot. Такое решение является интегрированным в Realty-Robot подобно всем стандартным сценариям. Заказному сценарию присваивается свой уникальный тип, который затем можно использовать для объявления сценариев в файле Realty-Robot.xml. Интегрированные сценарии лучше взаимодействуют с Realty-Robot, т.к. изначально разрабатываются с учетом тех же требований, что и стандартные сценарии.
Шаблоны сценариев в Realty-Robot.xml

При установке системы «Агентство недвижимости» в числе прочих файлов на компьютер копируется шаблонный файл настроек Realty-Robot.xml. Подключение к БД указано в файле непосредственно:

data source=localhost;
initial catalog=c:\Program Files\Realty-Soft.ru\Realty\realty-demo-1.fdb;
dialect=3;
user id=sysdba;
password=masterkey;
character set=WIN1251;pooling=False


В файле содержатся 2 демонстрационных сценария под именами:
«Шаблон экспорта»
«Шаблон экспорта Яндекс.Недвижимость»

Сценарии имеют способ запуска manually. Для демонстрации работы сценариев после запуска Realty-Robot можно нажать на «Однократно», выбрать один из этих сценариев и нажать «Выбрать и запустить».«Шаблон экспорта» (формат Realty-Robot) по умолчанию сохраняет файлы в каталог
c:\Program Files\Realty-Soft.ru\Realty\Export\Standard-Export,
«Шаблон экспорта Яндекс.Недвижимость» (формат YML) – в каталог
c:\Program Files\Realty-Soft.ru\Realty\Export\Yandex-Export

Т.к. при установке системы настраивается подключение к демонстрационной БД realty-demo-1.fdb, Realty-Robot будет производить экспорт именно из этой БД. Экспортируются все заявки и документы c включенными флагами «Разрешить экспорт» (в демонстрационной БД таких заявок большинство). На примере этих сценариев можно ознакомиться, каким образом работает Realty-Robot и как выглядят результаты экспорта.

Рекомендации по разработке сценариев для распространенных ситуаций
Ситуация: анонимный импорт из xls-файла

Если компания регулярно получает данные от компаний-партнеров об имеющихся у них заявках, и эти данные представлены в каком-либо формате, отличном от формата Realty-Robot, например, в формате Excel, рекомендации по разработке сценария таковы:

Вариант 1: Использование внешней программы конвертации
Разработать программу конвертации данных из получаемого формата в формат Realty-Robot (для определенности назовем ее converter.exe)
В файле Realty-Robot.xml:
Создать сценарий стандартного типа с запуском converter.exe. Пусть имя сценария будет «Конвертация».
Создать сценарий стандартного типа , пусть имя сценария будет «Импорт».
Создать составной сценарий, который будет вызывать вышеуказанные два сценария в нужной последовательности: Конвертация Импорт

Вариант 2: Использование заказного сценария
Заказать разработку заказного сценария конвертера. Пусть его тип будет 
В файле Realty-Robot.xml:
Создать сценарий заказного типа . Пусть имя сценария будет «Конвертация».
(Аналогично варианту 1) Создать сценарий стандартного типа , пусть имя сценария будет «Импорт».
(Аналогично варианту 1) Создать составной сценарий, который будет вызывать вышеуказанные два сценария в нужной последовательности: Конвертация Импорт

В сценарии импорта не забыть указать элементы , , для поддержки анонимного импорта.

В обоих вариантах могут быть приняты (и реализованы в программе либо заказном сценарии) различные соглашения по поводу того, куда копировать исходные xls-файлы, что является условием запуска задачи по заказному сценарию или сценарию запуска конвертера и т.д.






Способы запуска составного сценария:
В режиме запуска по интервалу. Задать достаточно короткий интервал, например, 10 сек. Полученный от компании-партнера Excel-файл скопировать в условленный входной каталог. Как только робот по истечении очередного 10-секундного интервала ожидания запустит задачу по составному сценарию, данные сначала будут преобразованы посредством converter.exe, а затем импортированы в БД.
В режиме однократного запуска. Для составного сценария устанавливается режим запуска «Вручную». Как и в предыдущем варианте, Excel-файл копируется в условленный входной каталог, а затем в Realty-Robot выбирается запуск «Однократно» для этого составного сценария.
Ситуация: обмен данными с компаниями-партнерами

Предположим, три компании – К1, К2, К3, – имеющие партнерские отношения, решили обмениваться своими заявками между собой на определенных условиях. Для организации обмена потребуется организовать следующие потоки данных:
К1 ( К2, К3
К2 ( К1, К3
К3 ( К1, К2

Выбирается некоторый FTP-сервер, который будет выполнять роль «центра синхронизации». На сервере создаются 6 каталогов по числу перечисленных выше потоков данных:
\K1-K2\
\K1-K3\
\K2-K1\
\K2-K3\
\K3-K1\
\K3-K2\

На каждом из трех узлов настраиваются:
2 составных сценария (экспорт и копирование на FTP) в сторону других двух партнеров. Возможно, следует ограничить перечень передаваемых реквизитов заявок, если между партнерами нет полностью доверительных отношений.
2 составных сценария (копирование с FTP и импорт) от других двух партнеров.

Способ запуска для задач экспорта можно выбрать «по расписанию», например, в 9, 11, 13, 15, 17, 18 часов ежедневно, а для задач импорта – «интервал», например, раз в 1 час. Тогда в среднем с задержкой 30 мин на каждом узле будут появляться обновленные заявки партнеров.
Ситуация: обмен данными между главным офисом компании и филиалами

Для организации совместной работы филиалов компании лучше всего использовать модель «звезда», когда центральной точкой взаимодействия является главный офис компании, на котором расположен терминальный сервер и общая БД, а на всех филиалах установлены терминальные клиенты. При этом программа «Агентство недвижимости» запускается на клиентах в терминальном режиме и фактически исполняется на сервере в главном офисе. В этом случае обеспечивается единое информационное пространство без каких-либо накладных расходов на синхронизацию данных.






Тем не менее, если отсутствует возможность организации постоянной интернет-связи между филиалами и главным офисом, можно использовать рассматриваемый в этом руководстве механизм экспорта/импорта данных. В этом случае необходимо иметь в виду:
На всех узлах компании должны быть установлены свои собственные копии системы «Агентство недвижимости» со своими собственными лицензионными номерами (node-id).
Возможность попеременного редактирования одной и той же заявки на разных узлах будет недоступна.
Сценарии экспорта, скорее всего, будут похожи на изложенный в разделе «Сценарии обмена данными с компаниями-партнерами».

Примечание: как альтернативу терминальному режиму взаимодействия можно рассмотреть организацию VPN.
Рекомендуемый алгоритм работы скрипта импорта на сайте

Исходя из вышеизложенного, можно рекомендовать следующий алгоритм работы скрипта импорта на сайте.

Скрипт работает в цикле с некоторым интервалом ожидания.
По окончании очередного интервала ожидания проверяем наличие файла-индикатора ready.flag в каталоге ftp-dir. Если его нет, значит экспорт с узла-экспортера еще не производился или не завершен. Выходим.
Удаляем файл-индикатор ready.flag, что будет признаком того, что импорт начался и никакой другой сценарий/процесс не должен работать с каталогом ftp-dir.
Выполняем собственно импорт в БД сайта, при этом наличие/отсутствие тех или иных заявок в БД определяем по связке +. Импорт можно организовывать различным образом, приведем один из них:
Удаляем из БД все заявки, которые были ранее приняты от узла-экспортера, но сейчас отсутствую в файле mail.xml. Тем самым обеспечиваем отсутствие в БД сайта уже неактуальных заявок.
Добавляем в БД все заявки, которые имеются в файле main.xml, но отсутствуют в БД. Тем самым обеспечиваем наличие в БД сайта новых заявок.
Обновляем в БД все заявки, которые имеются в файле mail.xml и одновременно имеются в БД сайта. Тем самым обеспечиваем актуализацию уже имеющихся в БД заявок.
Очищаем каталог ftp-dir, тем самым подготовив его к следующему экспорту со стороны узла-экспортера.
Уходим на очередной интервал ожидания цикла.
Работа с Realty-Robot

После запуска программа Realty-Robot загружает настройки (общие и сценарии) из файла настроек Realty-Robot.xml и далее руководствуется ими. Пример главного окна программы после выполнения нескольких задач:



Далее рассмотрено выполнение различных команд:

Команда
Комментарий

Действия: Старт
Доступна, если Робот остановлен.
Запускается Робот, начинается исполнения задач по сценариям в соответствии с назначенными расписаниями и интервалами.

Действия: Стоп
Доступна, если Робот запущен.
Если на данный момент времени нет ни одной задачи в состоянии «Выполняется», Робот останавливается. Если на данный момент имеется задача в состоянии «Выполняется», под кнопкой отображается сообщение красного цвета «Остановка робота будет произведена после выполнения текущей задачи» и после окончания выполнения задачи Робот останавливается.

Действия: Однократно
Доступна всегда.
Независимо от состояния Робота (запущен/остановлен) пользователю предоставляется возможность принудительно запустить на выполнение задачу по одному из имеющихся сценариев. После нажатия на кнопку отображается окно примерного содержания:



После выбора нужного сценария и нажатия на «Выбрать и запустить» произойдет:
добавление новой задачи по выбранному сценарию с признаком запуска «Однократно»
возврат в главное окно
запуск задачи:
если Робот работает (т.е. не остановлен), задача ставится в очередь со временем планового старта равным текущему времени
если Робот не работает и сейчас не выполняется другая задача, то задача стартует. Если сейчас выполняется другая задача, запрос на старт новой задачи игнорируется

Действия: Подробности
Доступна всегда.
Используется для просмотра:
Ошибок, если они произошли в процессе выполнения задачи
Не выполненных условий запуска, вследствие которых задача не смогла быть запущена
Просмотр осуществляется в отдельно открывающемся окне. Нажатие на кнопку дублирует двойной клик на левую кнопку мыши.

Действия: Выход
Доступна, если в данный момент времени не выполняется ни одна задача. Дублирует данную кнопку стандартная кнопка закрытия окна в верхнем правом углу в заголовке окна.

Фильтр по состоянию задач
Доступен всегда.
Каждая задача в каждый момент времени находится в одном из состояний –перечислены в фильтре как переключатели.
В процессе работы Робота в списке задач в главном окне может накопиться большое число записей о различных задачах. Для того, чтобы сосредоточить внимание только на некоторых из них, можно использовать переключатели фильтра. Например, если имеются сценарии с небольшими интервалами запуска задач, то очевидно, что в списке со временем появится большое число записей с состоянием «Не выполнены условия запуска». Для того, чтобы их скрыть, можно выключить одноименный переключатель.

Протоколирование действий Realty-Robot

Realty-Robot ведет два протокола:
Протокол задач
Системный протокол
Протокол задач

В протокол задач сохраняются сведения о каждой задаче, которая была завершена или для которой не выполнены условия запуска. Протоколы задач сохраняются в подкаталоге \realty-robot-tasks-log. На каждые сутки автоматически создается отдельный файл протокола задач. Например, для даты 2016.05.29 будет создан файл протокола задач \realty-robot-tasks-log\2016-05-29-tasks.xml.

Файл протокола задач можно использовать двумя способами:
Косвенно, используя в главном окне команду «Подробности». В этом случае в окне «Подробности» будут отображены элементы протокола для конкретной задачи, относящиеся к ошибкам при выполнении задачи (если имеются) и не выполненным условиям запуска (если имеются).
Просматривая его непосредственно. Например, в браузере Microsoft Explorer.
Системный протокол

Системный протокол может работать в двух режимах
Стандартный режим. Включен по умолчанию. В стандартном режиме системный протокол содержит только записи о произошедших ошибках в Realty-Robot.
Сервисный режим. Включается при запуске Realty-Robot, если в файле Realty-Robot.xml указан элемент true. В этом случае в протокол выводится подробная последовательность действий Realty-Robot.

Системные протоколы сохраняются в подкаталоге \realty-robot-trace-log. На каждые сутки автоматически создается отдельный файл системного протокола. Например, для даты 2016.05.29 будет создан файл протокола задач \realty-robot-tasks-log\2016-05-29-trace.xml. Файл системного протокола можно использовать для разрешения проблемных ситуаций двумя способами:
При взаимодействии со службой технической поддержки.
Просматривая его непосредственно. Например, в браузере Microsoft Explorer.








13PAGE \* MERGEFORMAT142215




Рисунок 1Рисунок 1Рисунок 1ЛђЗаголовок 1ЛђЗаголовок 2НђЗаголовок 315