Описание базовых элементов интерфейса — различия между версиями

Текущая версия на 08:23, 26 марта 2015

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

Общие модульные методы

Методы этого раздела служат для доступа к общей информации о plugin-программе, ее назначении и составе.

• Guid GetId ( ). Возвращает уникальный Guid-идентификатор plugin-программы. Используется при различении программ и при обновлениях. По идентификатору приложение загружает plugin в память процесса и не допускает копий.

• int GetInterfaceVersion ( int lastknownversion ). Возвращает версию интерфейса, на котором базируется plugin-программа.

В качестве параметра из Oktell передается максимально поздняя поддерживаемая версия. Изначально базовая версия 81022. Если plugin-программа при вызове метода возвращает номер версии, неизвестный для текущей версии Oktell, зарегистрировать ее не удастся.

• string GetModuleVersion ( ). Возвращает версию plugin-программы в строковом виде. Например «A1.0.1».

• string GetModuleName ( ). Возвращает собственное название plugin-программы. При использовании в комплексе в качестве имени будет использоваться другое, назначенное администратором при регистрации имя. Однако собственное может нести какую-либо дополнительную информацию.

• string GetDBUpdate ( ). Возвращает строку с запросом в формате Transact-SQL, представляющую собой пакет обновлений для БД при регистрации plugin-программы. Возможно присутствие нескольких батчей, разделенных строчками «GO» согласно tSQL. Запрос выполняется в БД в момент первого сохранения plugin-программы на сервере. Однако возможно и повторное исполнение в случае, если предварительно удалить регистрацию и создать новую с теми же параметрами. Это необходимо иметь в виду при создании запроса-обновления и формировать проверочные условия и/или удаляющие команды. Обновление для БД может отсутствовать. Однако для plugin-программ, реализующих доступ к уникальным сведениям в БД необходимо гарантировать существование в БД соответствующих таблиц, функций и хранимых процедур.

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

Пример возвращаемого значения:

<?xml version="1.0" encoding="utf-16"?>
 <oktellxmlmapper version="80710">
 <data name="dbupdate" count="1">
   <property_set>
     <property_cdata key="sqltext"><![CDATA[if exists ( Select * FROM sysobjects where id = object_id ( 'dbo.T_PluginTest' ) )
   Drop Table dbo.T_PluginTest]]></property_cdata>
     <property_cdata key="sqltext">
     <![CDATA[Create table dbo.T_PluginTest (id int identity ( 1, 1 ) Primary Key, name nvarchar ( 50 ), st bit )]]>
 </property_cdata>
     <property_cdata key="sqltext"><![CDATA[Insert into T_PluginTest ( Name, St ) Values ( 'A', 1 )]]></property_cdata>
   </property_set>
 </data>
 </oktellxmlmapper>

Текстовая информация из полей CDATA в каждом элементе property_cdata содержится отдельный batch-блок с запросом в формате tSQL. Все перечисленные запросы выполнятся поочередно в порядке присутствия в теле XML строки. Каждый запрос будет выполнен в отдельном batch-блоке. Если необходимо разделить текст запроса, представленного внутри одного property_cdata, необходимо стандарным способом в необходимом месте разделения вставить строку «GO».

Пример 2 возвращаемого значения.

Можно также возвращать строку, сразу содержащую тело запроса, в котором блоками GO разделяются batch-блоки.

if exists ( Select * FROM sysobjects where id = object_id ( 'dbo.T_PluginTest' ) )
  Drop Table dbo.T_PluginTest
GO

Create table dbo.T_PluginTest (id int identity ( 1, 1 ) Primary Key, name nvarchar ( 50 ), st bit )
GO

Insert into T_PluginTest ( Name, St ) Values ( 'A', 1 )
GO

• string GetForms ( ). Возвращает перечень заявленных стартовых plugin-форм (и компонентов) в виде строки с XML-содержимым установленной структуры. Для описания каждой plugin-формы используются параметры id, caption (name), description, controltype (control/form/none), module (dialog/crm/scriptcomponent), helplink. Именно этот метод определяет формат работы с plugin-программой. Настройка всех вариантов ее применения в комплексе зависит от состава стартовых plugin-форм и их направленности.

Каждая форма имеет уникальный Guid-идентификатор (id). Используется очевидным образом: Для настройки ссылок, а также для различения параметров (их принадлежности к конкретной форме при обмене информацией между plugin-программой и приложением Oktell). Название (caption) и описание (description) используются для отображения в приложении Oktell в модулях настройки на работу с plugin-программой.

Тип контрола (controltype) определяет в каком виде форма создана в теле plugin-программы, то есть экземпляром какого класса она является (в .NET это System.Windows.Forms.Control или System.Windows.Forms.Form, а в Win32 - имеет ли собственную рамку или встраивается в другие окна). В зависимости от этого клиентское приложение Oktell по-разному организует их отображение в диалоговом режиме. Оконные формы отображаются в собственной рамке, а контрольные размещаются в стандартном операторском диалоговом окне Oktell. Серверные компоненты не имеют визуального содержимого. Этот параметр для них можно не указывать, или указывать равным «2» или «none».

Первый рисунок - пример формы на базе Control, отображенной в режиме операторского диалога в стандартном для этого окне приложения Oktell.

Второй рисунок - формы на базе Form. Понятно, что она может принимать любой вид.

Вариант использования (module) указывает приложению Oktell, где описываемую форму можно применять в настройках. Очевидно, одна и та же визуальная форма может в принципе быть использована в обоих режимах (операторские диалоговые окна и доступные через меню модули интерфейса). Но в описываемом интерфейсе взаимодействия производится их четкое разделение. Поэтому в случае подобной задачи на уровне объекта управления необходимо приложению Oktell указывать о наличии двух разных форм с разными идентификаторами, а при создании возвращать экземпляры одного класса. Возвращать же одни и те же экземпляры по запросам разных форм не рекомендуется, и делать необходимо крайне осмотрительно, так как при допущении ошибок в проекте итоговые окна могут исчезать и появляться в используемых местах непрогнозируемым образом.

Адрес справки (helplink) используется для режима модулей интерфейса и определяет веб-страницу (или раздел в файле справки), которая будет отображена при щелчке мышью на пиктограмму с вопросительным знаком в поле пункта меню главного окна клиентского приложения, соответствующего описываемой plugin-форме. Если адрес не задан, пиктограмма для пункта меню не отображается. Ссылка может быть адресом веб-страницей или веб-сервиса, а также ссылкой на раздел в некотором файле справки. Поиск файла будет осуществляться в основном каталоге клиентского приложения (его обновление производится стандартным способом через каталог LiveUpdate с обновлениями), и в каталоге с plugin-программой (для использования этого способа при регистрации plugin-программы через архив или вручную файл должен быть размещен в основной каталог plugin-программы). Примеры задания ссылки на автономно доступный файл справки: «plugin1_manual.chm», «manual.chm::/topic.htm#anchor», «form1.htm».

На сервере могут исполняться только компоненты, имеющие невизуальное представление (формы с controltype=2 или controltype=none), и обозначенные для использования в составе сценариев (module=2 или module=scriptcomponent). При работе с такими компонентами сервером используются также интерфейсные методы GetInputParams, GetOutputParams и PrepareShow.

Пример возвращаемого значения.

В представленном примере из демонстрационной plugin-программы объявлены и реализованы пять стартовых plugin-форм: две для использования в диалоговом режиме и три для использования в режиме отображения внешних модулей.

<?xml version="1.0" encoding="utf-16"?>
 <oktellxmlmapper version="80710">
 <data name="availableforms" count="5">
   <property_set>
     <property_simple key="id" value="a69f5237-77ef-47fd-97d7-64e0da1c0457" />
     <property_cdata key="name"><![CDATA[Операторская форма 1]]></property_cdata>
     <property_cdata key="description"><![CDATA[Демонстрационная форма для диалогового режима на базе Form]]></property_cdata>
     <property_simple key="controltype" value="0" name="form" />
     <property_simple key="module" value="0" name="dialog" />
   </property_set>
   <property_set>
     <property_simple key="id" value="87b3e68e-8e27-4e1b-b3fa-d512f5c0148f" />
     <property_cdata key="name"><![CDATA[Операторская форма 2]]></property_cdata>
     <property_cdata key="description"><![CDATA[Демонстрационная форма для диалогового режима на базе Control]]></property_cdata>
     <property_simple key="controltype" value="1" name="control" />
     <property_simple key="module" value="0" name="dialog" />
   </property_set>
   <property_set>
     <property_simple key="id" value="817d77a7-5d0e-4783-9304-e310c2ac3443" />
     <property_cdata key="name"><![CDATA[Модуль 1]]></property_cdata>
     <property_cdata key="description"><![CDATA[Демонстрационный встраиваемый модуль образца 1 на базе Control]]></property_cdata>
     <property_simple key="controltype" value="1" name="control" />
     <property_simple key="module" value="1" name="crm" />
     <property_cdata key="helplink"><![CDATA[manual.chm::/topic_pluginABC.htm#form1]]></property_cdata>
   </property_set>
   <property_set>
     <property_simple key="id" value="38a86f47-073f-4ad7-a942-6919a048ab8a" />
     <property_cdata key="name"><![CDATA[Модуль 2]]></property_cdata>
     <property_cdata key="description"><![CDATA[Демонстрационный встраиваемый модуль образца 2 на базе Control]]></property_cdata>
     <property_simple key="controltype" value="1" name="control" />
     <property_simple key="module" value="1" name="crm" />
     <property_cdata key="helplink"><![CDATA[manual.chm::/topic_pluginABC.htm#form2]]></property_cdata>
   </property_set>
   <property_set>
     <property_simple key="id" value="03e57976-b970-45ff-aec2-fa95ef274bd7" />
     <property_cdata key="name"><![CDATA[Модуль 3]]></property_cdata>
     <property_cdata key="description"><![CDATA[Демонстрационный встраиваемый модуль образца 3 на базе Form]]></property_cdata>
     <property_simple key="controltype" value="0" name="form" />
     <property_simple key="module" value="1" name="crm" />
     <property_cdata key="helplink"><![CDATA[http://www.telsystems.ru/help/plugins/demoform3.htm]]></property_cdata>
   </property_set>
  </data>
  </oktellxmlmapper>

Режим диалога (операторские формы)

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

• string GetInputParams ( string xml ). Возвращает перечень входных параметров для указанной формы (компонента).

Параметр представляет собой строку в XML формате, в которой присутствует Guid идентификатор plugin-формы.

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

Используется при настройке компонента plugin-форма в момент создания сценария диалога. Администратор, создающий сценарий, задает описанные входные значения на основе свойств, указанных в возвращаемой структуре. Возможные типы: аргументы (строковые, числовые, дата-время, общие), запросы к БД, возвращающие значения или наборы, а также перечислимые типы с возможными вариантами, описанными в структуре. В момент выполнения сценария при передаче управления компоненту Plugin-форма, выполняются вычисления всех установленных параметров, готовится XML структура, которая затем передается в плагин на отображение модуля.

Пример передаваемого параметра:

<?xml version="1.0" encoding="utf-16"?>
 <oktellxmlmapper version="80710">
 <data name="inputparams" count="1">
   <property_set name="forminput">
     <property_simple key="idplugin" value="b3daa197-f539-22f1-bc5a-8442fa9334ec" />
     <property_simple key="idform" value="a69f5237-77ef-47fd-97d7-64e0da1c0457" />     
   </property_set>   
 </data>
 </oktellxmlmapper>

Возвращаемое значение.

Каждый параметр представляет собой отдельный набор property_set в основной коллекции. Задаваемые свойства:

• paramkey - уникальное имя параметра, по которому необходимо будет производиться сопоставление, когда параметры в рабочем процессе будут переданы в форму.

• paramtype - тип параметра. Определяет способ получения значения параметра при настройке в сценарии и тип значения. Допускается 7 вариантов (1-string, 2-int, 3-datetime, 4-argument, 5-table, 6-tablequery, 7-fixedlist).

• • 1, 2, 3, 4 - задаются из формы аргумента, позволяющей выбрать константное значение, значение переменной, выражения или встроенной в диалоговый сценарий функции, различия лишь в ограничении на формат выходного значения (строка, число, строка с дата/время содержимым, произвольный аргумент).

• • 5 - возвращает некоторый набор данных из БД, задается в формате SQL создателем сценария.

• • 6 - аналогично возвращает из БД набор данных, однако задает «запрос по умолчанию». Указанный текст будет отображаться в поле ввода запроса у разработчика сценария в начале и каждый раз, когда он будет очищать это поле. Для указания текста запроса у соответствующего параметру элемента property_set задается коллекция, содержащая один подэлемент с именем «query». В нем должно присутствовать свойство property_cdata с ключом sqltext. Также допускаются свойства connectiontype, connectionstring, определяющие в случае указания соответственно направление подключения (Собственная БД, ADO, OLE, Oracle, ODBC) и строку подключения к БД. Этот тип параметра может быть использован в случае, если разработчики plugin-программы закладывают жесткую структуру взаимодействия с БД, и их квалификация существенно выше, чем у возможного разработчика сценария.

• • 7 - фиксированный список. Предлагает разработчику выбрать один из описанных в теле параметра вариантов. Для этого в соответствующем элементе property_set задается коллекция из других элементов, описывающих возможные варианты значений. Каждый описательный набор property_set имеет атрибуты name="category" и id, установленный в соответствии с идентификатором варианта. В теле описательного набора присутствуют свойства с ключами id и name. id - определяет код, который будет передан как выбранный вариант при формировании значений для передачу в форму, name - название, которое увидит разработчик сценария в списке.

• paramname - название параметра, которое увидит разработчик сценанрия.

• paramdescription - описание параметра для разработчика сценария (подробная инструкция для получения ожидаемого значения).

• paramextra - значение параметра, которое будет без изменений передано на вход в режиме выполнения. Может не быть задано.

Пример возвращаемого значения:

<?xml version="1.0" encoding="utf-16"?>
 <oktellxmlmapper version="80710">
 <data name="input" count="6">
   <property_set>
     <property_simple key="paramkey" value="operator" />
     <property_simple key="paramtype" value="1" name="string" />
     <property_cdata key="paramname"><![CDATA[Оператор]]></property_cdata>
     <property_cdata key="paramdescription"><![CDATA[Имя текущего оператора]]></property_cdata>
   </property_set>
   <property_set>
     <property_simple key="paramkey" value="clientid" />
     <property_simple key="paramtype" value="2" name="int" />
     <property_cdata key="paramname"><![CDATA[Клиент]]></property_cdata>
     <property_cdata key="paramdescription"><![CDATA[Код обрабатываемого клиента]]></property_cdata>
    <property_simple key="paramextra" value="500" />
   </property_set>
   <property_set>
     <property_simple key="paramkey" value="queuetime" />
     <property_simple key="paramtype" value="4" name="argument" />
     <property_cdata key="paramname"><![CDATA[Время в очереди]]></property_cdata>
     <property_cdata key="paramdescription"><![CDATA[Будет отображено на форме без анализа]]></property_cdata>
   </property_set>
   <property_set>
     <property_simple key="paramkey" value="products" />
     <property_simple key="paramtype" value="5" name="table" />
     <property_cdata key="paramname"><![CDATA[Текущие товары]]></property_cdata>
     <property_cdata key="paramdescription"><![CDATA[Набор товаров запросом из БД (Id, Name, Set)]]></property_cdata>
   </property_set>   
   <property_set>
     <property_simple key="paramkey" value="users" />
     <property_simple key="paramtype" value="6" name="tablequery" />
     <property_cdata key="paramname"><![CDATA[Пользователи]]></property_cdata>
     <property_cdata key="paramdescription"><![CDATA[Пользователи (Id, Name)]]></property_cdata>
     <property_collection name="query" count="1">
       <property_set name="query">
         <property_simple key="connectiontype" value="1" name="sql" />
         <property_simple key="connectionstring" value="" />
         <property_cdata key="sqltext"><![CDATA[Select Id, Name From A_Users]]></property_cdata>
       </property_set>
     </property_collection>
   </property_set>
   <property_set>
     <property_simple key="paramkey" value="categories" />
     <property_simple key="paramtype" value="7" name="fixedlist" />
     <property_cdata key="paramname"><![CDATA[Категории]]></property_cdata>
     <property_cdata key="paramdescription"><![CDATA[Направление работы]]></property_cdata>
     <property_collection name="categories" count="2">
       <property_set name="category" id="0">
         <property_simple key="id" value="0" />
         <property_cdata key="name"><![CDATA[Товары]]></property_cdata>
       </property_set>
       <property_set name="category" id="1">
         <property_simple key="id" value="1" />
         <property_cdata key="name"><![CDATA[Услуги]]></property_cdata>
       </property_set>
     </property_collection>
   </property_set>
 </data>
 </oktellxmlmapper>

• string GetOutputParams ( string xml ). Возвращает перечень выходных параметров для указанной формы (компонента).

Параметр представляет собой строку в XML формате, в которой присутствует Guid идентификатор plugin-формы.

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

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

Пример передаваемого параметра:

<?xml version="1.0" encoding="utf-16"?>
 <oktellxmlmapper version="80710">
 <data name="outputparams" count="1">
   <property_set name="formoutput">
     <property_simple key="idplugin" value="b3daa197-f539-22f1-bc5a-8442fa9334ec" />
     <property_simple key="idform" value="a69f5237-77ef-47fd-97d7-64e0da1c0457" />     
   </property_set>   
 </data>
 </oktellxmlmapper>

Возвращаемое значение.

Каждый параметр представляет собой отдельный набор property_set в основной коллекции. Обязательными являются свойства:

• paramkey - уникальное имя параметра, по которому необходимо будет производиться сопоставление, когда параметры в рабочем процессе будут переданы в форму.

• paramtype - тип параметра. Определяет способ получения значения параметра при настройке в сценарии и тип значения. Допускается 4 варианта (1-string, 2-int, 3-datetime, 4-variable). Влияют на формат выбора переменной для сохранения значения. Соответственно для выбора предоставляется список только строковых переменных, только числовых, только переменных дата/время или список всех переменных.

• paramname - название параметра, которое увидит разработчик сценанрия.

• paramdescription - описание параметра для разработчика сценария (подробная инструкция для получения ожидаемого значения).

Пример возвращаемого значения:

<?xml version="1.0" encoding="utf-16"?>
 <oktellxmlmapper version="80710">
 <data name="output" count="3">
   <property_set>
     <property_simple key="paramkey" value="selectedproduct" />
     <property_simple key="paramtype" value="2" name="int" />
     <property_cdata key="paramname"><![CDATA[Выбранный товар]]></property_cdata>
     <property_cdata key="paramdescription"><![CDATA[Код (id) выбранного товара]]></property_cdata>
   </property_set>
   <property_set>
     <property_simple key="paramkey" value="info" />
     <property_simple key="paramtype" value="4" name="variable" />
     <property_cdata key="paramname"><![CDATA[Текст уведомления]]></property_cdata>
     <property_cdata key="paramdescription"><![CDATA[Для отображения следующим компонентом в сценарии после завершения работы с формой]]>
   </property_cdata>
   </property_set>
   <property_set>
     <property_simple key="paramkey" value="dt" />
     <property_simple key="paramtype" value="3" name="datetime" />
     <property_cdata key="datetimeformat"><![CDATA[dd.MM.yyyy HH:mm:ss]]></property_cdata>
     <property_cdata key="paramname"><![CDATA[Время]]></property_cdata>
     <property_cdata key="paramdescription"><![CDATA[Время, установленное для следующей связи]]></property_cdata>
   </property_set>
 </data>
 </oktellxmlmapper>

• string ShowDesign ( string xml ). Вызывается для отображения диалоговой plugin-формы в «демонстрационном» режиме без передачи установленных для нее входных параметров.

В строковом параметре находится XML структура с указанием Guid идентификатора интересующей формы. Если в параметре передан верный идентификатор - метод должен отобразить окно с формой в диалоговом режиме (с возвратом управления только после ее закрытия). Если указан неверный параметр - должен сразу вернуть управление.

Возвращается структура с описанием кода возврата.

Может быть вызвана только в момент создания сценария. Реализация метода plugin-программы для отображения диалоговых plugin-форм c CONTROLTYPE = FORM (оконные) может совпадать с реализацией метода PrepareShow. Для отображения же plugin-форм с CONTROLTYPE = CONTROL (встраиваемые контролы) реализация должна предусматривать создание и размещение такой формы на внутреннем окне и вывод его на экран командой ShowDialog().

Пример передаваемого параметра:

<?xml version="1.0" encoding="utf-16"?>
 <oktellxmlmapper version="80710">
 <data name="design" count="1">
   <property_set name="showformdesign">
     <property_simple key="idplugin" value="b3daa197-f539-22f1-bc5a-8442fa9334ec" />
     <property_simple key="idform" value="a69f5237-77ef-47fd-97d7-64e0da1c0457" />     
   </property_set>   
 </data>
 </oktellxmlmapper>

В качестве возвращаемого значения после закрытия формы должно вернуться описание результата. В случае если результат (свойство property_simple с ключом resultcode) не возвращает {"0", "success"}, текст результата из свойства property_cdata c ключом resultdescription будет отображен во всплывающем уведомлении.

• string PrepareShow ( string xml ). Вызывается для отображения операторской диалоговой plugin-формы в рабочем режиме.

Метод осуществляет создание, подготовку и отображение окна с формой в диалоговом режиме (с возвратом управления только после ее закрытия). Вызывается только в режиме операторских диалогов (module = "dialog") для оконных форм (controltype = "form").

Передаваемый параметр.

В качестве параметра - строка с XML содержимым. В нем в нескольких разделах перечислены

• Блок common. Общие данные по задаче, сценарию, абоненту, оператору, текущему комментарию, Guid идентификаторы plugin-программы и plugin-формы. Имеет жесткую структуру содержимого. Свойство idshow задает уникальный код экземпляра отображения - по нему будет запрашиваться закрытие и возврат значений.

• Блок input. Значения для входных параметров в установленном формате. Структура содержимого состоит из наборов, описывающих входные параметры. Их количество и формат определяются на основе данных,

• Блок fillinfo. Информация о наполнении (этапе). При переводе формы от одного оператора к другому у первого окно с формой закрывается, возвращая строку (любого формата) с неким содержимым. Это содержимое будет передано в управляющий объект plugin-программы в клиентском приложении второго оператора как часть структуры в параметре данного метода PrepareShow. См. также описание метода GetCurrentFillInfo. Блок может отсутствовать.

В приведенном примере передаваемого параметра отмеченные зеленым цветом комментарии разделяют описанные зоны.

<?xml version="1.0" encoding="utf-16"?>
 <oktellxmlmapper version="80710">
 <data name="prepareparams" count="3">

<!-- ###################################################### -->
<!--        Раздел COMMON с общими параметрами              -->
<!-- ###################################################### -->
  <property_set name="сommon">
     <property_cdata key="idplugin"><![CDATA[b3daa197-f539-22f1-bc5a-8442fa9334ec]]></property_cdata>
     <property_cdata key="idform"><![CDATA[a69f5237-77ef-47fd-97d7-64e0da1c0457]]></property_cdata>
     <property_cdata key="iduser"><![CDATA[da803f01-ea77-40fa-bc9d-e2efb36fd5a8]]></property_cdata>
     <property_simple key="allowstop" value="1" />
     <property_simple key="showontop" value="1" />
     <property_cdata key="comment"><![CDATA[Тело комментария]]></property_cdata>
     <property_cdata key="taskname"><![CDATA[Обработка входящих]]></property_cdata>
     <property_simple key="idshow" value="8bc38a2a-5faa-4c75-864e-2f4e6723f1fd" />
     <property_collection count="2">
       <property_set name="clientinfo">
         <property_collection name="fields" count="3">
           <property_set id="0" name="field">
             <property_cdata key="fieldname"><![CDATA[Название]]></property_cdata>
             <property_cdata key="fieldvalue"><![CDATA[ООО "Гульчатай"]]></property_cdata>
           </property_set>
           <property_set id="1" name="field">
             <property_cdata key="fieldname"><![CDATA[Телефон]]></property_cdata>
             <property_simple key="fieldvalue" value="3214567" />
           </property_set>
           <property_set id="3" name="field">
             <property_cdata key="fieldname"><![CDATA[Контактное лицо]]></property_cdata>
             <property_cdata key="fieldvalue"><![CDATA[Веселовский Пал Виталич]]></property_cdata>
           </property_set>
         </property_collection>
       </property_set>
     </property_collection>
   </property_set>
 
<!-- ###################################################### -->
<!--        Раздел INPUT с заказанными параметрами          -->
<!-- ###################################################### -->
  <property_set name="input">
     <property_collection count="6">
       <property_set name="parameter" id="clientid">
         <property_simple key="paramkey" value="clientid" />
         <property_simple key="paramtype" value="1" />
         <property_simple key="paramextra" value="500" />
         <property_simple key="paramvalue" value="822" />
       </property_set>
       <property_set name="parameter" id="operator">
         <property_simple key="paramkey" value="operator" />
         <property_simple key="paramtype" value="1" />
         <property_simple key="paramextra" value="" />
         <property_cdata key="paramvalue"><![CDATA[Иванов Анатолий]]></property_cdata>
       </property_set>
       <property_set name="parameter" id="categories">
         <property_simple key="paramkey" value="categories" />
         <property_simple key="paramtype" value="7" />
         <property_simple key="paramextra" value="" />
         <property_simple key="paramvalue" value="0" />
       </property_set>
       <property_set name="parameter" id="queuetime">
         <property_simple key="paramkey" value="queuetime" />
         <property_simple key="paramtype" value="4" />
         <property_simple key="paramextra" value="" />
         <property_simple key="paramvalue" value="1,4142135623731" />
       </property_set>
 
.....................................................................................
Табличный параметр. 
Имеет большой достаточно объем описательного текста даже при небольшом объеме данных
Его формат будет описан отдельно в пункте OnQuery
.....................................................................................
 
      <property_set name="parameter" id="products">
         <property_simple key="paramkey" value="products" />
         <property_simple key="paramtype" value="5" />
         <property_simple key="paramextra" value="" />
         <property_collection name="table" count="2">
           <property_set name="tableheader">
             <property_collection name="columns" count="3">
               <property_set name="columninfo" id="0">
                 <property_simple key="index" value="0" />
                 <property_simple key="name" value="id" />
                 <property_simple key="typename" value="Int32" />
                 <property_cdata key="typefullname"><![CDATA[System.Int32]]></property_cdata>
               </property_set>
               <property_set name="columninfo" id="1">
                 <property_simple key="index" value="1" />
                 <property_simple key="name" value="name" />
                 <property_simple key="typename" value="String" />
                 <property_cdata key="typefullname"><![CDATA[System.String]]></property_cdata>
               </property_set>
               <property_set name="columninfo" id="2">
                 <property_simple key="index" value="2" />
                 <property_simple key="name" value="st" />
                 <property_simple key="typename" value="Boolean" />
                 <property_cdata key="typefullname"><![CDATA[System.Boolean]]></property_cdata>
               </property_set>
             </property_collection>
           </property_set>
           <property_set name="tabledata">
             <property_collection name="rows" count="2">
               <property_set name="row" id="0">
                 <property_collection name="cells" count="3">
                   <property_set name="cell" id="0">
                     <property_simple key="cellvalue" value="1" />
                   </property_set>
                   <property_set name="cell" id="1">
                     <property_simple key="cellvalue" value="qwer" />
                   </property_set>
                   <property_set name="cell" id="2">
                     <property_simple key="cellvalue" value="1" />
                   </property_set>
                 </property_collection>
               </property_set>
               <property_set name="row" id="1">
                 <property_collection name="cells" count="3">
                   <property_set name="cell" id="0">
                     <property_simple key="cellvalue" value="2" />
                   </property_set>
                   <property_set name="cell" id="1">
                     <property_simple key="cellvalue" value="wert" />
                   </property_set>
                   <property_set name="cell" id="2">
                     <property_simple key="cellvalue" value="1" />
                   </property_set>
                 </property_collection>
               </property_set>
             </property_collection>
           </property_set>
         </property_collection>
       </property_set>
 
.....................................................................................
 
    </property_collection>
  </property_set>
 
<!-- ###################################################### -->
<!--   Раздел FILLINFO с информацией об этапе/заполнении    -->
<!-- ###################################################### -->
  <property_set name="fillinfo">
    <property_cdata key="fillinfo"><![CDATA[произвольная строка в любом формате от XML до B64]]></property_cdata>
  </property_set>
</data>
</oktellxmlmapper>

Возвращаемое значение.

В возвращаемой строке с XML содержимым должна присутствовать структура со значениями в двух разделах:

• Блок common. Новое значение комментария (передаваемого из формы в форму и от оператора к оператору), а также значение результата выполнения. По аналогии со стандартом операторского диалогового окна допускается два вида результатов: переход по кнопке Далее к следующему компоненту сценария с сохранением выходных значений в переменных сценария, а также остановка сценария кнопкой Стоп без сохранения выходных значений формы в переменных.

• Блок output. Набор, описывающий значения выходных параметров. Они будут применены в обработчике сценариев на сервере для сохранения в соответствующих переменных, указанных при настройке компонента «Plugin-форма».

В приведенном примере возвращаемого значения отмеченные зеленым цветом комментарии разделяют описанные зоны.

<?xml version="1.0" encoding="utf-16"?>
 <oktellxmlmapper version="80710">
 <data name="result" count="2">
<!-- ###################################################### -->
<!--   Раздел COMMON с общеий информацией о результате      -->
<!-- ###################################################### -->
  <property_set name="common">
    <property_cdata key="comment"><![CDATA[теперь вот такой комментарий]]></property_cdata>
    <property_simple key="result" value="next" />
  </property_set>
<!-- ###################################################### -->
<!--   Раздел OUTPUT со значениями выходных параметров      -->
<!-- ###################################################### -->
  <property_set name="output">
    <property_collection count="3">
      <property_set name="parameter" id="selectedproduct">
        <property_simple key="paramkey" value="selectedproduct" />
        <property_simple key="paramtype" value="2" name="int" />
        <property_simple key="paramvalue" value="12345555" />
      </property_set>
      <property_set name="parameter" id="info">
        <property_simple key="paramkey" value="info" />
        <property_simple key="paramtype" value="4" name="variable" />
        <property_cdata key="paramvalue"><![CDATA[выходное значение!!!]]></property_cdata>
      </property_set>
      <property_set name="parameter" id="dt">
        <property_simple key="paramkey" value="dt" />
        <property_simple key="paramtype" value="3" name="datetime" />
        <property_cdata key="datetimeformat"><![CDATA[dd.MM.yyyy HH:mm:ss]]></property_cdata>
        <property_cdata key="paramvalue"><![CDATA[01.12.2008 7:43:10]]></property_cdata>
      </property_set>
    </property_collection>
  </property_set>
</data>
</oktellxmlmapper>

• string GetCurrentFillInfo ( string xml ). Вызывается для определения текущего наполнения формы (этапа) и последующего перевода формы на другого оператора в том виде, в котором она находится у текущего оператора.

Строковый параметр в XML структуре определяет код интересующей формы (хотя диалоговый режим поддерживает отображение только одной операторской диалоговой формы единовременно).

Возвращаемое значение может иметь любой формат и будет без разбора передано как часть структуры входного параметра (блок fillinfo) в метод PrepareShow или CreateControl на компьютере оператора, принимающего переведенный вызов.

Пример передаваемого параметра:

<?xml version="1.0" encoding="utf-16"?>
 <oktellxmlmapper version="80710">
 <data name="close" count="1">
   <property_set name="forminfo">
     <property_simple key="idplugin" value="b3daa197-f539-22f1-bc5a-8442fa9334ec" />
     <property_simple key="idform" value="a69f5237-77ef-47fd-97d7-64e0da1c0457" />     
     <property_simple key="idshow" value="e161da32-c52a-5515-e692-34bb1236a62d" />     
   </property_set>   
 </data>
 </oktellxmlmapper>

Пример возвращаемого значения:

произвольная строка в любом формате от XML до B64

• string StopShow ( string xml ). Вызывается для принудительного закрытия диалоговой формы с CONTROLTYPE = FORM (оконные). Это может происходить в случае перевода звонка и соответствено формы на другого оператора (предварительно вызывается GetCurrentFillInfo) или в случае принудительного завершения диалогового сценария (по настройкам системы).

Строковый параметр в XML структуре определяет код интересующей формы (хотя диалоговый режим поддерживает отображение только одной операторской диалоговой формы единовременно).

Возвращается структура, содержащая значение комментария.

Пример передаваемого параметра:

<?xml version="1.0" encoding="utf-16"?>
 <oktellxmlmapper version="80710">
 <data name="close" count="1">
   <property_set name="forminfo">
     <property_simple key="idplugin" value="b3daa197-f539-22f1-bc5a-8442fa9334ec" />
     <property_simple key="idform" value="a69f5237-77ef-47fd-97d7-64e0da1c0457" />     
     <property_simple key="idshow" value="e161da32-c52a-5515-e692-34bb1236a62d" />     
   </property_set>   
 </data>
 </oktellxmlmapper>

Пример возвращаемого значения:

<?xml version="1.0" encoding="utf-16"?>
 <oktellxmlmapper version="80710">
 <data name="result" count="1">
   <property_set name="common">
     <property_cdata key="comment"><![CDATA[Новое значение комментария]]></property_cdata>
   </property_set>   
 </data>
 </oktellxmlmapper>

• string GetControlResult ( string xml ). Вызывается для получения XML структуры со значениями выходных переменных для форм с CONTROLTYPE = CONTROL (контрольные). Поскольку отображение таких форм производится приложением Oktell (в отличие от оконных форм plugin-программы, для которых вызывается метод PrepareShow, осуществляющий подготовку, отображение и возврат управления вместе с описываемой структурой значений выходных параметров в контексте самой plugin-программы).

Строковый параметр в XML структуре определяет код интересующей формы (хотя диалоговый режим поддерживает отображение только одной операторской диалоговой формы единовременно).

Возвращаемое значение - XML структура установленного образца с содержимым, соответствующим значениям выходных параметров plugin-формы, структура и состав полностью аналогичны соответствующему возвращаемому значению метода PrepareShow.

Пример передаваемого параметра:

<?xml version="1.0" encoding="utf-16"?>
 <oktellxmlmapper version="80710">
 <data name="controlresult" count="1">
   <property_set name="getresult">
     <property_simple key="idplugin" value="b3daa197-f539-22f1-bc5a-8442fa9334ec" />
     <property_simple key="idform" value="a69f5237-77ef-47fd-97d7-64e0da1c0457" />
     <property_simple key="idshow" value="a26a4540-6bee-4986-8098-adf340d3faa1" />
   </property_set>   
 </data>
 </oktellxmlmapper>

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

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

• System.Windows.Forms.Control CreateControl ( string xml ). Используется и в режиме диалога, и в режиме подключения внешних модулей (CRM).

В режиме диалога вызывается для создания и подготовки формы с CONTROLTYPE = CONTROL (контрольные).

Входной параметр представляет собой строку с комплексным XML параметром, который в зависимости от режима использования имеет тот или иной формат. В режиме диалога содержимое параметра аналогично содержимому одноименного параметра метода PrepareShow, содержит однотипные разделы и служит для настройки требуемого отображения.

Возвращает созданный экземпляр контрола, который затем размещается в стандартном операторском диалоговом окне Oktell.

В режиме модулей CRM параметр имеет один и тот же вид: в содержимом XML структуры передаются идентификаторы plugin-программы, plugin-формы, экземпляра plugin-формы, а также информация о пользователе, рабочем месте, и т.д. Какие из переданных параметров использовать - дело управляющего объекта.

Возвращает созданный экземпляр окна (оконной формы), которое затем размещается среди других внешних модулей.

ВНИМАНИЕ: Окно представляет собой .NET форму (System.Windows.Forms.Form), которая в классовой структуре FrameWork является потомком System.Windows.Forms.Control.

Значение передаваемого параметра при использовании в режиме диалога полностью совпадает с параметром функции PrepareShow.

Пример параметра при создании для подключения среди внешних модулей (CRM):

<?xml version="1.0" encoding="utf-16"?>
 <oktellxmlmapper version="80710">
 <data name="info" count="3">
   <property_set name="user">
     <property_simple key="id" value="da803f01-ea77-40fa-bc9d-e2efb36fd5a8" />
     <property_cdata key="name"><![CDATA[Иванов Анатолий]]></property_cdata>
     <property_simple key="login" value="Ivanov" />
     <property_simple key="password" value="si4255" />
     <property_simple key="isoperator" value="1" />
     <property_simple key="issupervisor" value="1" />
     <property_simple key="isadmin" value="0" />
     <property_simple key="departmentid" value="c4e3b424-3048-4cce-a2e4-033c532a7d99" />
     <property_cdata key="departmentname"><![CDATA[Маркетинг]]></property_cdata>
   </property_set>
   <property_set name="workplace">
     <property_simple key="id" value="de609bc7-6d3b-4daf-a418-a1d0648d7784" />
     <property_cdata key="name"><![CDATA[Marketing1]]></property_cdata>
     <property_simple key="hasphone" value="1" />
   </property_set>
   <property_set name="link">
     <property_simple key="idshow" value="2e2d8ff0-de47-415f-ab68-9bddcd09952b" />
     <property_simple key="idplugin" value="b3daa197-f539-22f1-bc5a-8442fa9334ec" />
     <property_simple key="idform" value="03e57976-b970-45ff-aec2-fa95ef274bd7" />
     <property_cdata key="linktext"><![CDATA[Форма 3 экз 1]]></property_cdata>
     <property_cdata key="headertext"><![CDATA[Демка, Форма 3 экз 1]]></property_cdata>
     <property_cdata key="description"><![CDATA[Описание пункта меню, задаваемое администратором]]></property_cdata>
     <property_cdata key="address"><![CDATA[Демонстрационный плагин / Модуль 3]]></property_cdata>
   </property_set>
 </data>
 </oktellxmlmapper>

Использование в сценариях сервера

Возможно использование плагина в составе с серверной службой. Исполнение протекает посредством передачи управления сценариями внешним модулям через компонент «Плагин», доступный во всех типах сценариев системы. Передача управления происходит путем вызова метода PrepareShow, с передачей XML-параметра и ожиданием возврата XML-ответа. В составе параметра передается вся контекстная информация из сценария (зависит от типа исполняемого сценария), а также перечень значений для всех требуемых входных параметров, указанных в возвращаемом значении метода GetInputParams. Значения входных параметров вычисляются в ходе реализации сценария. Соответствующие аргументы назначаются в редакторе сценариев при модификации компонента «Плагин». Там же происходит назначение переменных сценария для приема возвращаемых значений. Список возвращаемых значений, их кодов и типов определяется методом GetOutputParams.

Структура параметров и возвращаемых значений при вызове методов GetInputParams и GetOutputParams в контексте работы с компонентами для серверных сценариев абсолютно идентична структуре при работе в режиме диалога. В качестве idform передается идентификатор соответствующего компонента.

Структура возвращаемого значения метода PrepareShow также идентична при работе в режиме диалога и в режиме сценариев. Передаваемый параметр в отличие от режима диалога имеет отличия в разделе common (контекстная информация сценария) и лишен блока fillinfo.

Подробно о параметрах в описании соответствующих методов.

Сервисное взаимодействие

Методы и события данного раздела служат для осуществления плотного взаимодействия plugin-программы и клиентского приложения Oktell. XML-содержимое описывает не только параметры, но и само действие (действия в общем случае). Не изменяя интерфейса подключения plugin-программ при помощи этих методов будут расширяться возможности взаимодействия, добавляться новые сервисы в клиентское приложение Oktell для использования в plugin-программах.

• event PluginQueryInvoker OnQuery. Событие управляющего объекта, обрабатываемое в клиентском приложении Oktell. Служит для выполнения сервисных специальных запросов в клиентском приложении Oktell по инициативе plugin-программы или какой либо из ее plugin-форм. Результат выполнения попадает в управляющий объект как возвращаемое значение метода-обработчика. Параметр и возвращаемое значение представляют собой строки с XML-содержимым. Некоторые запросы должны обязательно содержать указание идентификатора plugin-формы и ее экземпляра, переданные через параметр метода CreateControl в момент создания.

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

Именно этот режим будет претерпевать изменения и дополняться при необходимости развития.

Описание структуры параметров обширно и приведено в отдельной статье «Сервисное взаимодействие».

• string DoQuery ( string xml ). Событие приложения Oktell, обрабатываемое в управляющем объекте plugin-программы. Служит для выполнения сервисных специальных запросов в plugin-программе. Какие из них использовать и использовать ли вообще - дело управляющего объекта. Параметр и возвращаемое значение представляют собой строки с XML-содержимым.

Например в управляющий объект передаются события о смене активной вкладки в заголовке (сами вкладки появляются в приложении Oktell по событию OnQuery управляющего объекта). В управляющий объект также попадают события об отображении или скрытия той или иной формы, так как может потребоваться обновление данных, инициирование или остановка каких-либо таймеров и т.д.

Описание структуры параметров обширно и приведено в отдельной статье «Сервисное взаимодействие».