Nektion Formula Language Basics
Adding item fields
Nektion in a nutshell
The core idea in Nektion is that you can adjust the tool to the way you are working:
1) set-up a model that corresponds to the terminology you use and how you group things together, and
2) create views based on the model that supports the way you manage work, make decisions, and follow up on things (see Picture 1).
In other words, rather than figuring out if a predefined set of features in a tool fits your use cases, you can set up Nektion just right for your needs.
The two most important concepts in Nektion are contexts and views. Contexts are used to logically group the “pieces” of your work models such as product, team, sprint, feature, and user story. The views then use your contexts to display items in a structure that supports managing work and collaboration.
Picture 1: Example of a model and a board view that is created using the model
One of the big benefits of Nektion is that once you define your contexts and views, you can create items in views and drag and drop them within and even between views. This enables you to create really efficient workflows. For instance, you could have a list view where you prioritize tasks by putting the most important ones at the top, and then you can open a board view where you allocate the tasks to your team members by drag-and-dropping them from the list view.
Let’s take a practical example of how you set up things in Nektion. In this example, we have a product with new commercial releases coming once per quarter. There are teams doing the development that can vary between releases and that do their work in sprints. From a product management standpoint, it is key to manage which features go into a release, whereas the teams work on stories that are completed in a sprint. In this example we want to set up the following views:
A view with Features that have been added to the product and to what stories they are split to
A product kanban view where we can create new features and move them from new to validation to next up to development to done
A list view where we can prioritize our next up features
A roadmap timeline where we can show different features will be ready and in which release
A view to see the content of a release
A view for teams to see their backlog, the stories, and their parent Features
A list view for teams to prioritize their stories
A sprint board for managing the state (Not Started, In Development, Done) of the stories
Picture 2: The conceptual model in our example
At this point, it is also worth noting the difference between item/relation types and items/relations. Product is an item type, but iPhone and iPad could be the names of two items of the type Product. We could have the relation type called Product has Release that is used to create one relation between iPhone and Release 2020 and another between iPhone and Release 2021. When we define a model, we define item types and relation types, when we use the views we create items and relations. From here on, when we refer to concepts in Nektion, we will write them in italics.
Creating a practice account
Even if you have an existing Nektion account, it can be useful to create a practice account to go through this tutorial. Alternatively, you can just read the tutorial.
In Nektion, there are three main types of objects to model a hierarchy of different concepts: relation types, item types, and contexts.
Item types are types used to represent different items. We could create an item type called Product, for example, which could represent our company’s individual products.
Relation types are used to indicate relations between two or more item types. For example, if for every product, there could be some features planned, we could create a relation type called Product has Feature, where Product is the “parent”, and Feature the “child”.
Contexts are objects used to group together item types and relation types closely connected to each other. A context could be as shown below:
Picture 3: Example of contexts, relation types and items types in a model
In the above picture, Product is hierarchically a top item type. It has a relation type to a Release and to Feature. Furthermore, a Release also has a relation type to Feature, since we want to be able to add Features to an item of type Release. Then there is a relation type from Feature to Story.
We can call our first context for instance Product Context and it consists of the following relation types:
Product has Release
Product has Feature
Release has Feature
Feature has Story
It is important that the direction of the relation types is hierarchical from “parent” to “child” and therefore we should not create a relation type like Release has Product. Another way to think about it is that in general, the relation type direction goes from one to many, for example, one Product has many Releases, one Release has many Features, and so on.
Note also that there could be multiple relation types between the same item types. For instance, we could have a relation type called Product has wished Feature that is used for Features that someone (e.g. a customer) wishes will be included in the product backlog.
We have a second context with Team as the top item type. We can call it Team Context where we define the following relation types:
Team has Story
Team has Sprint
Sprint has Story
Note that the above model might well have been defined differently. For instance, there is no Team has Feature relation types, so you cannot allocate a Feature directly to a Team. What is the correct choice boils down to how you want your model to work. You can always tinker with it and change it later.
We have one more context that we need to create. In Nektion states are also item types. From our views (see product kanban and sprint board), we have a state model for our Features and Stories. We can group these into a State Context where have the relation types (note the direction from parent to child):
Feature State has Feature
Story State has Story
Note here again the direction. The parent type is the one that can have multiple of the other, but not the other way around. For example, a Feature has at any given moment one and only one state, but multiple Features can have the same state.
Accessing Nektion Model Tools
To create your model in Nektion, you have to use the Nektion Model Tools. They are accessible by clicking on the small circle in the upper left corner and selecting Model Tools from the menu.
From the Nektion Model Tools you can create and manage your contexts, relation types, item types, and fields, and configure access rights for users.
Picture 4: Nektion model tools
In order to create a context in Nektion, go to the model tools and open the contexts tab. Press “Add Context” to create a Context. In the dialog that opens, click on the NAME field to give it the name you want e.g. Product Context. The name is saved by clicking outside the editing area. When you have named the Context press the save button.
Now you have a new context. The next step is to add relation types to the context.
Note that if you have existing relation types (displayed in the relation types tab) and want to add them to the context, you can do this by using the “open to right” function to have both tabs open and drag-and-dropping the relation type on the context.
Picture 5: New context creation
Creating relation types
To finalize the Product Context, we need to create the relation types to it:
Right-click on the Context you created and select add child -> relation type. Name your relation type and press enter.
2. Add the relation types you need. When you create a relation type, you add the start item type, the name, and the end item type. The name is often just a verb such as “has” in which case the relation type will be displayed like this: “[Product] has [Feature]”
If the start/end items you are adding don’t exist, you can create them!
When you are done with the Product context, consider also doing Team and State Contexts using the steps above.
Picture 6: Adding a relation type
Picture 7: Create a new item type if it doesn’t exist
Item Type Icons
Adding icons to item types is something that you should do to make it easier to distinguish what types of items are shown in different views. Not only are the icons displayed in the views, they also provide a hover effect that tells which item type the icon represents if you put the mouse cursor on the icon.
Nektion provides a large collection of different icons to use for your item types. For example, if you had an item type called “Story” like the examples in this tutorial, an appropriate icon could be the “sticky note” icon.
To add icons, open the item type’s details view. Here, the row below “Name” says “Icon”.
Click on the pre-selected icon to open the icon catalog. If you don’t find an appropriate icon from the first ones, try searching with different keywords. Once you’ve found a good icon, click on it and then press “Select” to confirm.
Picture 8: Pick your icon from the picker
Overview of the Nektion User Interface
The Nektion UI consists of a menu with different folders on the left side where different items can be accessed. When you open an item, there are tabs under which you can find different views. Every item of the same type has the same views by default.
Picture 9: Nektion UI (after it has been configured and some items created)
The main way to access different views in Nektion is through the side menu that consists of folders that display different items that can be clicked to access their views. For instance, you could have a folder called Projects that contains all projects and by clicking a particular project you access the project’s work breakdown view.
Folders can be created via Nektion [model tools]. In the model tools, select the tab “Folders”. Clicking the “Add Folder” button opens a view like the below:
Clicking the “New Folder” at the top of the small window allows you to change the folder’s name.
You can now save the folder, and it should appear in the menu on the left.
By right-clicking on the folder and selecting “edit folder” you can open the editor again and define what items to show there. The relevant field in the folder’s details view is the one called “Items”. Here you can write the following type of formula (see Note below before you do it!)
->> ”Product has Release”:1234568
you cannot copy-paste the formula because the item type ids (e.g. 1234567) should be ones that are used on your account
when you start writing the formula, there is an autofill function that will suggest formulas, item types, etc.
you should use it to select the correct choices because the autofill will generate the correct ids for item types, relation types, and contexts
The above formula fetches all items of type Product and expands the tree to include every Release that is linked in a Product.
When you have defined the folder, it will show the text “This view is empty” in the menu. By right-clicking on the text and selecting “add sibling”, you can create your first item in the folder. When you have done it, you can right-click on the Product you created, select add child, and create a Release to the Product.
Picture 10: Creation view for folders
Picture 11: Editing a folder
In the same way you can add another folder called “Teams”, where you can display the Teams and Sprints.
Item views can be created via an item type’s details view. To access it, open an item of the desired type (for example a Product item). Next to its name in the title bar is a vertical ellipsis ‘⋮’, and clicking it opens a menu where you can select “Edit type”.
In the “Views” section of the details view, click on the “Add” button and select the type of view you want to add.
In order to show something in a view, you need to define what type of items you want to see in it. This is discussed in the next chapter and also for every view separately.
Picture 12: Adding a view
Nektion Formula Language Basics
To define what items you want to see in a view, you write a formula in the view’s Items field. The pattern you have for defining a view is that you have a start item and then you follow contexts and/or individual relation types to arrive at some items you want to see. In the chapter “Creating folders” the start items were defined by ITEMSOFTYPE(“Product”:1234567), i.e. any item that is of type “Product”. However, when we want to define a view for a particular Product, we usually want to define the start item with the function NODE().
NODE() refers to the so-called context item. In other words, we could have in the menu multiple products, Product 1, Product 2, etc, but when we open Product 1 (=context item), we want to see in the tree view items that are specifically related to it, and not to those other products.
We have four ways to follow the items from our start item. The double arrow operator (->>, also called “expand”) will include the start items and all the items that are on the path of the relation types when “expanding” forward from the start item. For instance, in the example in the Creating folders chapter, we used ->> because we wanted to see both our Products and the Releases there were for each product.
Alternatively, we could use a simple arrow (->, also called “hop”). The simple arrow makes a single hop from the start item. It could be used for instance to show in a list all the Features that a Product has in its backlog.
In addition to the above operators, we have <<- and <- which are otherwise the same as their sisters above but follow the relation types and contexts in the other direction.
One last thing to know is the filter operators.
Details views are used to show different fields of an item, such as description, state, due date, responsible, and so on. Every item type has by default a details view so one doesn’t have to be created separately.
A more in-depth dive into adding item fields to details views is in the chapter “Adding Item Fields”.
Picture 13: a details view
Tree views are used to show items that form a hierarchical structure.
We can start by adding a tree view by clicking on a product in the menu, selecting “edit type” in the three-dot menu, and then adding a tree view to the views section.
One way to display what we have in our Product context is to write the following formula in the Items field:
NODE() ->> ”Product Context”:1234569
“Product Context” here refers to the context defined in chapter “Contexts”.
In the new view, you can add items of the following types: Release, Feature (both as a child of the context Product, and any Release), and Story (as a child of a Feature). While this is fine, we can take it a step further and limit the tree to only show a view of the Features and their child Stories. Modify the formula as follows:
NODE() ->> ”Product Context”:1234569 <<- ”Feature has Story”:1234570
Here, the backward-pointing arrow means that the formula will expand from every Story back to the parent Feature, and discards everything else, like the Product or any Releases.
As a final thing, go ahead and create a few Features for our Product and some Stories for them. This is a good way to check that your setup works as it should.
Picture 14: A tree view
Picture 15: Adding a tree view
Nektion boards are useful for displaying data divided into a few groups. For example, a use case could be displaying Features divided into categories based on their states.
Start by creating a board view (you can call it “Kanban”) as instructed in the chapter “Creating Views” and open its details view in front of you. Enter the following formula to the Items fields:
NODE()->> ”Product Context”:1234569 _|TYPE(“Feature”:1234572)
The operator _| is used to filter out from all the items we have in Product Context the ones that meet our criteria, in this case, the items that are of type Feature.
From the “Views” section, click the “Add” button and add a “Board dynamic columns” item. You could name the item “Feature States”, for example. Dynamic columns allow the number of columns to be dynamically changed depending on the situation. Here, the aim is to include every Feature State, and, if need be, to automatically add any new ones to the board should you create any.
Into the dynamic columns’ items, enter the following formula:
Next, in the dynamic columns’ details view, add a “Board column” item under the dynamic columns you just created. Its name could be, for example, “Features Per State”. For its items, enter the following:
Picture 16: A board view
Picture 17: Board setup
Now open the board. You should see a view like this if you don’t yet have the Feature States created
You can create the Feature States by right-clicking the column title. A useful way to divide the states could be:
Now if you have done all this you will have … an empty board. The thing is that the Features you created in the tree view don’t yet have any state set for them. Right-click on the tree view tab (“backlog” if you named it as was suggested) and select “open to right”. Now you should have both the board and the tree view open and you can close other views that are open.
You can now drag-and-drop Features from the tree view to the Board and thus set the state to whatever you want. And of course, you can drag and drop the Features you have on your board to change the state again. You can also create new Features on the board by hovering your cursor on the bottom of a column – the Features that you create on the board are also automatically visible in the tree view.
Picture 18: Adding a column
Timelines show items in a horizontal view based on the items’ start and end dates. These dates could be made to update automatically, for example, to assign the end date to the day a Feature’s ‘state’ was changed to ‘Done’. However, this chapter will cover the simpler case where the dates are added manually.
Click on a Feature and right-click on the “Details” tab and select “Edit view”. In the View section, press the Add button to create a simple field and name it Start Date. Click on the simple field and select the type DATETIME. Then add one more simple field, this type called End Date and also of type DATETIME.
Note that if you want to use an existing start date or end date field, you search (the magnifying glass icon in the upper right corner) the field by its name and drag and drop the field to the Feature’s details view.
Picture 19: what a timeline looks like
Using the start and end dates to add items to timeline
Now you can open up a few Features and add the start and end dates to them.
Finally, go back to the Product and do the familiar drill of editing the type and add a timeline view in the Views section. In Items, write the following formula:
Additionally, set the field Item Start and Item End to point to the Start Date and End Date fields. This is done by using the VAL formula.
Into the formula editor for the Start Date, write “VAL(“ and start writing Start Date. The editor should start giving suggestions on which field to use. The end result should look something like this:
Now do the same for the End Date!
Picture 20: Setting-up a timeline
The next covered in this tutorial is the list. It’s good for displaying an undetermined amount of information in a structured manner.
Let’s create a list view under Product for prioritizing the items that are in the phase “Next Up”. Once again, open the item you want to edit (like the Product), go to the three-dot menu, select edit type, and add a list view in the Views section. Add the following formula to the Items field (though without the quotes – the editor will add them when you accept a suggestion after writing a couple of characters of the item’s name):
NODE() ->> ”Product Context”:1234569 _| ISLINKED( R(“Feature
State has Feature”:12345674), ISITEM(“Next Up”:12345675) )
The formula expands from the original Product item by the context “Product Context” defined earlier in chapter “Contexts”. With the _| operator, Nektion flattens the graph into a one-dimensional list of items (instead of a tree-like hierarchy).
Next, the ISLINKED part checks whether the items are Features linked to a Feature State and whether the Feature State is “Next Up”.
Picture 21: list of epics
At this point, the list you’ve created is very simple as it only shows the icon and name of the items, but you can move the position of Features that are in the “Next Up” state by drag-and-dropping so that the most important one is highest on the list.
Also, adding extra fields into the list’s details view’s “Views” section causes them to be added as a column into the list. For example, dragging the End Date field would create a column for the Features’ End Dates (for more information, check the section “Adding existing start and end dates” in chapter “Timeline”)
The Time Series view displays a chart with changes of a given value plotted over time. For example, you could specify individual data points to represent the number of fixed issues.
Let’s create a simple time series that displays epics and features created. Start by creating an empty time series view the same way other views are created. In the details view of the view, you just created, there are the fields for “Chart start” and “Chart end”. In this case, you could write the following:
Chart start: NOW() - DAYS(// however many days you want)
Chart end: NOW()
Picture 22: Time Series view
Now you’ve defined the bounds of the time series. Next, let’s add a simple field under the view and give it the field type of “Formula”. For its expression, you could enter something like this:
COUNT( NODE()->>”Portfolio”:id )
This simply counts the items created and forms a chart based on their creation dates.
Picture 23: The start and end dates in the details view
Adding Item Fields
In chapter “Timeline”, you added start and end date fields to Feature. Now let’s add some more fields and also use them in views to make them more information-rich.
The simple field in Nektion is used for inputting different data (text, numbers, dates, and so on) as well to do calculations. We will go through the most common simple field types.
Boolean field type
The boolean field type shows as a tick box in the UI. An example use case for this if some of our Features are mandatory, we could add a boolean field type called Mandatory. The boolean field type is added the same way as the document field type: add a simple field to the Feature and select field type Boolean. You can also add the new boolean field to for example a list view.
The Integer field type is for adding integers (1, 2, …). If you want to be able to add decimals, select the Decimal field type.
Let’s add an integer field type called Story Points. The process is the same as for Boolean and Document field types – add the Story Point field to the Details view of the Story.
Formula field type
The formula field type is used for calculating different things. With the Nektion formula language you can do very diverse calculations such as calculating the time between events (e.g. status changed from “In Development” to “Done”), combining different text fields, or calculating how many tasks you have in a project.
Relation fields are used to select and display items, such as which state an item has.
If you have created all the views that we have gone through in this tutorial, you have also created items for Feature State and Story State. If not, we will set up a new view where you can create those items.
Let’s start with creating a relation widget to Feature. Open up a Feature and select Edit Type from the three-dot menu. Right-click on the details view, select add child, and then Relation Field. You can name the relation field to Feature State. Click open the relation field you created and in the Items field add the following type of formula:
NODE()<-”Feature State has Feature”:1234692
Note that the arrow goes from right to left as we want to traverse the relation from the Feature to the Feature State. If you had created the Feature States, you will now have them visible in the relation field.
A relation field can be made visually nicer by adding some colors to the options. If you right-click on the Feature Status relation field, you can select Edit Options. With Edit Options, you can arrange the order of the options, add a background color, add new options, and delete existing ones.
Document field type
The document field type is a field that opens a rich text editor when you click on it. This way, you can add some simple visual customization to the text contained within, making it easier to read a longer text.
Let’s add a description field to the item type Feature. To do that click open a Feature and select the Edit Type from the three-dot menu. Right-click on the Details view and select “add child” to add a document field. Name the field Description and then click it open. We can now add the Description field to the list view that was created (Priorities). To do that click on the list tab and select “Edit view”. If you still have the Feature type open, you can now drag and drop the Description field to the View section. The Description field helps potentially a lot to prioritize our Features.
Picture 24: Edit Options allows you set colors, manage the order, and add and delete options
Setting default values
Sometimes you want to set a default value for a field when an item of a certain type is created. For example, in our example, we might want every new Feature to have the Feature State set to New. In Nektion item creation works through a so-called template item that every item type has. When a new item of that type is created the template item is copied.
Default values are set by editing the field of the template item. Open a Feature and select Edit Type for the three-dot menu. You see the item type template in the field of the same name. By pressing ctrl and clicking on the template item, it will open to the right and can edit its fields.