Сервис eltex-ted необходим для интеграции с универсальным шлюзом (далее УШ).
Задачи, решаемые eltex-ted:
SoftWLC одновременно может работать только с одним УШ.
При интеграции используется Guest Based концепция, формат логина УЗ Wi-Fi: Фамилия (транслит)_ HotelID_ Номер комнаты (число)
Сервис устанавливается с помощью пакетного менеджера командой
apt install eltex-ted |
Конфигурационный файл для настройки доступен по пути /etc/eltex-ted/config/application.yml
spring:
cache:
caffeine:
spec:
# See CaffeineSpec for more settings
expireAfterWrite=10m
jpa:
hibernate:
naming:
# Use strict case sensitive table names
physical-strategy: org.hibernate.boot.model.naming.PhysicalNamingStrategyStandardImpl
datasource:
type: com.zaxxer.hikari.HikariDataSource
driver-class-name: com.mysql.jdbc.Driver
url: jdbc:mysql://localhost:3306/eltex_ems?useUnicode=true&characterEncoding=utf8&useSSL=false&useLegacyDatetimeCode=false&serverTimezone=UTC
username: javauser
password: javapassword
hikari:
poolName: Hikari
auto-commit: false
data-source-properties:
cachePrepStmts: true
prepStmtCacheSize: 250
prepStmtCacheSqlLimit: 2048
useServerPrepStmts: true
server:
port: 8009
management:
trace:
http:
enabled: true
endpoints:
web:
exposure:
# Actuator info
# Useful for inspecting deployed beans, watching metrics, watching caches info
# Also we can use it to create heapdump, threaddump, shutdown application and etc.
include: health, beans, info, caches, prometheus, env, threaddump, heapdump, configprops, httptrace
ugw:
baseUrl: http://localhost:8000/pmsconnect
connectionTimeoutMs: 1000
totalConnections: 1
mercury:
host: localhost
port: 6565
pcrf:
baseUrl: http://localhost:7070
attributes:
creator:
firstname: 'Operator-Creator-Name'
lastname: 'Operator-Creator-Family'
posId: 12344321
|
В файле application.yml нужно обратить внимание на параметры:
|
| Блок | Пояснение | В Docker |
|---|---|---|
spring.cache.caffeine.spec | Параметры кэша Caffeine. В Ted кэшируются две выборки:
Время жизни кэша по умолчанию 10 минут. | SPRING_CACHE_CAFFEINE_SPEC |
| spring.jpa.hibernate.naming | Параметры JPA Hibernate. | SPRING_JPA_HIBERNATE_NAMING_PHYSICALSTRATEGY |
| spring.datasource | Доступ до БД MariaDB eltex_ems. Сервис eltex-ted сам получает необходимые параметры Доменов из БД. | SPRING_DATASOURCE_... |
| server | Блок параметров сервера Ted. port - порт, на котором сервис eltex-ted слушает входящие запросы. | SERVER_PORT |
| management.endpoints.web.exposure | Информация о работе сервера, предоставляемые компонентом Spring Actuator. | MANAGEMENT_ENDPOINTS_WEB_EXPOSURE_INCLUDE |
| ugw | Блок параметров взаимодействия с УШ (Универсальным шлюзом). baseUrl - URL УШ. Обязательно содержит /pmsconnect. | UGW_BASEURL |
| mercury | Сервис eltex-ted создает пользователей Wi-Fi через SoftWLC eltex-mercury. | MERCURY_... |
| pcrf | Сервис eltex-ted работает с сессиями пользователей Wi-Fi через SoftWLC eltex-pcrf. | PCRF_BASEURL |
| attributes.creator | Имя ответственного за УЗ Wi-Fi: creator: firstname: 'Ivan' lastname: 'Ivanov' При создании УЗ нужно указывать имя и фамилию оператора. Обычно, это оператор ЛК. При работе Ted'а работает только бэкэнд, потому и оператора нужно указать отдельно. | ATTRIBUTES_CREATOR_FIRSTNAME ATTRIBUTES_CREATOR_LASTNAME |
| attributes.posId | Зафиксированный PoS (Point of Sales) идентификатор. Используется при обработке начислений, передается в запросах типа /charge в сторону УШ. | ATTRIBUTES_POSID |
Сервис Ted тесно взаимодействует с порталом.
Для его работы нужно правильно настроить окружение:
Создать SSID в домене гостиницы, это обязательное условие. SSID настраиваем на портальную авторизацию, в качестве портала указываем ранее созданный портал.
Все методы API Ted, кроме getversion - служебные.
Обращаться к ним необходимости нет. Все обращения к ним будут идти от Captive Portal и УШ.
Информация приводится для понимания логики работы.
Для проверки работоспособности API-интерфейса Ted после установки сервиса можно использовать метод getversion.
curl http://<IP>:<port>/getversion |
Результат:
Должна вернуться версия сервиса Eltex-Ted
1.21-3101 (09.12.21 19:18:53) |
Параметры:
Отсутствуют.
От УШ приходит нотификация при заселении постояльца в номер гостиницы.
В SoftWLC создается учетная запись Wi-Fi
curl --header "Content-Type: application/json" \
--request POST \
--data '{
"hotelId":"54",
"roomNumber":"1408",
"guestName":"Энслин",
"guestFirstName":"Майк",
"pmsRegNum":"666"
}' \
http://<IP>:<port>/checkin |
Результат:
В случае успешного запроса вы получите
{"code":0,"messages":["Success"]} |
Если учетная запись с таким пользователем была когда-то заведена и заблокирована , то при таком запросе вы увидите следующий ответ : |
При ошибке
{"code":9} |
Параметры:
| Название параметра | Type | Lenght | Поле обязательно для заполнения? | Описание |
|---|---|---|---|---|
| hotelId | string | 20 | да | Уникальный идентификатор гостиницы для обработки в рамках определенного домена. Задается в параметрах домена. |
| roomNumber | string | 10 | да | Номер комнаты гостя. |
| guestName | string | 40 | да | Фамилия гостя. На вход ожидаются данные формата "Фамилия" или "Фамилия,Имя". |
| guestFirstName | string | 40 | да | Имя гостя. |
| guestTitle | string | 10 | ||
| pmsRegNum | string | 20 | да | Уникальный номер гостя. |
| arrivalDate | string | 19 | нет | Дата заселения гостя. Часовой пояс SoftWLC. По умолчанию - Дата и время вызова метода. "YYYY-MM-DD HH:MM:SS" |
| departureDate | string | 19 | нет | Дата выселения гостя. Часовой пояс SoftWLC. |
| arrivalDateTS | string | 19 | нет | Дата заселения гостя. Часовой пояс УШ. |
| departureDateTS | string | 19 | нет | Дата выселения гостя. Часовой пояс УШ. "YYYY-MM-DD HH:MM:SS" |
| dateTime | string | 19 | нет | Дата, переданная в запросе от FIAS. |
| guestLanguage | string | 2 | нет | Язык интерфейса. ТВ Формат ISO 639-1, по умолчанию en. |
| guestVipStatus | string | 20 | нет | Статус VIP постояльца |
| roomShare | string | 1 | нет | Признак количества постояльцев в гостинице. N – один постоялец в комнате, Y – более одного постояльца в комнате |
| swapFlag | string | 1 | нет | Признак, что данная запись направлена в рамках процесса синхронизации базы данных с УШ. Y – запись синхронизационная в рамках процесса синхронизации БД (Database Resync) N (или отсутствует значение) – Запись онлайн FIAS SF |
| noPost | int | нет | 1, если запрещены начисления | |
| profileNum | string | 10 | нет | Номер профиля |
От УШ приходит нотификация при переселении постояльца (возможно изменение атрибутов без переселения).
В SoftWLC происходит обновление учетной записи Wi-Fi.
curl --header "Content-Type: application/json" \
--request POST \
--data '{
"hotelId":"54",
"roomNumber":"1409",
"oldRoom":"1408",
"guestName":"Энслин",
"guestFirstName":"Майк",
"pmsRegNum":"666"
}' \
http://<IP>:<port>/guestchange |
Результаты:
В случае успешного запроса вы получите
{"code":0} |
При ошибке
{"code":9} |
Параметры:
Используются те же параметры, что и при методе CheckIn, за исключением "swapFlag". Так же добавляются новые
| Название параметра | Type | Lenght | Поле обязательно для заполнения? | Описание |
|---|---|---|---|---|
| oldRoom | string | 10 | да | Предыдущий номер комнаты гостя. |
| oldRoomShare | string | 1 | нет | Признак количества постояльцев в предыдущей комнате. N – один постоялец в комнате, Y – более одного постояльца в комнате |
От SoftWLC Captive Portal к Ted на /charge приходит нотификация о выборе профиля.
От Ted к УШ уходит запрос на УШ /charge для Обработка начислений.
Результаты:
В случае успешного запроса вы получите
{"code":0} |
При ошибке
{"code":9} |
Параметры:
| Название параметра | Type | Lenght | Поле обязательно для заполнения? | Описание |
|---|---|---|---|---|
| roomNumber | string | 10 | да | Номер комнаты гостя. |
| guestName | string | 40 | да | Фамилия гостя. На вход ожидаются данные формата "Фамилия" или "Фамилия,Имя". |
| domain | string | 235 | да | Домен гостя |
| tariffCode | string | 64 | да | Уникальный код тарифа в SoftWLC |
| tariffPrice | int | да | Цена тарифа в SoftWLC Передается из SoftWLC, чтобы Ted не нужно было работать со структурой тарифа. Цена тарифа передается в копейках. | |
| dateTime | string | 19 | да | Дата, переданная в запросе от FIAS. |
От УШ приходит уведомление на запрос /charge. Содержит информацию о проведенной покупке.
curl --header "Content-Type: application/json" \
--request POST \
--data '{
"hotelId":"54",
"roomNumber":"1409",
"status":"0",
"pmsRegNum":"666",
"posId":"23134141",
"dateTime":"2021-12-14 14:39:39",
"dateTimeTS":"2021-12-14 14:39:39"
}' \
http://<IP>:<port>/saledone |
Результаты:
В случае успешного запроса вы получите
{"code":0} |
При ошибке
{"code":9} |
Параметры:
| Название параметра | Type | Lenght | Поле обязательно для заполнения? | Описание |
|---|---|---|---|---|
| hotelId | string | 20 | да | Уникальный идентификатор гостиницы для обработки в рамках определенного домена. Задается в параметрах домена. |
| roomNumber | string | 10 | да | Номер комнаты гостя. |
| status | int | да | Статус продажи:
| |
| pmsRegNum | string | 20 | да | Уникальный номер гостя. |
| posId | string | 16 | да | Идентификатор точки продажи |
| dateTime | string | 19 | да | Дата, переданная в запросе от FIAS. |
| dateTimeTS | string | 19 | да | Дата, переданная в запросе от FIAS Используется для поиска соответствий между запросами в разных информационных системах. Часовой пояс УШ. "YYYY-MM-DD HH:MM:SS" |
| checkNum | int | 10 | нет | Номер чека |
| text | string | 255 | нет | Текст ответа покупки |
| userID | string | 16 | нет | Идентификатор пользователя |
| salesOutlet | int | 5 | нет | Номер торговой точки |
| postingSequenceNum | int | 8 | нет | Уникальный идентификатор покупки в УШ |
От УШ приходит нотификация при выселении постояльца из номера гостиницы.
В SoftWLC происходит блокировка УЗ Wi-Fi.
curl --header "Content-Type: application/json" \
--request POST \
--data '{
"hotelId":"54",
"roomNumber":"1409",
"pmsRegNum":"667"
}' \
http://<IP>:<port>/checkout |
Результаты:
В случае успешного запроса вы получите
{"code":0} |
При ошибке
{"code":9} |
Параметры:
| Название параметра | Type | Lenght | Поле обязательно для заполнения? | Описание |
|---|---|---|---|---|
| hotelId | string | 20 | да | Уникальный идентификатор гостиницы для обработки в рамках определенного домена. Задается в параметрах домена. |
| roomNumber | string | 10 | да | Номер комнаты гостя. |
| pmsRegNum | string | 20 | да | Уникальный номер гостя. |
| roomShare | string | 1 | нет | Признак количества постояльцев в гостинице. N – один постоялец в комнате, Y – более одного постояльца в комнате |
| swapFlag | string | 1 | нет | Признак, что данная запись направлена в рамках процесса синхронизации базы данных с УШ. Y – запись синхронизационная в рамках процесса синхронизации БД (Database Resync) N (или отсутствует значение) – Запись онлайн FIAS SF |
| dateTime | string | 19 | нет | Дата, переданная в запросе от FIAS. |
От SoftWLC приходят данные, по которым надо найти пользователя (вернуть логин в БД)
Результаты:
В случае успешного запроса вы получите
{"code":0} |
При ошибке
{"code":9} |
Параметры:
| Название параметра | Type | Lenght | Поле обязательно для заполнения? | Описание |
|---|---|---|---|---|
| roomNumber | string | 10 | да | Номер комнаты гостя. |
| guestName | string | 40 | да | Фамилия гостя. На вход ожидаются данные формата "Фамилия" или "Фамилия,Имя". |
| domain | string | 235 | да | Домен гостя |
| dateTime | string | 19 | да | Дата, переданная в запросе от FIAS. |
Для удобства проверки ответов сервиса Eltex-Ted на запросы была создана коллекция запросов в формате json, которая может быть импортирована в Postman для дальнейшего использования.
Для того, чтобы импортировать коллекцию запросов в приложение Postman необходимо
в основном окне приложения нажать кнопку Import:

Файл для импортирования можно найти прикрепленным в конце раздела "Импорт коллекции запросов в формате json в приложение Postman" |
В открывшемся окне выбрать вкладку Files, нажать Upload Files и указать файл коллекции 'Ted_requests.postman_collection.json':

После загрузки файла, должно отобразиться следующее окно:

Здесь можно увидеть название импортируемой коллекции и версию файла.
При дальнейшем нажатии кнопки Import, данная коллекция будет добавлена в Workspace:

Каждый запрос можно настраивать отдельно.
Для каждого запроса было добавлено тело, с использованием параметризации, для того, чтобы изменять
передаваемые параметры не изменяя сам запрос.
Список параметров запроса можно увидеть в самом запросе на вкладке Body.
Список редактируемых параметров можно увидеть при нажатии на название коллекции и перейдя на вкладку
Variables:

Сервис может быть запущен в docker-контейнере. Для этого необходимо подготовить файл с переменными окружения .env и docker-compose.yml.
version: "3"
services:
eltex-ted:
container_name: eltex-ted
image: hub.eltex-co.ru/softwlc/eltex-ted:1.21-<tag>
ports:
# Основной порт сервиса
- "${TED_SERVER_PORT}:${TED_SERVER_PORT}"
# volumes:
# Логи gc пишутся внутри контейнера, если требуется оперативно их
# вытащить можно определить директорию для выгрузки логов
# Также можно вытащить логи через команду docker cp
# "./export:${TED_LOG_DIR}
environment:
# Можно также переопределить параметры запуска сервиса
# Но это нужно делать, только если есть необходимость, пока в закомментированном виде
#- DEBUG_PORT=${TED_DEBUG_PORT}
#- JAVA_INIT_HEAP=${TED_JAVA_INIT_HEAP}
#- JAVA_MAX_HEAP=${TED_JAVA_MAX_HEAP}
#- HEAP_DUMP_PATH=${TED_HEAP_DUMP_PATH}
#- LOG_DIR=${TED_LOG_DIR}
#- CONFIG_DIR=${TED_CONFIG_DIR}
#- LOGGING_CONFIG=${TED_LOGGING_CONFIG}
#
# Настройка логгирования
- LOG_LEVEL=${TED_LOG_LEVEL}
- CONSOLE_LEVEL=${TED_CONSOLE_LEVEL}
# Настройка перенаправления логов в Graylog
- GELF_HOST=${GELF_HOST}
- GELF_PORT=${GELF_PORT}
- GELF_LEVEL=${GELF_LEVEL}
# Конфигурация сервиса
- SPRING_CACHE_CAFFEINE_SPEC=${TED_SPRING_CACHE_CAFFEINE_SPEC}
- SPRING_JPA_HIBERNATE_NAMING_PHYSICALSTRATEGY=${TED_SPRING_JPA_HIBERNATE_NAMING_PHYSICALSTRATEGY}
- SPRING_DATASOURCE_TYPE=${TED_SPRING_DATASOURCE_TYPE}
- SPRING_DATASOURCE_DRIVERCLASSNAME=${TED_SPRING_DATASOURCE_DRIVERCLASSNAME}
- SPRING_DATASOURCE_URL=${TED_SPRING_DATASOURCE_URL}
- SPRING_DATASOURCE_USERNAME=${TED_SPRING_DATASOURCE_USERNAME}
- SPRING_DATASOURCE_PASSWORD=${TED_SPRING_DATASOURCE_PASSWORD}
- SPRING_DATASOURCE_HIKARI_POOLNAME=${TED_SPRING_DATASOURCE_HIKARI_POOLNAME}
- SPRING_DATASOURCE_HIKARI_AUTOCOMMIT=${TED_SPRING_DATASOURCE_HIKARI_AUTOCOMMIT}
- SPRING_DATASOURCE_HIKARI_DATASOURCEPROPERTIES_CACHEPREPSTMTS=${TED_SPRING_DATASOURCE_HIKARI_DATASOURCEPROPERTIES_CACHEPREPSTMTS}
- SPRING_DATASOURCE_HIKARI_DATASOURCEPROPERTIES_PREPSTMTCACHESIZE=${TED_SPRING_DATASOURCE_HIKARI_DATASOURCEPROPERTIES_PREPSTMTCACHESIZE}
- SPRING_DATASOURCE_HIKARI_DATASOURCEPROPERTIES_PREPSTMTCACHESQLLIMIT=${TED_SPRING_DATASOURCE_HIKARI_DATASOURCEPROPERTIES_PREPSTMTCACHESQLLIMIT}
- SPRING_DATASOURCE_HIKARI_DATASOURCEPROPERTIES_USESERVERPREPSTMTS=${TED_SPRING_DATASOURCE_HIKARI_DATASOURCEPROPERTIES_USESERVERPREPSTMTS}
- SERVER_PORT=${TED_SERVER_PORT}
- MANAGEMENT_ENDPOINTS_WEB_EXPOSURE_INCLUDE=${TED_MANAGEMENT_ENDPOINTS_WEB_EXPOSURE_INCLUDE}
- MANAGEMENT_TRACE_HTTP_ENABLED=${TED_MANAGEMENT_TRACE_HTTP_ENABLED}
- UGW_BASEURL=${TED_UGW_BASEURL}
- UGW_CONNECTIONTIMEOUTMS=${TED_UGW_CONNECTIONTIMEOUTMS}
- UGW_TOTALCONNECTIONS=${TED_UGW_TOTALCONNECTIONS}
- MERCURY_HOST=${TED_MERCURY_HOST}
- MERCURY_PORT=${TED_MERCURY_PORT}
- ATTRIBUTES_CREATOR_FIRSTNAME=${TED_ATTRIBUTES_CREATOR_FIRSTNAME}
- ATTRIBUTES_CREATOR_LASTNAME=${TED_ATTRIBUTES_CREATOR_LASTNAME}
- ATTRIBUTES_POSID=${TED_ATTRIBUTES_POSID}
- PCRF_BASEURL=${TED_PCRF_BASEURL}
- TZ=${TZ} |
# Можно также переопределить параметры запуска сервиса
# Но это нужно делать, только если есть необходимость, пока в закомментированном виде
TED_DEBUG_PORT=0
TED_JAVA_INIT_HEAP=256m
TED_JAVA_MAX_HEAP=512m
TED_HEAP_DUMP_PATH=/var/log/eltex-ted
TED_LOG_DIR=/var/log/eltex-ted
TED_CONFIG_DIR=/etc/eltex-ted
# CONFIG_DIR это не ошибка. резолвится на уровне сервиса.
TED_LOGGING_CONFIG="-Dlog4j2.configurationFile=${CONFIG_DIR}/log4j2-docker.xml -Dfile.encoding=UTF-8"
# Настройка логгирования
TED_LOG_LEVEL=INFO
TED_CONSOLE_LEVEL=INFO
# Настройка перенаправления логов в Graylog
GELF_HOST=udp:lab3-test.eltex.loc
GELF_PORT=12201
GELF_LEVEL=INFO
# Конфигурация сервиса
TED_SPRING_CACHE_CAFFEINE_SPEC=expireAfterWrite=10m
TED_SPRING_JPA_HIBERNATE_NAMING_PHYSICALSTRATEGY=org.hibernate.boot.model.naming.PhysicalNamingStrategyStandardImpl
TED_SPRING_DATASOURCE_TYPE=com.zaxxer.hikari.HikariDataSource
TED_SPRING_DATASOURCE_DRIVERCLASSNAME=com.mysql.jdbc.Driver
TED_SPRING_DATASOURCE_URL=jdbc:mysql://softwlc.eltex.loc:3306/eltex_ems?useUnicode=true&characterEncoding=utf8&useSSL=false&useLegacyDatetimeCode=false&serverTimezone=UTC
TED_SPRING_DATASOURCE_USERNAME=javauser
TED_SPRING_DATASOURCE_PASSWORD=javapassword
TED_SPRING_DATASOURCE_HIKARI_POOLNAME=Hikari
TED_SPRING_DATASOURCE_HIKARI_AUTOCOMMIT=false
TED_SPRING_DATASOURCE_HIKARI_DATASOURCEPROPERTIES_CACHEPREPSTMTS=true
TED_SPRING_DATASOURCE_HIKARI_DATASOURCEPROPERTIES_PREPSTMTCACHESIZE=250
TED_SPRING_DATASOURCE_HIKARI_DATASOURCEPROPERTIES_PREPSTMTCACHESQLLIMIT=2048
TED_SPRING_DATASOURCE_HIKARI_DATASOURCEPROPERTIES_USESERVERPREPSTMTS=true
# Порт на котором поднимается сервис Ted
TED_SERVER_PORT=8009
TED_MANAGEMENT_ENDPOINTS_WEB_EXPOSURE_INCLUDE=health,beans,info,caches,metrics,env,threaddump,heapdump,configprops,httptrace
TED_MANAGEMENT_TRACE_HTTP_ENABLED=true
# Адрес УШ
TED_UGW_BASEURL=http://localhost:8000/pmsconnect
TED_UGW_CONNECTIONTIMEOUTMS=1000
TED_UGW_TOTALCONNECTIONS=1
# Адрес Mercury
TED_MERCURY_HOST=localhost
TED_MERCURY_PORT=6565
# Адрес PCRF
TED_PCRF_BASEURL=http://localhost:7070
# Имя и фамилия ответственного за учётные записи PMS (СОРМ)
TED_ATTRIBUTES_CREATOR_FIRSTNAME=Operator-Creator-Name
TED_ATTRIBUTES_CREATOR_LASTNAME=Operator-Creator-Family
# Зафиксированный PoS (Point of Sales) идентификатор. Для запросов типа /charge в сторону УШ.
TED_ATTRIBUTES_POSID=12344321
#Настройка часового пояса
TZ=Asia/Novosibirsk |
В файле .env нужно указать адреса:
|
Представленные ниже данные помогают оператору понять, как работает услуга Интеграция с гостиничными сетями в целом.
Перечислены признаки работы услуги Интеграция с гостиничными сетями:
При обработке заселения в БД MariaDB radius создается УЗ Wi-Fi с логином - Фамилия (транслит)_ HotelID_ Номер комнаты (число);
Счетчики по запросам можно найти в Метриках Ted (см. ниже). Если какая-то из метрик не меняется, значит что-то идёт не так, как задумано.
В БД MariaDB radstat для УЗ заведенным через "Интеграцию с гостиничными сетями" будут следующие свойства:
Для сбора и последующего анализа основной информации было создано два скрипта.
Инструкция по их использованию находится в файле README.md
Для мониторинга работы eltex-ted доступны Prometheus метрики по пути http:<IP>:8009/actuator/prometheus
Среди них отметим следующие:
# HELP jvm_threads_peak_threads The peak live thread count since the Java virtual machine started or peak was reset |