Вопрос

Приветствую, уважаемые форумчане!

На больших проектах, по разработке на платформе Terrasoft, ощущается острая необходимость документации кода. На сегодняшний день есть множество frameworks для автоматической генерации документов на основе markdown или wiki.

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

Может кто-то использует нечто подобное, подскажите best-practice, поделитесь как вы решаете эту проблему.

Для генерации документации, клиентской части ядра, платформы, используется JSDuck. Можно сформировать для каждого сайта нечто а-ля https://academy.terrasoft.ru/jscoresdk/ Но как-бы заставить jsduck собирать информацию ещё и про схемы конфигурации... Или же проще использовать другой framework для этой задачи...

У меня такой же вопрос

5 комментариев

Добрый день.

JSDuck является оптимальным решением и позволяет генерировать действительно удобную и полезную документацию. Приложения, созданные на ExtJS, поддерживают автоматическое создание документации, так как генератор изначально создавался для Sencha и позволяет распознавать синтаксис ExtJS.
Запуск генератора осуществляется из командной строки:

$ jsduck

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

$ jsduck path/to/src --output docs

Но я не рекомендую этого делать, если у вас очень много параметров конфигурации. Это очень не удобно и не наглядно.
Также можно указать другой путь к файлу конфигурации, если в этом есть необходимость. Например

$ jsduck --config=mypath/to/myconfig.json

Справку по всем параметрам командной строки можно посмотреть командой

$ jsduck --help

Все параметры могут быть использованы как из командной строки, так и в файле конфигурации.

Пример файла конфигурации:

{
"--title": "My Application Docs",
"--warnings": [
"-all:path/to/extjs/src"
],
"--output": "docs",
"--": [
"path/to/extjs/src",
"path/to/my/app"
]
}

Краткое описание параметров:
title — титульный заголовок на странице документации.
warnings — позволяет управлять потоком предупреждений, которые пишутся в консоль, если документированный код не соответствует самому коду. В приведенном примере с помощью опции "-all" игнорируются все предупреждения, возникающие в фреймворке extjs.
output — директория сгенерированной документации.
В последней секции "--" перечисляются директории с исходниками, из которых должна быть сгенерированна документация.

Ознакомиться с официальной документацией можно по этой ссылке: https://github.com/senchalabs/jsduck/wiki

Я читал документацию по JSDuck. И формировал документацию для ядра Terrasoft BPMonline.
Но как это поможет сгенерировать документацию для модулей конфигурации? Возможно ли настроить JSDuck так, чтобы можно было сгенерировать документацию по всем клиентским файлам конфигурации. Если у вас это удавалось - будет здорово, если вы со всеми поделитесь инструкцией и конфигами.

"Возможно ли настроить JSDuck так, чтобы можно было сгенерировать документацию по всем клиентским файлам конфигурации" - да, возможно. Если Вы читали документацию по JSDuck и формировали документацию для ядра Terrasoft BPMonline, ты Вы, безусловно, в курсе, что путь к исходным файлам, для которых необходимо сформировать документацию, указывается в файле конфигурации, примерно вот так:

"--": [
"path/to/extjs/src",
"path/to/my/app"
]

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

Привожу в качестве примера наш конфигурационный файл:
{
"--title": "bpm'online NUI Docs",
"--warnings": ["-link", "-nodoc(,)", "-inheritdoc", "-type_syntax"],
"--output": "..\\Documentation",
"--footer": "Terrasoft 2002-2016 Все права защищены",
"--tags": ".\\meta-tags.rb",
"--": [
"C:\\Projects\\NuewUnitTests\\Terrasoft.Nui\\ConfigurationJS"
]
}
Создание пользовательских тегов описано в документации JSDuck.

Добрый день! У меня наконец получилось извлечь боле менее вразумительную документацию с помощью JSDuck. Прошлый раз утилита постоянно обрывалась по ошибке. Я считал, что это из-за нестандартной структуры клиентских модулей. Нестандартных для классов ExtJS.
Но правильно настроив конфиг и используя правильные комментарии удалось сгенерировать кое-что полезное. Спасибо.

А как быть с серверным кодом? Может подскажите оптимальный инструмент для документации по серверному коду?

Добрый день!
К сожалению, на данный момент у нас нет опробованного оптимального инструмента для генерации документации по серверному коду Конфигурации Приложения. Идет анализ и тестирование подходящего инструмента. Рекомендую обратить внимание на следующие подходы к созданию документации и используемые при этом инструменты, описанные в статьях https://habrahabr.ru/post/102177/
и https://habrahabr.ru/post/252101/

Войдите или зарегистрируйтесь, чтобы комментировать
Публикация

В документацию по разработке bpm'online добавлены новые матералы. В этом обновлении документации разработчика также активно участвовали команды разработки bpm’online.

В текущем обновлении раздел "Описание платформы" дополнен подразделом "Элементы управления". В него добавлены статьи, раскрывающие общие принципы работы с элементами управления, а также статьи о таких элементах управления, как профили связанных сущностей и детали.

Также в раздел "Описание платформы" добавлено описание различных вспомогательных классов и миксинов.

Кроме того пополнены новыми статьями разделы "Бизнес-процессы" и "С чего начать разработку"

Поделиться

0 комментариев
Войдите или зарегистрируйтесь, чтобы комментировать
Публикация

Сегодня обновлена документация по разработке bpm'online. Особенностью сегодняшнего обновления является то, что все опубликованные материалы созданы командами разработчиков при участии Академии!
Новые материалы:

Поделиться

0 комментариев
Войдите или зарегистрируйтесь, чтобы комментировать
Публикация

В документации по разработке bpm’online (SDK) для bpm'online версии 7.8 опубликованы новые материалы.
Организация процесса разработки. Из этой статьи Вы узнаете о рекомендуемой последовательности создания новой функциональности в трех средах: среде разработки, среде тестирования и промышленной среде.
Работа с серверным кодом в Visual Studio. В статье изложены все тонкости настройки среды разработки для интеграции с VisualStudio.
Веб-служба DataService. Серия из восьми статей, посвященных интеграции bpm'online с внешними пользовательскими приложениями при помощи Web службы DataService.

Поделиться

0 комментариев
Войдите или зарегистрируйтесь, чтобы комментировать
Вопрос

Добрый день!
Начиная с версии 7.5. в bpmonline itil transitions
появился такой функционал, как очереди, единое окно, процесс управления обращениями из очереди.
В документации к данному продукту, выложенной на сайте, нет ни строчки про это
http://academy.terrasoft.ru/documents/?product=transitions&ver=7.5.0

Где можно почитать описание работы с этими разделами, и почему его нет в документации.

У меня такой же вопрос

16 комментариев

Добрый день, Дарья!

Большое спасибо за Ваше замечание. Данный недочет взяли в работу.

Сейчас Вы можете ознакомиться с функциональностью перечисленных разделов в
руководстве пользователя

Добрый день!
В руководстве по engagement centre тоже не слишком много написано про очереди, правила формирования и т.п.

Рассмотрим продукт ITIL transitions
1)В разделе Очереди есть уже созданная очередь, называемая Обращения на обработку
Создается обращение, где ответственный - текущий контакт, и состояние обращения не конечное.
Такое обращение, насколько я понимаю, должно отражаться в едином окне текущего пользователя.
Но оно не отображается. Почему?
2) Приведите, пожалуйста, пример какие еще могут быть очереди

Здравствуйте, Дарья!

1. Для того, чтобы данная очередь отображалась в Едином окне оператора необходимо указать состояние "В работе". Если для очереди указано состояние отличное от данного, в едином окне оно отображаться не будет.

Так же проверьте при помощи фильтрации в реестре, существуют ли Обращения удовлетворяющие условиям фильтрации в очереди. Если таких записей нет, они так же не будут отображаться.

2. К примеру, могут быть очереди Контактов, по которым необходимо дополнить информацию.

Поменяла состояние обращения на в работе - ничего не изменилось - обращение в едином окне не появилось.
и где собственно задается это условие - про "состояние в работе"

P.S. Обращение, удовлетворяющее условиям фильтрации в очереди, есть.

Дарья, состояние "В работе" необходимо указать в настройках очереди.

Скриншот во вложении.

В настройках очереди указала состояние " в работе".
Создала обращение - ответственный текущий пользователь, состояние - новый.
Обращение условиям фильтрации очереди удовлетворяет.
Но обращения в очереди по-прежнему не видно.

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

Елена, после конструкции http://localhost:6565/0/ServiceModel/ProcessEngineService.svc/QueuesUpd…
процесс запуска очередей запустился.

Проблемы с производительностью сайта версии 7.5.0.1054 тоже сейчас не наблюдается (перезапустила IIS и еще раз очистила Redis)

Но наблюдается новая проблема в едином окне. Пытаюсь взять обращение в работу(нажать на кнопку "Взять в работу"), и система зависает и ничего не происходит ( см. вложение).
Что может быть не так? и что вообще должно происходить при нажатии на эту кнопку.

Дарья, для решения вопроса понадобится более глубокий анализ. Отправили Вам личное сообщение для координации дальнейших действий.

"Татаровская Дарья" написал:

В настройках очереди указала состояние " в работе".
Создала обращение - ответственный текущий пользователь, состояние - новый.
Обращение условиям фильтрации очереди удовлетворяет.
Но обращения в очереди по-прежнему не видно.


Добрый день,
сталкиваюсь с аналогичной проблемой.

Создала очередь с очень простыми условиями Ответственный текущий пользователь или не заполнено, очередь в работе, вижу в журнале процессов "Процесс наполнения очередей единого окна" в состояниях Завершен.
в Едином окне пусто.

Маргарита, вероятнее всего, не запустился процесс наполнения очереди.

Для запуска данного процесса используйте ссылку вида:

http://*****/0/ServiceModel/ProcessEngineService.svc/QueuesUpdateProcess/Execute

Вместо "*****" укажите адрес Вашего сайта.

это действие нужно будет выполнять каждый раз?

Маргарита, данное действие достаточно выполнить один раз.

"Лазоренко Елена Петровна" написал:

Маргарита, вероятнее всего, не запустился процесс наполнения очереди.

Для запуска данного процесса используйте ссылку вида:

http://localhost:6565/0/ServiceModel/ProcessEngineService.svc/QueuesUpda...

Вместо "localhost:6565" укажите адрес Вашего сайта.

Наполнение Единого окна Очередью "Обращения на обработку" происходит,
а вот если отключаю эту очередь "в планах" и включить " в работе" очередь, созданную мной, Единое окно не наполняется, даже после выполнения ссылки.

Маргарита, для решения вопроса понадобится более глубокий анализ. Отправили Вам личное сообщение для координации дальнейших действий.

Маргарита, проблема заключалась в том, что не были указаны операторы на детали "Команда".

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

Коллеги, у нас появилась проблема – как правильнее\удобнее документировать техническую логику проектных решений.
Например – по нажатию «сохранить» в счете проверяется 10 условий и на каждое из них система по разному реагирует. Все это храниться в коде и когда возвращаемся к этому коду через год - очень тяжело понять что и как. Документация, оформленная с клиентом – не помогает – слишком верхнеуровневая.

Подскажите, пожалуйста, а как это у Вас делается?

У меня такой же вопрос

2 комментария

комментировать, комментировать и еще раз комментировать.

"Гусев Александр Юрьевич" написал:Например – по нажатию «сохранить» в счете проверяется 10 условий и на каждое из них система по разному реагирует. Все это храниться в коде и когда возвращаемся к этому коду через год - очень тяжело понять что и как

Техническое задание никто не отменял, если в нем все описано, проблем с пониманием логики не будет. И комментарии в коде, комментарии :smile:

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

Есть документация по написанию скриптов для BPM Terrasoft?
Хотелось бы не методом тыка изучать, а понимать что делать, чтобы решать поставленные задачи.

У меня такой же вопрос

5 комментариев

Здравствуйте.

Синтаксис кода для BPMonline - это стандартный синтаксис языка программирования C#. Мануалы же по структуре классов и интерфейсов продукта доступны в SDK по следующей ссылке: www.terrasoft.ru/bpmonlinesdk

Спасибо.

Спрошу здесь, в тему документации, чтобы не плодить топики...
Как бы подобраться к параметрам т.н. мультивалютного поля - надо менять их динамически.
См прикрепленную картинку
Нужен параметр "Разрешить редактирование суммы"
Уже нашел:) Control.CurrentCurrencyValueEditEnabled
ILSpy полезная вещь

"Александр Кудряшов" написал:

Спрошу здесь, в тему документации, чтобы не плодить топики...
Как бы подобраться к параметрам т.н. мультивалютного поля - надо менять их динамически.
См прикрепленную картинку
Нужен параметр "Разрешить редактирование суммы"
Уже нашел:) Control.CurrentCurrencyValueEditEnabled
ILSpy полезная вещь

Прикрепленный файлРазмер

parameters.png
11.1 кб

IP-АТС Oktell может раз в день с интернета забирать курс валют и сохранять значения в базу Террасофта.

"Соколов Илья Андреевич" написал:IP-АТС Oktell может раз в день с интернета забирать курс валют и сохранять значения в базу Террасофта.

это вот вы мне зачем рассказали? :smile: запись в базу TS средствами Oktell мы в 3х было дело реализовывали, смс напоминания например по сей день используем
у меня вопрос был только по реквизитам для контрола... я может его не совсем в тот топик добавил...
кстати для bpm не стал бы я загрузку курсов делать через сторонний планировщик - можно ж средствами самой системы это изящнее реализовать, тем более прямого доступа к базе on-demand решения нет

Войдите или зарегистрируйтесь, чтобы комментировать