We are very pleased to reveal our new family member of management tools for Atlassian’s widely used corporate wiki platform Confluence: Managed Data Fields. In this article we’ll explain what the new extension for Confluence is all about and how you can use it to simplify data management in Confluence.
Overview
Managed Data Fields allows Confluence users to globally define structured Data Fields, access and instantiate them with values on Confluence pages, and monitor and analyze these values permanently as they are changed. Hence, the Confluence App not only enforces the structured documentation of information but also bundles this information in one place, allowing to conveniently make informed, data-driven business decisions.
For example, employing Managed Data Fields to improve your company’s business process documentation in Confluence allows to easily monitor and evaluate the entire process landscape and answer questions such as “Are there any Finance process documentations with status ‘Draft’?”. However, the use cases to leverage the App’s capabilities are manifold and not solely related to process documentation.
Components
The functionalities presented above are realized by the interplay of three major components that are explained in more detail in the following section.
1. Field Definitions
Field Definitions globally determine the type, structure, and possible selection values for all your Data Fields. We distinguish between the following types of Data Attributes:
- Text: Free text
- Date: Calendar date
- User: Allows to mention Confluence users
- Dropdown, Option Field: Allow to select one of several predefined selection values
- Multi-Select: Checkboxes that allow to select none to many predefined selection values
Managed Data Fields also allows to freely combine several of these Data Attributes in one complex Field Definition, allowing to capture a variety of information in one data structure.
2. Field Instances
Once defined, Field Definitions can be instantiated on any Confluence page. An instantiated Field Definition is referred to as a Field Instance that carries analyzable data. To add a Field Instance, simply insert the Managed Data Fields macro into a place of your choice on your Confluence page. A dialog allows to browse through all existing Field Definitions, preview their appearance, and directly enter values. After having placed a Field Instance on the page, its values may be changed anytime by editing the corresponding macro in page editing mode.
Field Instances always conform to their underlying Field Definition in terms of appearance, defined Data Attributes, and predefined selection values. Hence, changing a Field Definition instantaneously also updates all related Field Instances, making it simple to add new selection values or even whole Data Attributes. However, Field Instances only automatically adopt changes if no data is lost. For example, if a Data Attribute is deleted from the Field Definition, Field Instances carrying values for the specific Data Attribute will not automatically remove it but rather inform the user by displaying appropriate symbols. In this case, it is possible to manually trigger a synchronization that removes the related data from the Field Instance.
The example below shows a Field Instance whose underlying Field Definition was modified. While the Data Attribute "Process ID" is added automatically, the Data Attribute "Name" and the selection option "Released" are marked as non-conforming.
3. Field Queries
The third and most powerful component of Managed Data Fields is the Field Query. Field Queries allow to search for and monitor the value states of Field Instances of a specific Field Definition, no matter where they hide in the jungle of Confluence pages. Field Queries can simply be added to a Confluence page as Confluence macro (just like Field Instances). The corresponding dialog thereby also allows to search only for instances with specific values and/or limit the query to a certain Confluence space. After having inserted the Field Query macro into the Confluence page, the result set of Field Instances is displayed and, of course, constantly kept up to date. The result table includes a link to each matching Field Instance, along with the Confluence space and currently selected values. Confluence’s permissions system is fully accounted for by displaying user-dependent results. Hence, Field Instances on restricted Confluence pages are completely excluded from the result set if the currently logged in user has insufficient permissions.
Workflow
To get you started with Managed Data Fields right away, the following section illustrates how a Data Field is defined, instantiated, and queried for.
1. Creating a Field Definition
As described above, Field Definitions are managed globally, i.e. beyond the Confluence page/space scheme. However, after having freshly installed Managed Data Fields you may expect to interact with it just like with any other Confluence App. Therefore, you can enter the Field Definition area by selecting the Managed Data Field macro on any Confluence page. The integrated macro dialog serves as the central hub to interact with the App. To enter the Field Definition area, simply choose “Field Definition” and click the "Create" button. Note that this action will not create any macro on your Confluence page but rather redirect to the Field Definition area in a new browser tab.
There does exist another, more convenient way to access the Field Definition area. To receive a global link prominently placed in the Confluence header bar, create the Confluence user group “managed-data-fields-editors”. Once this group is created, all group members can visit the Field Definition area permanently via the global link. At the same time, however, non-group members will not be able to enter the Field Definition area via the macro dialog anymore.
The Field Definition page not only allows to create completely new Field Definitions but also alter existing ones or delete them completely. Note, however, that deleting a Field Definition does not automatically delete all its Field Instances to prevent data loss. Rather, all related Field Instances will be marked accordingly.
When creating a new Field Definition, you can either create one of a single Data Attribute or assemble a complex Field Definition containing several Data Attributes. The picture below shows the configuration of the "Process Documentation" Field Definition with four Data Attributes. Note that for Dropdown, Option Field and Multi-Select Data Attributes, there must also be at least one predefined selection value in place.
2. Creating a Field Instance
Let’s bring our newly created Field Definition to life by instantiating it with values on a Confluence page. To do that, choose “Field Instance” and select the corresponding Field Definition. The editable representation of the Data Field allows to preview its appearance on the Confluence page and directly enter values. After submitting, you can find your Field Instance macro in the page editor under its Field Definition’s name. Publish the page to finally persist the Field Instance in the App's data storage. Note that Field Instances are read-only when viewing a Confluence page. In order to update its values, enter the page editing mode and select the Field Instance. A context menu then displays the Data Field in an editable form. Don’t forget to save your changes and you are good to go!
3. Creating a Field Query
Choosing the respective tab in the dialog allows to configure a new Field Query. Just like when creating a new Field Instance, you are first asked to select one of the existing Field Definitions to perform a query for. In our case, we choose the prior created "Process Documentation" Field Definition. You can either configure the query to retrieve all Field Instances (irrespective of their current values), or narrow the result set down to Field Instances with specific values. To apply a value filter, simply select the values in the presented representation of the Field Instance. Note the difference: Single selection Data Attributes, such as dropdowns and option fields are displayed as checkboxes. This allows to apply a value filter consisting of more than one value. For text type Data Attributes, multiple search values can be applied by comma separation. Field Queries with an active value filter are performed after the following logic: for each Data Attribute with one or more specified values to search for, the retrieved Field Instances’ Data Attributes must contain at least one of the specified values. As a second refinement option, you may limit the query to Field Instances of a certain Confluence space. After submitting the macro and publishing the page, the Field Query is performed on any page visit. Hence, your result set is always up to date.
Upcoming Features
We just started making it simple and more convenient to manage and monitor data in Confluence and there are many more features we can think of. In the near future, for example, we are going to provide Field Queries with a major upgrade: Charts! As our goal is to provide you with a tool to quickly gain an overview of your current data situation to base your business decisions on, charts appear to be the most intuitive way to consume such information. Hence, you can look forward to functionality that allows to configure your individual dashboard of charts that monitor your Data Fields.
Moreover, we plan to integrate Managed Data Fields with our BPMN Modeler for Confluence Enterprise. Ever thought of monitoring data related to single process elements in a BPMN diagram? We are delivering the solution in tandem with our widely used process modeling tool.
Finally, we are trying to constantly improve the App’s user experience and therefore appreciate any kind of feedback of our users. Feel free to get in touch with us to discuss new features, mention problems or report bugs.
Get your Managed Data Fields Trial Version for free in the Atlassian Marketplace!
For more information visit our Product Page or check out the Managed Data Fields User Manual .
Back to blog overview
