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

Материал из Oktell
Перейти к: навигация, поиск
(Новая страница: «Наверх __TOC__ Поскольку методы выполняются управляющим объекто...»)
 
Строка 302: Строка 302:
  
  
−
string ShowDesign ( string xml )
+
*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 управляющего объекта). В управляющий объект также попадают события об отображении или скрытия той или иной формы, так как может потребоваться обновление данных, инициирование или остановка каких-либо таймеров и т.д.
 +
 
 +
Описание структуры параметров обширно и приведено в отдельной статье «Сервисное взаимодействие».

Версия 07:08, 31 марта 2014

Наверх

Поскольку методы выполняются управляющим объектом 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">

  <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>

</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.


center


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


center


Вариант использования (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"> 

 <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[1]]></property_cdata>
 </property_set>

</oktellxmlmapper>


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

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

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

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

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

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

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

<?xml version="1.0" encoding="utf-16"?> <oktellxmlmapper version="80710"> 

 <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>

</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"> 

 <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>

</oktellxmlmapper>


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

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

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

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

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

<?xml version="1.0" encoding="utf-16"?> <oktellxmlmapper version="80710"> 

 <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>

</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"> 

 <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>

</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"> 

 <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>

</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"> 

 <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>

 <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>

 <property_set name="fillinfo">
   <property_cdata key="fillinfo"><![CDATA[произвольная строка в любом формате от XML до B64]]></property_cdata>
 </property_set>

</oktellxmlmapper>


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

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

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


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

<?xml version="1.0" encoding="utf-16"?> <oktellxmlmapper version="80710"> 

 <property_set name="common">
   <property_cdata key="comment"><![CDATA[теперь вот такой комментарий]]></property_cdata>
   <property_simple key="result" value="next" />
 </property_set>
 <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>

</oktellxmlmapper>


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

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

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

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

<?xml version="1.0" encoding="utf-16"?> <oktellxmlmapper version="80710"> 

 <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>

</oktellxmlmapper>

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

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


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

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

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

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

<?xml version="1.0" encoding="utf-16"?> <oktellxmlmapper version="80710"> 

 <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>

</oktellxmlmapper>

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

<?xml version="1.0" encoding="utf-16"?> <oktellxmlmapper version="80710"> 

 <property_set name="common">
   <property_cdata key="comment"><![CDATA[Новое значение комментария]]></property_cdata>
 </property_set>

</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"> 

 <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>

</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"> 

 <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>

</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 управляющего объекта). В управляющий объект также попадают события об отображении или скрытия той или иной формы, так как может потребоваться обновление данных, инициирование или остановка каких-либо таймеров и т.д.

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

Источник — «https://wiki.oktell.ru/index.php?title=Описание_базовых_элементов_интерфейса&oldid=8101»