Comala workflow что это
Автоматизация workflow небольшой команды разработки (Часть 2)
В предыдущей публикации я описывал список продуктов и их настройки, которые необходимы для работы нашей организации.
В этой статье я постараюсь описать, как мы это всё используем в ежедневной работе всего коллектива разработки.
Работа в основном в стиле стартапа, когда нет конкретной и подробной постановки. Очень часто эксперименты вроде “а давайте попробуем так, посмотрим что получится” или “вы классно все сделали, но теперь надо все совсем по-другому”.
За эти годы концепцию нашей работы можно описать одной фразой — это “стремительная смена концепции”.
Понятное дело, что применить в таких условиях различные методологии никак не удавалось.
Начинал в этой системе я как программист, потом Team lead, ну а теперь PM (DM). Т.е. руковожу, полностью участвую в проектировании и иногда даже пописываю. Во времена моего программирования у меня был замечательный ПМ (выходец из тестировщиков), которая поддерживала все мои идеи по автоматизации workflow. Даже более того, концептуально этот процесс придуман ей, а я уже смог его технически реализовать и в некоторых местах усовершенствовать.
Перейдем к сути.
Постановка задачи
Все задачи появляются у нас либо после совещания с высшим руководством, либо пожелания от заказчика, либо придумываем что-то сами (или находим баги).
В случаях, когда задача не односложная, собирается мини-совещание из ПМ, тимлида, QA-лида и аналитика. После обсуждения и придумывания, что и как будем разрабатывать, обычно сразу дробим это на логически завершенные небольшие задачки (не дольше работы 1-го дня программиста) и грубо прикидываем сроки на реализацию (для планов для высшего руководства).
Аналитик садится и вдумчиво излагает постановку в Confluence. После этого данную постановку согласовывает с ПМ, а тот при необходимости с высшим руководством.
Затем на основании этой постановки создается задача в Jira.
Часто задачи сразу появляются в Jira минуя этап с Confluence.
Ревизия постановки
При переходе на этот шаг триггеры Jira автоматом меняют ответственного задачи на ПМ-а.
Этот шаг предназначен для того, чтобы ПМ перечитал описание задачи и убедился, что автор правильно понял постановку и корректно описал задание для программиста. Очень часто из-за недостаточного взаимопонимания задача делается и тестируется до самого конца и только уже при релизе видно, что сделали совсем не то, что изначально требовалось.
Также на этом шаге ПМ принимает решение нужно ли реализовывать вообще данную задачу. Или нужно ли ее реализовывать именно в эту версию.
На этом этапе есть два варианта workflow: вернуть назад на постановку (доработку описания) или продвинуть дальше в работу.
Также я часто на этом шаге назначаю ответственного тимлида для того, чтобы он сам определил исполнителя
Ожидание работ
При выборе этого шага я настроил экран, в котором надо задавать исполнителя, поле “Программист” и планируемое время.
Этот шаг — пул задач программиста, который надо выполнить за версию в порядке, указанном в поле приоритет или в порядке любом удобном, если приоритет одинаковый.
Так уж получается, что во время работы над версией частенько этот список пополняется.
В работе
У нас в команде договоренность, что мелкие правки типа подвинуть кнопку правее или раскрасить зелёный зеленее, можно сразу бросать на сборку. Иначе — ОБЯЗАТЕЛЬНО на ревизию кода.
Итак, бросаем задачу на ревизию кода, и при этом ответственным назначаем тимлида.
Ревизия кода
На этом шаге тимлид в специальной секции Development в Jira смотрит какой именно комит был сделан программистом и нажимает специальную кнопку “Code Review”.
После нажатия автоматически открывается Crucible и создается ревью на указанный комит (или несколько комитов).
Тимлид может видеть дерево файлов, которые правил программист ну и соответственно диференсы. Может оставить комментарий к любой строке кода или общий к ревизии. Crucible позволяет даже указать степень критичности проезда программиста.
После мук изучения чужого гуанокода, тимлид либо проталкивает задачу на шаг сборки, либо возвращает программисту в ожидание работ.
Программист в этом случае в секции Development видит Code Review и его статус. При переходе на этот Code Review опять же открывается Crucible, где программист может наглядно увидеть, где именно он налажал.
При переводе на шаг “Ожидание сборки”, тимлид выбирает ответственным тестировщика, который указан в спец поле, либо если оно не заполнено, то QA-лида.
Ожидание сборки
Так как сервер тестирования у нас один общий, то сборка по расписанию не годится. Нельзя подменять сайт во время его тестирования.
Поэтому обычно у нас тестировщики договариваются и, если никто не против, собирают себе свежую версию ресурса.
Делают они это с помощью Jenkins. В нем созданы по три сборки на каждый проект: сборка для тестов, сборка для разработки, сборка БД.
Ожидание тестирования
На этом шаге могут быть задачи, которые уже были в тесте, а могут быть и в первый раз. Если задача уже в тесте была, то тимлид уже ответственным ставит именно того тестировщика, который вернул задачу в работу.
Иначе все задачи скапливаются у QA-лида. Он смотрит на пул задач и нагрузку каждого тестировщика, и определяет кому назначить задачу на тест. Более того, сразу же определяет и тестировщика для парного тестирования.
Тестирование
Ожидание парного тестирования
Этот шаг был придуман по нескольким причинам. Многие не понимали его целесообразности, но в итоге спустя какие-то время соглашались, что он необходим.
Суть его заключается в том, что есть основной тестировщик по задаче, который очень глубоко и усиленно ковыряет задачу со всевозможных аспектов и есть парный тестировщик, который поверхностно просматривает задачу только после полностью завершенных тестов первого. Это очень похоже на ревизию кода у программистов.
В итоге получаем то, что не только один тестировщик знает как устроена та или иная функциональность. Если задача футболялась 10 раз между программистом и тестировщиком, то свежий взгляд парного тестировщика может заметить что-то пропущенное. Ну и самое важное, то что каждый тестировщик работает по-своему и привыкает использовать софт определенным образом (логинится не используя мышь, аплоадить файлы драг-н-дропом, вместо фильтров использовать сортировки, при вводе данных копипастить тексты и т.д.). Очень часто бывает, что одни и те же функции можно использовать по-разному, и парный тестировщик натыкается на ошибки, которые были проверены основным, но немного по-своему.
Парное тестирование
Если на этом шаге обычно уже можно считать, что задача почти закончена. И очень часто, когда поторапливают с выпуском версии, его можно пройти формально.
ReadMe
После успешно проведенных тестирований уже окончательно определена функциональность и ее реализация. И вот теперь этой задачей занимается техпис. Обычно все задачи, кроме совсем незначительных или тех, которые сами сломали в процессе работы над версией, мы помечаем меткой “ReadMe”.
Парный тестировщик, если видит эту метку отправляет задачу на шаг “ReadMe” и назначает на техписа.
Техпис в специальном поле описывает очень кратко Release notes по этой задаче. Обычно это оповещение пользователя об изменении функциональности или исправлении ошибки, или о появлении новой функциональности и как ей пользоваться.
На этом же шаге техпис исправляет или дополняет справку ресурса в Confluence.
После проделанной работы, задача отправляется на финальный шаг “Ревизия функциональности”.
Ревизия функциональности
При переходе задачи на этот шаг, триггеры Jira автоматом назначают ответственным ПМ-а.
На этом шаге ПМ проверяет работу всей команды в целом. Было ли реализовано то что хотели, именно так как хотели, нормальное ли описание в ReadMe и т.д.
Бывает, что на этом шаге оказывалось, что программист с тестировщиком что-то между собой порешали и отрезали “ненужную функциональность” или изменили ее потому что посчитали так лучше, и именно эта функциональность требовалась высшим руководством и именно в таком виде. Тогда задача опять идет на “Ожидание работ”.
Ценность данного шага заключается в том, что хороший ПМ или ДМ после выпуска и звонка заказчика с фразой “что вы наделали?”, должен знать как именно реализовали задачу, как назвали кнопки, тексты сообщений, нюансы алгоритмов и смело ответить “сам дурак”. А не мяться и гадать, а как же они сделали ту форму и чего в ней кнопка задизейблена…
Закрыто
Ну тут все и так понятно. Задача закрывается после удачно прошедшей ревизии функциональности.
Или задача в любой момент может оказаться никому не нужной, потому переход на этот шаг возможен с любого другого шага.
Рабочий стол
Выпуск версии
При выпуске версии, мы выгружаем из Jira все задачи версии в виде двух колонок: компонент и поле ReadMe. Вот и получается у нас ReadMe сгруппированное по разделам.
С помощью “Scroll HTML Exporter” мы экспортируем страницу хелпа в Confluence и все ее дочерние страницы в набор html файлов, которые внутри выглядят так же красиво как в Confluence и ссылаются друг на друга.
Итоги
Вот по такому workflow мы уже работаем несколько лет, иногда его дорабатывая и дотачивая.
Но в целом он очень удобен.
Для ПМ тем, что в любой момент времени видно, кто именно и на каком шаге держит задачу.
Для разработчиков удобно видеть только свой объем работ.
Ну и, конечно же, автоматизация на всех шагах. Т.е. нет такого человека, без которого рабочий процесс может остановиться.
workflow
Legacy Workflows Documentation
Looks like you followed an old link. Comala Workflows is now Comala Document Management.
Please access our latest documentation here Welcome to Comala Document Management
Documentation for other versions of Comala Workflows are available too.
Purpose
The workflow macro is used to define a workflow and is used to contain a collection of states, approvals and triggers. All macros used to define the workflow must be encased inside a workflow macro.
Syntax
Parameters
Names the workflow. Workflow names must be unique within a space.
A comma delimited list of labels. The workflow will apply only to pages that have one of the specified labels (or none of the labels if the invertlabel param is set.)
A comma-separated list of labels which, once added, can only be removed by a Confluence or space administrator.
A comma-separated lists of users who should be considered workflow administrators. Using this parameter expands the access to the admin=true function beyond Confluence and space administrators.
header or
headertemplate
The template name to be rendered as a header on all pages on which the workflow is present. The template reference can include the space, i.e., SPACEKEY:template.
footer or
footertemplate
The template name to be rendered as a footer on all pages on which the workflow is present. The template reference can include the space, i.e., SPACEKEY:template.
Examples
Workflow Header
You can create a template and have that template rendered on all pages on which the workflow is active. For example, create a template PageHeader in the space DOCS with the following Confluence wiki markup code.
The workflow refers to the PageHeader template:
For more information of the wiki markup language, see Confluence Wiki Markup. The use of the headertemplate / footertemplate parameters is an alternative to defining the header and footer in the workflow code with the pageheader and pagefooter macros.
If the reference to the template does not specify a space key, it will refer to a page in the same space where the workflow is active.
Legacy Workflows Documentation
Looks like you followed an old link. Comala Workflows is now Comala Document Management.
Please access our latest documentation here Welcome to Comala Document Management
Documentation for other versions of Comala Workflows are available too.
This tutorial helps you to learn how to create workflows using the workflow markup. If you are evaluating the plugin, use the Workflow templates provided with plugin.
This tutorial focuses on a central need of many Content Management Scenarios: that content should be visible to only those people involved in the workflow until that content has been seen and approved by relevant parties.
The example below is based on the Editor and staff approval workflow already provided as a workflow template.
Specification
We start by defining four «states» that any given page can be in: Draft, Ready, Reviewed and Published.
These are all «transitions»; they define how the work flows between those states. In addition to the forward flows, there are some that lead backwards:
Creating the workflow
You have 2 options to create the new workflow:
Using the workflow macro
Like most things in Confluence, a workflow is defined using Confluence Macros.
Using the state macro
Each state defines:
The initial ad hoc workflow created already contains our initial states:
The states include the taskable=true parameters because we created the workflow as an ad hoc workflow; however, we are going to override the entire workflow.
Defining the transitions
We need to define the following transitions:
When the system reaches the Published state, we apply the Final Marker to the version of the page. Usually non-contributors only see final versions.
Save the workflow
You can save the workflow now.
Trying our State Changes
Let’s try out the workflow.
The page is shown in its initial Draft state:
From there you can submit the page:
You can now transition the page towards the Published state with each approval. You can view the current state by hovering over the Page activity link:
Understanding the Comala Workflow Engine
Legacy Workflows Documentation
Looks like you followed an old link. Comala Workflows is now Comala Document Management.
Please access our latest documentation here Welcome to Comala Document Management
Documentation for other versions of Comala Workflows are available too.
This article covers the theory behind the Comala Workflows engine. This article is not intended as a tutorial per se, but rather as a backgrounder to help workflow designers understand how the engine works. For detail examples see Tutorials.
What are Comala Workflows?
The Comala Workflows plug-in delivers a collection of macros that can be used to generate custom workflows for use with Confluence pages. Many business processes require some sort of formalized workflow for creating, approving and publishing documents, whether for external documentation, internal specifications or for policies and procedures. Comala Workflows macros help automate these processes without the need of complex programming languages.
Workflow as a State Machine
The macros used in Comala Workflows are basically a state machine description language (see sidebar). A workflow first defines each state a page must pass through in a process (using a state). For example, a simple process for a sales plan might include: draft, review, VP approval, final. For each of these states, a workflow designer can define the criteria (events) to move from each state to the next. For example, in the draft state, the article sales person may be assigned tasks to complete (using a task), such as «list each customer opportunity,» «briefly describe each opportunity,» and «define the revenue potential.»
A page which has a workflow applied to it must always be in a defined state. There is no default state—a page cannot be in limbo.
Once the sales person has checked off as having completed each of the items, the page can then progress to the Review state, possibly by a sales manager. In this case, the review is viewed as a type of approval (using the approval). The sales manager can either approve the sales plan (sending it for VP Approval) or reject the sales plan with a comment (sending it back to draft). VP Approval is handled similarly, using another instance of the approval macro. If the VP rejects, the workflow can be designed to either return the sales plan back to either review or draft. If approved, it can advance to the last state, Final.
Workflow macros allow for more complex definitions of state transition events than described here. For example, a state can transition because it has exceeded a due date, a user has updated a page, or added an attachment. These events can also be used to trigger/execute (using the trigger) a number of other operations. Similarly, approvals can be either simple, or more complex, for example, requiring all members of a group to approve, requiring a special sequence of approvals, etc. The macro language even allows a workflow to publish an article automatically (see Understanding Publishing])
What is a State Machine?
A traffic light can be used as a simple example of a state machine. A traffic light (in the US) has to be in one of three states:
The state diagram below illustrates each state and defines the triggers for the traffic light to transition to the next color or state. Each state has a timer to determine how long the traffic light should remain in each color. For example, this traffic light remains red for 20 seconds. When the timer reaches 20, the light transitions from red to green and resets the timer. While green, once the timer reaches 15 secs, the light transpositions to amber.
In real life, the state machine for a modern traffic light is more complex as it must control the lights in both directions, plus must add a few additional conditions:
Types of Defined Workflows
There are two basic types of workflows, which differ not in how they are coded, but in how they are applied to pages:
How to Define a Workflow
As an example workflow, lets examine the steps to design a simple documentation process. The complete code for this sample workflow can be found in Basic Workflow Structure.
Step 1 – Define the Needed States
The first step is to determine what states are needed for the workflow. For the example documentation process, these states could be:
How to Define States
Within Comala Workflows, states are defined using the state. The macro is used to define the name of the state, as well as some of the exit/transition criteria (see How to Transition Between States below). For example, to define the Assign Author state, the syntax would be:
Clearly there is more that needs to happen in this state. How to transition between states is covered in Step 3
Step 2 – Define the Needed Tasks for Each State
For some of our states, tasks need to be assigned. Tasks are useful for when:
In our example workflow, tasks are useful for the Planning state where the page author is tasked with writing an abstract and an outline. The syntax for assign these tasks in the Planning state is:
The syntax above defines the two tasks to a user specified by the variable pageauthor and places notifications on the user dashboard under «My Comala Workflow Tasks.» Once the user marks both tasks as complete, the workflow transitions to the next state automatically.
The variable pageauthor represents metadata set during the Assign Author state (not shown above). See Using Metadata below for a discussion variables and metadata.
Step 3 – Define How the Article Transitions between States
The next step is to define how a page moves from one state to the next. There are many events that can be used to cause a state transition, among these are (this list is not exhaustive):
There are two ways to define these transitions:
Defining a State Transition with the Macro
For a certain class of events, how a state transitions (and to what state) is defined using a parameter setting within the macro. For example, in the sample workflow above, we need to define what happens in the TW Review. In this state, the tech writer can either accept the page, complete his/her edits and send the page for final review, or reject the page to send it back to the author for more work. This scenario can be handled with as an approval. Defining an approval requires two parts, first is using parameters of the state macro to define what the next state is after approval or rejection:
Next, the approval and who the approver is (defined by the variable tw) must be defined:
Defining a State Transition with the Macro
In the sample workflow, an author needs to be assigned to the page and then have the page transition to the Planning state. Assigning the page is simple, and in the state macro:
We want the user to be presented with a dialog box to set the page author. This must be done with a
The above trigger fires when the page is assigned to the author while in the Assign Author state. It uses the
In actuality, if the
Step 4 – Define How to Initiate the Workflow
Workflows can be applied to a page in one of three ways:
In the sample workflow, assuming that the workflow has been activated at the space level (see Manage workflows), the workflow automatically initializes the page when it is created and sets the state to Assign Author, but the page has not been assigned to any user (meaning no email notification or dashboard notice). To have a newly created page be assigned to the tech writer regardless of who created the page and set an instructional message on the page, the following
With this code, when a page is added (created) in a space where this workflow is active, it will automatically be initialized to the Assign Author state and assigned to the tech writer, sending an email notification and adding a dashboard notice under My Comala Workflow Tasks.
Step 5 – Determine How Articles will be Published
Probably the most powerful aspect of workflows engine is how it handles publishing content. The engine handles separating draft from published versions of a page by restricting the view of any user without editing privileges to only being able to see the published version of the page. The workflow engine has added flexibility in that it allows for three different scenarios for handling content creation and the display of published content to the public:
In all of these scenarios, editors (anyone with editing rights for the page) normally see the most recent version of the page. However, editors can click the Published button at the top of the page to view the published version of that page.
For the sample workflow, we will use a simple, same-space publishing scenario. Once the final approval is given, the article will be automatically published (moves to the Published state, marked as the final state of the workflow).
Step 6 – Define How the Workflow Recycles
To be useful to the end user, content must be maintained. Currently, the sample workflow ends at the Published state, with no provisions for how to to handle an update. We could start a new page copied from the published version and start the flow again, or a better approach is to update the workflow to handle the article refresh process for us. The simplest approach is to detect when anyone with edit permissions edits that page to return the article to Draft and restart the process from there. For the workflow, a simple modification is required, adding the updated parameter:
Now when anyone edits the page, the editable article returns to the Draft state, leaving the Published (final) version still visible to users.
Detecting Attachment or Label changes
Another common need is to handle what happens when an attachment is updated. We’d like our workflow to detect the update and return the article back to TW Review even when the change does not involve the content on the page. By adding another trigger macro we can program this additional functionality. Comala Workflows has similar functionality for detecting the change of labels on a page.
Now the sample workflow will cycle back to Draft if the page content is updated, or back to TW Review if an attachment is updated.
Basic Workflow Structure
The structure of a workflow has four basic parts
In code, the basic structure is as follows:
Using the sample workflow defined above as an example, the fully coded workflow is as follows:
Using Metadata
Often when designing a workflow, the ability to store page- and workflow-specific data is needed so that it can be retrieved later, adding to the workflow’s flexibility. Typical examples for uses of metadata are for storing the names of page authors or reviewers for later use, for example, when a page is rejected in a later state and needs to be sent back to the author for rework. The sample workflow takes advantage of this ability to store the page author’s name with the
In this example, that assignee for the page is saved as the metadata value pageauthor and can me used to display a message, for example:
And data saved as metadata can also retrieved for workflow reports (see Reporting)
Workflow versus Action Macros
There are two classes of macros:
Approval versus Assignment versus Task
There is some overlap in how approval, assignment and (a single) task function, and in some cases, these macros could be used interchangeably. Each of these macros causes a notice to be posted on the targeted user’s dashboard under My Comala Workflow Tasks but how the user interacts with the page differs:
Which method to use depends on the requirements of the workflow and how automated and tightly controlled the workflow designer wants the workflow to be.
Limitations
There are some limitations to the capabilities of the workflow engine. Understanding these limitations will help when designing workflows: