Skip to main content

The app file

New in v13.2.0

Initial entities can be defined in the app file using InitialEntity objects.

The app file (, or app/ is the entry point for you application and defines all entity types by means of so-called Controllers, classes that inherit from ViktorController:

class BlueType(ViktorController):

class GreenType(ViktorController):

Click here for a complete overview of all required and optional controller attributes.

Importing controllers

If the entity type controllers are divided across multiple files, the controller classes should be imported in the app file:

from .blue_type.controller import BlueType      # defines entity type 'BlueType'
from .green_type.controller import GreenType # defines entity type 'GreenType'

Alternatively, if the class name itself does not equal the entity type name (e.g. Controller), you can import as an alias:

from .blue_type.controller import Controller as BlueType    # defines entity type 'BlueType'
from .green_type.controller import Controller as GreenType # defines entity type 'GreenType'

Initial entities

In addition to the entity type Controller(s), the initial entities can be specified in this file. These entities are initialized when the application is started:

from viktor import InitialEntity


initial_entities = [
InitialEntity("GreenType", name="A Green Entity", params=...),
InitialEntity("BlueType", name="A Blue Entity", params=...)

The initial entities, including their children, are applied on every start on your development workspace. On a production workspace, however, only the top level entities are applied the first time the workspace is created.

An InitialEntity is build up from the following inputs:

  • entity_type_name

    Refers to the class name of the entity type controller (or its alias), which should be accessible from the app file. In above example this would mean that VIKTOR expects at least controller imports named GreenType and BlueType.

  • name

    Name of the entity which will be shown in the VIKTOR interface.

  • params (optional)

    Parameters of the initial entity. If not defined, the default params will be set.

    Assume we have a parametrization with inputs width and length, the initial values can be set using a dictionary notation:

    InitialEntity(..., params={"width": 300, "length": 500})

    or by pointing to a .json file located relative to the app file:

    InitialEntity(..., params='initial_dimensions.json')

    with initial_dimensions.json:

    "width": 300,
    "length": 500
  • children (optional)

    List of children defined as InitialEntity objects. If not defined, no children will be added. Each child must be a valid child-type of its parent (i.e. the child-type must be defined as one of the children on the parent controller).

    InitialEntity("ParentType", ..., children=[
    InitialEntity("ChildType", ...),