Содержание
Для работы Agami требуется среда исполнения Microsoft .NET Framework 1.1 SP1.
Скачать необходимые файлы можно здесь:
Для начала работы вам необходимо установить продукт. Его дистрибутив поставляется в виде файла msi.
Название файла дистрибутива содержит номер версии. Например, для версии 0.5.6 файл будет называться ShtrihM.Agami.Common-0.5.6.msi.
После установки в папке Program Files появляются две новые папки Agami и Pinicola, а также сервис Agami.
В дистрибутив Agami входят следующие продукты:
Сервис бизнес-логики Agami
Пользовательский интерфейс Pinicola
Конфигуратор Xenus
Сервис бизнес-логики Agami выполняет следующие задачи: работа с аппаратной частью, связь с платежным сервером и сервером технического мониторинга и предоставления механизма для создания пользовательского интерфейса. Это означает, что сам сервис Agami не занимается выводом пользовательского интерфейса, он лишь предоставляет набор сервисов, при помощи которых внешне приложение может организовать, например, прием платежей.
Сервис Agami построен по модульному принципу. Главной задачей непосредственно сервиса Agami является загрузка модулей, их конфигурация и предоставление сервисов этих устройств для приложения пользовательского интерфейса.
В Agami определены следующие виды плагинов:
Принтера
Купюроприемника
Карточек
Устройства связи
Платежной системы
Преобразователя запросов платежной системы
Технического мониторинга
Устройства общего назначения
Большинство из этих плагинов являются обязательными и должны быть определены в конфигурации один раз. К таким плагинам относятся все плагины специалазарованных устройств, таких как принтер и купюроприемник, а также плагины платежной системы и технического мониторинга. Если в вашей конфигурации отсутствует одно или несколько устройств или вам не доступен сервис технического мониторинга, вам необходимо использовать плагин-заглушку соответсвтующего типа. Плагины-заглушки не выполняют никакой полезной работы, но они необходимы так как Agami рассчитывает на присутсвие данного типа плагина. Плагины устройств общего назначения и преобразователи запросов платежной системы могут присутствовать в системе в любом количестве или отсутствовать вообще.
Во время запуска Agami загружает и инициализирует все плагины, определенные в конфугации. Идентификатором плагина является имя сборки, определенное в атрибуте assembly. Все плагины, поставляемые в комплекте Agami, устанавливаются в Global Assembly Cash, или скоращенно GAC, откуда к ним можно обратиться, используя полное имя сборки. В полное имя сборки входит, помимо названия файла, номер версии сборки, публичный ключ подписи и иформация о языке. Обратите внимание, что в разных версиях Agami стандартные плагины имеют разные полные имена сборок. По этой причине вы не можете использовать файлы конфигурации, предназначенные для другой версии продукта.
Если во время запуска один из плагинов не может быть инициализирован, запуск Agami прекращается. Основными причинами сбоя при запуске являются ошибки в конфигурации и сбои в работе устройств. Во время работы ведется лог событий, в том числе ошибок. Поскольку запуск Agami прекращается после первой ошибки, вы сможете увидеть диагностическое сообщение ближе к концу лог-файла. Если лог-файл не создается или в него не добавляются новые сообщения после запуска, то скорее всего у вас ошибка синтаксиса XML в файле конфигурации.
После успешной загрузки всех плагинов Agami запускает приложение пользовательского интерфейса Pinicola и следит за его выполнением. В случае закрытия приложения пользовательского интерфейса, Agami заново запускает это приложение.
Как вы уже заметили, сервис Agami не определяет процесс приема платежей, эту задачу выполняет пользовательский интерфейс Pinicola. Ни Pinicola, ни Agami не накладывают почти никаких ограничений на использование возможностей Agami и с его помощью можно решить задачи связанные не только с приемом платежей, но и, например, с работой с банковскими картами. Словом, все, для чего может потребоваться купюроприемник, принтер и платежный сервер.
Логика работы и оформление графического интерфейса загружаются из файла описания Interface.xml. В этом файле содержатся описания ресурсов (графика, звук), экранов интерфейса и скриптов обработчиков событий.
Во время запуска Pinicola загружает файл Interface.xml и все связанные с ним ресурсы в память, после чего пытается установить связь с сервисом Agami. В случае ошибки загрузки файла Inteface.xml на экран выводится сообщение "Терминал временно не работает" на синем фоне. Если Pinicola не может загрузить графику, то вместо изображения будет использована заглушка, которую рисует графический элемент использующий это изображение.
При невозможности установления соединения с сервисом Agami, Pinicola завершает свою работу. Такое поведение было заложено из-за того, что для создания канала связи иногда требуется продолжительное время и Pinicola может попытаться соединиться с Agami до его установления. Через некоторое время Agami должна снова попытаться запустить приложение пользовательского интерфейса, так как это считается нештатным завершением работы.
Для повышения удобства конфигурирования Agami было создано приложение Xenus, но, к сожалению, при выполнении несандартных задач вам все же придется прибегнуть к ручному конфигурированию файлов конфигурации.
Конфигуратор Xenus также построен по принципу плагинов, каждый из которых позволяет конфигурировать свою часть Agami. Со всеми стандартными плагинами Agami поставляется плагин Xenus, позволяющий их конфигурировать.
При помощи конфигуратора Xenus вы можете отконфигурировать общие настройки, выбрать и настроить плагины, а также запустить и остановить сервис Agami.
Поздравляю, вы установили Agami на терминал и теперь не знаете, что делать. Самое время заняться конфигурированием.
Конфигурирование Agami можно разбить на три основных этапа:
Конфигурирование драйверов устройств
Конфигурирование стандартных параметров
Нестандартное конфигугирование, опционально
Конфигурирование устройств подробно описано в документации к вашему терминалу.
Внимание! После того, как вы сконфигурировали все драйверы устройств необходимо запустить скрипт RegCopy.bat для того, чтобы скопировать настройки драйверов в ветку системного реестра, доступную сервису Agami. Эту операцию необходимо проводить после каждого изменения настроек драйверов.
Для конфигурирования стандартных параметров можно использовать конфигуратор Xenus. С помощью конфигуратора Xenus вы можете настроить общие параметры терминала, а также выбрать и настроить плагины Agami.
В левой части окна конфигуратора Xenus располагается список категорий конфигурирования. После выбора категории в правой части окна отображается сводная страница информации о разделе. В ней вы можете выбрать тип плагина, если доступно несколько вариантов, удалить секцию информации о плагине и изменить настройки плагина.
Для замены типа плагина необходимо выбрать требуемый тип плагина из выпадающего списка и, в случае несовместимости текущих настроек с новым плагином, сбросить настройки.
Вы также можете удалить настройки плагина. Agami требует обязательного присутствия общих настроек и настроек адаптеров кажого типа. Если вы не планируете использование какого-либо плагина, вам следует использовать заглушку для данного типа плагина. Заглушки имитируют присутствие адаптера, но не выполняют полезную работу.
Для приема платежей вам потребуется настроить адаптер платежной системы. В комплекте Agami поставляется плагин платежной системы Aves.
При подключении терминала к платежной системе вам должны предоставить файл PointConfig.xml, в котором описываются параметры платежной системы уникальные для данного терминала. Для внесения настроек необходимо открыть файл PointConfig.xml и перенести содержимое тегов в конфигуратор, используя таблицу соответствия имен тегов и настроек адаптера:
Таблица 1. Таблица соответствия имен тегов и настроек адаптера
| Название тега | Название настройки |
|---|---|
| ApplicationId | Идентификатор приложения |
| SenderId | Идентификатор отправителя |
| ReceiverId | Идентификатор приемника |
| PrivateKey | Ключ приложения |
| PublicKey | Ключ сервера |
| Server | Сервер |
| Port | Порт |
| BufferSize | Размер буфера |
| SendReceiveTimeout | SendReceiveTimeout |
| SleepTimeout | SleepTimeout |
Также вы можете внести настройки адаптера платежной системы используя текстовый редактор. Для этого откройте файл AgamiService.exe.config, который находится в папке Program Files/Agami/bin, и перенесите содержимое тега PaymentServer файла PointConfig.xml в тело тега PaymentServer файла AgamiService.exe.config, оставляя атрибут assembly тега PaymentServer.
Для того, чтобы видеть состояние терминала необходимо подключить терминал к серверу технического мониторинга. В комплекте Agami поставляется плагин сервера технического мониторинга Larus.
Для генерации настроек клиента сервера технического мониторинга используется Otis. Для внесения настроек необходимо открыть файл TechnicalServer.xml и перенести содержимое тегов в конфигуратор, используя таблицу соответствия имен тегов и настроек адаптера:
Таблица 2. Таблица соответствия имен тегов и настроек адаптера
| Название тега | Название настройки |
|---|---|
| TerminalId | Идентификатор терминала |
| PrivateKey | Ключ приложения |
| PublicKey | Ключ сервера |
| Server | Сервер |
| Port | Порт |
| SendReceiveTimeout | SendReceiveTimeout |
| SleepTimeout | SleepTimeout |
| PingTimeout | PingTimeout |
Также вы можете внести настройки адаптера сервера технического мониторинга используя текстовый редактор. Для этого откройте файл AgamiService.exe.config, который находится в папке Program Files/Agami/bin, и перенесите содержимое тега TechnicalServer файла PointConfig.xml в тело тега TechnicalServer файла AgamiService.exe.config, оставляя атрибут assembly тега TechnicalServer.
Адаптер подключения ичпользуется для поддержвания связи с интернет. В комлекте Agami поставляется плагин подключения по GPRS с ипользованием модема Siemens MC35i. Если вы используете другие средства подключения к интернету или у вас нет необходимости в наличии связи с интернет, необходимо использовать плагин-заглушку адаптера подключения.
Для настройки адаптера подключения необходимо знать тип переключателя (реле или кроссплата), порт подключения модема, индекс подключения к переключателю и параметры соединения с интернет. Определить параметры подключения модема вы можете при помощи документации к терминалу.
Адаптер подключения GPRS позволяет ипользовать несколько соединений с интернет. Для этого вам потребуется multisim-карта, в которой выбор провайдера осуществляется при помощи PIN-кода.
Внимание! При использовании неправильных настроек переключателя адаптер подключения может зависать при запуске.
Кофигуратор принтера позволяет включить фискальный режим.
Внимание! Включение фискального режима принтера не переводит программное обеспечение в режим использования фискальной регистрации!
Конфигуратор купюроприемника позволяет настроить преобразование кодов купюр в их номинал. По умолчанию адаптер купюроприемника настроен на прием рублевых купюр номиналом от 10 до 1000 рублей.
Для работы с другими купюрами вам необходима прошивка купюроприемника, поддерживающая купюры данного типа. Коды купюр вы можете узнать при помощи теста драйвера купюроприемника.
Прежде чем приступить к тонкой настройке параметров программного обеспечения, необходимо пояснить назначение различных файлов конфигурации.
Файл AgamiService.exe.config, находящийся в папке Program Files\Agami\bin, содержит настройки сервиса бизнес-логики Agami. В нем хранятся параметры терминала и настройки плагинов, которые вы можете изменять при помощи конфигуратора Xenus, а также шаблоны чеков, настройки логгирования log4net и соединения пользовательского интерфейса.
Файл Interface.xml, находящийся в папке Program Files\Pinicola, содержит описание пользовательского интерфейса и логики его работы. В нем хранятся описания ресурсов, переменных, экранов и обработчики событий.
Шаблоны чеков находятся в файле AgamiService.exe.config по пути configuration->Agami->Checks. Обращение к шаблонам ведется по имени. По умолчанию в Agami объявлены шаблоны чеков инкассации (CollectionCheck) и чеков оплаты (MobilePayment). Шаблон GuaranteeReceipt не используется, оставлен для совместимости с предыдущими версиями. Вы можете добавить новые шаблоны, а также модифицировать существующие. Шаблон CollectionCheck является обязательным, используется Agami при распечатке информации об инкассации. Шаблон MobilePayment используется пользовательским интерфейсом.
Пример 1. Отрывок из шаблона чека инкассации
<Check type="CollectionCheck">
<Lines>
<TableLine fontSize="big" bold="false"
italic="false">
<Column width="24"
alignment="center">Инкассационный
чек</Column>
</TableLine>
<Feed />
<Line fontSize="medium" bold="false"
italic="false">------------------------------------------------</Line>
<TableLine fontSize="medium" bold="false"
italic="false">
<Column width="48" alignment="center">Терминал №
${TerminalNumber}</Column>
</TableLine>
<Line fontSize="medium" bold="false"
italic="false">------------------------------------------------</Line>
<Feed />
<TableLine fontSize="medium" bold="false"
italic="false">
<Column width="24" alignment="left">Номер
инкассации:</Column>
<Column width="24"
alignment="left">${CollectionNumber}</Column>
</TableLine>
<TableLine fontSize="medium" bold="false"
italic="false">
<Column width="24" alignment="left">Дата
инкассации:</Column>
<Column width="24"
alignment="left">${CurrentDate}</Column>
</TableLine>
<TableLine fontSize="medium" bold="false"
italic="false">
<Column width="24" alignment="left">Время
инкассации:</Column>
<Column width="24"
alignment="left">${CurrentTime}</Column>
</TableLine>
<TableLine fontSize="medium" bold="false"
italic="false">
<Column width="24" alignment="left">Накопительный
итог:</Column>
<Column width="24"
alignment="left">${AccumulativeTotal}</Column>
</TableLine>
.
.
.
</Lines>
</Check>
Шаблон чека состоит из определения типа чека (атрибут type тега Check) и строк (тег Lines) - содержимого чека. Строки чека могут быть простыми строками (Line), таблицами (TableLine), пустыми строками (Feed) и строками продажи (Sale), которые используются для фискальной регистрации.
Для печати строки необходимо определить параметры шрифта, по которым плагин принтера выберет из доступных шрифтов принтера наиболее подходящий. При определении параметров шрифта необходимо указать размер шрифта, толщину и наклон. Размер шрифта, атрибут fontSize может принимать значения small, medium и big - маленький, средний и большой соответственно. Атрибут bold, который может принимать значение true и false, показывает, требуется ли использовать широкую версию шрифта. Атрибут italic, который также может принимать значения true и false, показывает требуется ли использовать прописную версию шрифта.
Обычная строка Line печатается выбранным шрифтом без выравнивания. Для печати используется содержимое тега.
Строка таблицы TableLine печатается выбранным шрифтом, в которой каждая колонка имеет ширину и выравнивание. Внутри тега TableLine неоьходимо объявить одну или несколько колонок, тег Column, содержимое которых исползуется для печати. Тег Column имеет два атрибута: ширина в символах и выравнивание, width и alignment соответственно. Значение атрибута alignment может принимать значения left, center и right, выравнивание влево, по центру и направо соответственно.
Пустая строка Feed не имеет атрибутов, её содержимое не используется. Прокрутка строки ведется с использованием шрифта по умолчанию для принтера.
Строка продажи Sale используется в режиме фискальной регистрации для регистрации продажи. Тег Sale имеет два атрибута quantity и price, количество и цена товара соответственно. Содержимое тега используется в качестве названия товара и может быть пустым.
Содержимое чека формируется динамически во время выполнения запроса на печать. Для формирования содержимого строк используются переменные, передаваемые в запросе на печать. Обращение к переменной ведется при помощи названия, заключенного в фигурные скобки с символом $ в начале, например ${CollectionNumber}. При печати чека всегда доступны стандартные переменные, объявленные в общих параметрах терминала, такие как CompanyName, TerminalNumber и TerminalAddress. Вы можете добавить свои переменные в тег TerminalParameters и использовать их в шаблоне. Кроме того, при создании запроса печати чека можно добавить другие переменные. В запросе оплаты при помощи переменных передается информация о платеже.
Для включения фискального режима нужно выполнить следующие шаги:
Включить фискальный режим принтера, например при помощи конфигуратора Xenus
Добавить в шаблон чека продажи MobilePayment строку продажи. Например, добавьте в конце шаблона строку
<Sale quantity="1" price="${gross_sum}" />Включить фискальный режим в файле Interface.xml, выставив значение переменной isFRMode в 1. Для этого найдите строку
<Variable name="isFRMode" type="int" initialValue="0" />и измените значение атрибута initialValue на 1.