@it-enterprise/web-agent

Description

API для взаимодействия с установленным на клиентской машине специальным приложением - "IT-Enterprise. WebAgent" или "Master. WebAgent"

Установка

@it-enterprise/web-agent

npm install @it-enterprise/web-agent

Использование API

Создание экземпляра web-агента

var version = '{"Version":"'+ /* версия пакета */ + '","OfficeViewer":'+ /* тип просмотрщика */ +',"Office365Site":'+ /* сайт Office365 */ +',"Project":"' + /* проект */ + '","UserLogin":"' + /* логин пользователя */ + '"}'
var agent = new WebAgent(version, needCalcHashes);

Ключи OfficeViewer, Office365Site, Project и UserLogin нужны для интеграции агента с Office365.

• OfficeViewer - тип просмотрщика документов.
  • "" - открывать приложением по умолчанию на клиенте
  • "O" - загружать в Office 365
• Office365Site - путь к сайту Office365
• Project - код проекта (glbproject)
• UserLogin - логин пользователя в системе

needCalcHashes - проверять хеши файлов агента (для обновления агента до версии web-сервера)

Вызов любой функции обращения к web-агенту

Для вызова любой функции агента (скачивание/загрузка файлов, печать, сканирование и т.д.) для начала необходимо вызвать функцию Ping для проверки доступности агента:

agent.ping(callback, updateCallback, checkId, onerror, waitForRestart);

• callback - действие, вызываемое после ответа агента. Структура: function (state, message, installAgent, exception) {}
  • state - состояние агента. Тип перечисления - agent.agentStates:
    • available - агент доступен.
    • notLaunched - агент не запущен или не установлен.
    • oldVersion - используется старая версия - ошибка при обработке ответа.
    • updateIssues - ошибка при попытке обновления агента.
    • oldLauncher - используется старая версия программы обновления агента.
    • setNewPorts - необходимо запомнить порты агента для текущего пользователя.
    • canNotBeEnabled - невозможно использование агента (клиент на linux-системе).
  • message - в случае, когда:
    • state === agent.agentStates.updateIssues - это сообщение об ошибке (string).
    • state === agent.agentStates.setNewPorts - это Json-объект с портами ({ Http: http, Https: https }).
  • installAgent - не используется
  • exception - ошибка при попытке обновления
• updateCallback - действие при обновлении агента. Структура: function (current, total, message) {}
  • current - текущий процент обновления
  • total - максимальный процент обновления
  • message - сообщение при обновлении
• checkId - проверять PID (актуально, если агент обновляется и еще не запустил новый процесс)
• onerror - действие, вызываемое при ошибке обращения к агенту. Структура: function (exception) {}
• waitForRestart - сейчас идет процесс ожидания обновления (запуска нового процесса) агента

Редактирование файла на клиенте

agent.editFile(params, onSuccess, onError, onWait, returnData);

• params - параметры для редактирования файла. Структура класса:
  • file - имя файла.
  • fileUrl - URL для вызова запроса в web-агенте для скачивания файла. Дополнительно в методе автоматически будут переданы протокол, хост и порт текущего URL`а в браузере (window.location.origin) и строка, содержащая первый '/' после хоста с последующим текстом URL`а (window.location.pathname) для составления полного URL скачивания файла в web-агенте.
  • clientPath - путь к папке с файлом на клиенте.
  • download - загрузить файл на клиенте (файл не был передан на клиент заранее).
  • readOnly - не используется.
  • application - приложение для открытия файла. Если пусто - используется приложение по умолчанию.
  • wait - ждать окончания редактирования файла.
  • delAfterUse - удалить файл после окончания редактирования.
  • uploadToServer - загрузить файл на web-сервер после редактирования
  • cookies - куки web-сервера (нужны для корректного вызова запроса в web-агенте для скачивания файла с web-сервера на клиент)
• onSuccess - действие при успешном редактировании файла. Структура: function () {}
• onError - действие, вызываемое при ошибке редактировании файла. Структура: function (exception) {}
• onWait - действие при ожидании окончания редактирования файла (файл на клиенте открылся). Структура: function (name, path) {}
  • name - путь к файлу
  • path - не используется
• returnData - вызвать действие onSuccess, передавая в него строку-ответ агента. Иначе - вызвать загрузку файла на web-сервере (необходимо наличие специльного метода). Структура строки ответа - "{1};{2};{3}":
  • 1 - результат редактирования файла ('-' - ошибка; '*' - файл был открыт, откредактирован и закрыт (если в параметраз передали wait = true); '+' - файл успешно открыт).
  • 2 - текст ошибки, если 1 == '-' и не удалось создать файл; имя файла, если 1 == '*'; путь к файлу, если 1 == '+' или 1 == '-' и файл удалось создать, но не открыть.
  • 3 - путь к папке, если 1 == '*'.

Загрузка файлов на клиентский компьютер

agent.transferClientFiles(files, index, success, error, callback);

• files - коллекия файлов для передаче. Стуктура класса каждого файла:
  • FileName - имя файла на клиенте
  • DestFolder - путь к папке на клиенте
  • Open - открыть файл на клиенте после передачи
  • DeleteAfterUse - удалить после того, как закончится работа с файлом на клиенте
  • FileInfo - настройки файла. Структура класса:
    • LastModified - дата последнего изменения файла (тип System.DateTime)
    • Attributes - атрибуты файла (тип System.IO.FileAttributes)
  • Cookies - куки web-сервера (нужны для корректного вызова запроса в web-агенте для скачивания файла с web-сервера на клиент)
  • PartialDownloadUrl - URL для вызова запроса в web-агенте для скачивания файла. Дополнительно в методе автоматически будут переданы протокол, хост и порт текущего URL`а в браузере (window.location.origin) и строка, содержащая первый '/' после хоста с последующим текстом URL`а (window.location.pathname) для составления полного URL скачивания файла в web-агенте
• index - индекс текущего файла в коллекции files
• success - действие при успешной передаче всех файлов. Структура: function () {}
• error - действие, вызываемое при ошибке передачи файла. Структура: function (exception) {}
• callback - действие при успешной передаче текущего файла. Структура: function (current, total) {}
  • current - текущий процент передачи файлов
  • total - максимальный процент передачи файлов

Загрузка файлов с клиентского компьютера на web-севрер

agent.uploadFilesToServer(files, onSuccess, onError, index, returnData);

• files - коллекция файлов, которые необходимо загрузить с клиента. Стуктура класса каждого файла:
  • File - путь к файлу на клиенте
  • DeleteSourceFile - удалить файл на клиенте после загрузки
  • LoadAsBase64 - загрузить содержимое файла как base64 строку
• onSuccess - действие при успешной передаче всех файлов. Структура: function () {}
• onError - действие, вызываемое при ошибке передачи файла. Структура: function (exception) {}
• index - индекс текущего файла в коллекции files.
• returnData - вызвать действие onSuccess, передавая в него индекс текущего файла в коллекции и строку-ответ агента. Иначе - вызвать загрузку файла на web-сервере (необходимо наличие специльного метода). Строка ответа - это содержимое файла (Stream).

Печать файлов и отчетов RDL

Автоматически при вызове печати файла будет произведена попытка печати средствами брузера.

agent.print(params, onSuccess, onError, isReport);

• params - параметры файлов для печати. Структура класса:
  • file - файл, который необходимо распечатать. Структура класса файла такая же, как при загрузке файлов на клиентский компьютер.
  • files - коллекция файлов для печати. Стуктура класса каждого файла такая же, как при загрузке файлов на клиентский компьютер.
  • showDialog - отобразить диалог печати
  • cookies - куки web-сервера (нужны для корректного вызова запроса в web-агенте для скачивания файла с web-сервера на клиент)
• onSuccess - действие при успешной печати всех файлов. Структура: function () {}
• onError - действие, вызываемое при ошибке печати файлов. Структура: function (exception) {}
• isReport - признак печати отчета

Сканирование файлов

agent.scan(params, onSuccess, onError, returnData);

• params - параметры сканирования. Структура класса:
  • sd - отобразить диалог выбора сканера на рабочей станции
  • ss - использовать потоковое сканирование
  • mr - максимально допустимая разрешающая способность в dpi
  • st - выбор режима выгрузки (PDF/JPEG/TIFF)
  • sm - режим сканирования (ч/б, цветное, градация серого)
  • nd - бездиалоговый режим сканирования
  • rd - изменить порядок страниц после сканирования (только при сканировании в pdf)
• onSuccess - действие при успешном сканировании. Структура: function (fileName) {}
  • fileName - имя сканированного файла
• onError - действие, вызываемое при ошибке печати файлов. Структура: function (exception) {}
• returnData - вызвать действие onSuccess, передавая в него содержимое сканированного файла и имя файла. Иначе - вызвать загрузку файла на web-сервере (необходимо наличие специльного метода). Содержимое сканированного файла в формате FormData, второй аргумент - имя сканированного файла.

Сравнение файлов

agent.compareDocuments(params, onSuccess, onError);

• params - параметры сравнения. Структура класса:
  • file1 - путь к файлу на клиенте
  • file2 - путь к файлу на клиенте
• onSuccess - действие при успешном вызова программы сравнения файлов. Структура: function () {}
• onError - действие, вызываемое при ошибке вызова программы сравнения файлов. Структура: function (exception) {}

Выбор папки на клиентском компьютере

agent.browseFolder(params, onSuccess, onError);

• params - параметры вызова диалога проводника. Структура класса:
  • Title - заголовок окна проводника
  • Path - путь к начальному каталогу
• onSuccess - действие при успешном выборе папки. Структура: function (ret) {}
  • ret - путь к выбранной папке
• onError - действие, вызываемое при ошибке выбора папки. Структура: function (exception) {}

Вызов диалога сохранения/выбора файла на клиентском компьютере

agent.saveFile(params, onSuccess, onError);

• params - параметры вызова диалога проводника. Структура класса:
  • Title - заголовок окна проводника
  • Filter - фильтр отображаемых файлов
  • AllFiles - признак "Все файлы"
  • FileName - имя файла, выбранное в окне проводника
• onSuccess - действие при успешном выборе папки. Структура: function (ret) {}
  • ret - путь к файлу
• onError - действие, вызываемое при ошибке вызова диалога сохранения файла. Структура: function (exception) {}

Получить информацию о файле на клиентском компьютере (с диалогом выбора файла)

agent.getClientFileInfo(params, onSuccess, onError);

• params - параметры вызова диалога проводника. Структура класса:
  • Filter - фильтр отображаемых файлов
  • AllFiles - признак "Все файлы"
  • Multy - возможность выбора нескольких файлов
  • Title - заголовок окна проводника
  • InitialDirectory - путь к начальному каталогу
  • SendToServer - отправить файл на сервер после выбора
  • FileLoadFilter - коллекция разрешенных/запрещенных расширений файлов. Структура класса:
    • AllowedExtensions - список разрешенных расширений
    • DeniedExtensions - список запрещенных расширений
• onSuccess - действие при успешном выборе папки. Структура: function (files) {}
  • files - список выбранных файлов через '*'
• onError - действие, вызываемое при ошибке вызова диалога сохранения файла. Структура: function (exception) {}

Вызова диалога выбора пользователя на клиентской машине

agent.ShowUserPicker(args, onSuccess, onError);

• args - возможность выбора нескольких пользователей ('+'/'-')
• onSuccess - действие при успешном выборе папки. Структура: function (ret) {}
  • ret - для каждого выбранного пользователя: "sid,name,domain,accountName,sidHex". Разделитель между выбранными пользователями - ";"
• onError - действие, вызываемое при ошибке вызова диалога сохранения файла. Структура: function (exception) {}

Запуск процесса на клиенте

agent.startProcess(params, onSuccess, onError);

• params - параметры запуска процесса. Структура класса:
  • workingDirectory - рабочий каталог
  • fileName - имя файла
  • errorMessage - сообщение, которое выдать при сбое запуска приложения на клиенте
  • arguments - аргументы командной строки
  • waitTimeout - таймаут ожидания
  • silentMode - тихий режим (без выдачи сообщений об ошибках)
  • runAsAdmins - запустить процесс в режиме администратора
  • additionalProps - только для процесса 'winmergeu'. Структура класса:
    • File1 - путь к файлу
    • File2 - путь к файлу
    • File1Url - URL для вызова запроса в web-агенте для скачивания файла.
    • File2Url - URL для вызова запроса в web-агенте для скачивания файла.
  • process - только для процесса 'winmergeu'. Имя процесса - "merge"
  • cookies - куки web-сервера (нужны для корректного вызова запроса в web-агенте для скачивания файла с web-сервера на клиент)
• onSuccess - действие при успешном выборе папки. Структура: function (ret) {}
  • ret - результат запуска процесса. Структура класса:
    • Success - удачный запуск процесса
    • ExitCode - код возврата процесса
    • ProcessId - PID
    • StartTime - дата-время, когда процесс стартовал
• onError - действие, вызываемое при ошибке вызова диалога сохранения файла. Структура: function (exception) {}

Сервисный вызов на клиенте (для получения %TEMP%, информации о файле/папке; копирования/перемещения файла/папки и т.д.)

agent.serviceRequest(args, onSuccess, onError);

• args - аргументы вызова. Структура класса:
  • request - тип вызова.
  • args - аргументы вызова.
    • Варианты вызова (всё вызывается на клиенте):
      • request = 'GetTemp' - получить путь %TEMP%. args - не нужны.
      • request = 'FileInfo' - получить информацию о файле. request = 'DirectoryInfo' - получить информацию о папке. Структура args:
        • FileName - путь к файлу или каталогу.
        • DirInfo - получить информацию о каталоге (true\false)
        • ResultType - режим поиска:
          • 1 - искать только файлы.
          • 2 - искать только каталоги.
          • 3 - искать файлы и каталоги.
        • SearchDeep - глубина поиска:
          • 0 - без ограничений.
          • 1 - искать только в текущем каталоге (по умолчанию).
          • n - искать на n уровней по отношению к текущему каталогу.
        • SearchSilent - не выдавать сообщения об ошибке
        • FileExtensions - маска для поиска файлов (например, '*.txt')
      • request = 'RunCmd' - запуск cmd.exe. Структура args:
        • Command - команда для выполнения в cmd.exe
        • Timeout - таймаут ожидания выполнения cmd.
      • request = 'DeleteFile' - удалить файл или каталог. Структура args:
        • Files - файл/файлы/папка для удаления. Может быть путем к файлу, коллекцией путей к файлам или папкам. Если удаление папки, то в конце пути необходимо добавить '\'
      • request = 'MoveDirectory' - переместить папку. request = 'MoveFile' - переместить файл. Структура args:
        • SourcePath - путь откуда перемещать
        • DestPath - путь куда перемещать
      • request = 'CopyFile' - скопировать файл. Структура args:
        • SourcePath - путь откуда копировать
        • DestPath - путь куда копировать
      • request = 'CreateDirectory' - создать папку. Структура args:
        • Path - путь к папке
      • request = 'GetHelpPath' - получить путь хранения файлов клиентской документации. args - не нужны.
      • request = 'CanUpdateHelp' - проверить возможно ли обновление клиентской документации. args - не нужны.
      • request = 'ConvertFileByPdmFilesConverter' - конвертировать файл средствами конкретной CAD системы. Структура args:
        • sourceFile - путь к исходному файлу
        • outFile - путь к файлу после конвертации
        • logFile - путь к файлу для логирования
• onSuccess - действие при успешном обращении к агенту. Структура: function (data) {}
  • data - ответ агента. Варианты структуры ответа:
    • request === 'GetTemp' - путь к каталогу.
    • request === 'FileInfo' или request === 'DirectoryInfo' - информация о файле/папке и информации о файлах в ней. Структура класса:
      • FileName - путь к файлу (только для получения информации о файле).
      • FileSize - размер файла в байтах (только для получения информации о файле).
      • FileTime - строка, содержащая дату последней корректировки файла/папки в виде 'yyyyMMddHHmmss'.
      • FileInfos - коллекция с информацией о файлах в папке (только для получения информации о папке). Структура класса каждого файла:
        • RelativePath - путь относительно папки, о которой запрашивается информация.
        • Name - имя файла (без пути).
        • Modified - строка, содержащая дату последней корректировки файла/папки в виде 'yyyyMMddHHmmss'.
        • Size - размер файла в байтах.
        • IsFile - текущий объект - файл.
    • request === 'RunCmd' - результат запуска. Структура класса:
      • Success - удачный запуск командной строки.
      • Result - строка с ответом (стандартным выводом) cmd.
    • request === 'MoveDirectory' или request === 'MoveFile' или request === 'CopyFile' или request === 'CreateDirectory' - результат перемещения/копирования/создания. Структура класса:
      • Success - перемещение прошло успешно
    • request === 'GetHelpPath' - путь к каталогу.
    • request === 'CanUpdateHelp' - признак возможности обновления (true\false)
    • request === 'ConvertFileByPdmFilesConverter' - результат конвертирования (true\false)
• onError - действие, вызываемое при ошибке вызова. Структура: function (exception) {}

Получение портов на которых работает агент (для терминального режима)

agent.getPortForCurrentUser(nextFunc, callback, onerror);

• nextFunc - действие, вызываемое после успешной найденных портов. Структура: function () {}
• callback - действие с обработкой состояния агента (подробнее о состоянии агента). Структура: function (state, message, installAgent, exception) {}
• onerror - действие, вызываемое при ошибке поиска портов. Структура: function (exception) {}