Extending the App - Nautobot Design Builder Documentation

Skip to content

# Extending the App

Design builder is primarily extended by creating new action tags. These action tags can be provided by a design repository or they can be contributed to the upstream Design Builder project for consumption by the community. Upstreaming these extensions is welcome, however it is best to open an issue first, to ensure that a PR would be accepted and makes sense in terms of features and design.

## Action Tag Extensions

The action tags in Design Builder are provided by `design.Builder`. This component reads a design and then executes instructions that are specified in the design. Basic functions, provided out of the box, are `get`, `create`, `create_or_update` and `update`. These actions are self explanatory (for details on syntax see this document). Two additional actions are provided, these are the `ref` and `git_context` actions. These two actions are provided as extensions to the builder.

Extensions specify attribute and/or value actions to the object creator. Within a design template, these extensions can be used by specifying an exclamation point (!) followed by the extensions attribute or value tag. For instance, the `ref` extension implements both an attribute and a value extension. This extension can be used by specifying `!ref`. Extensions can add behavior to the object creator that is not supplied by the standard create and update actions.

### Attribute Extensions

Attribute extensions provide some functionality when specified as a YAMl attribute. For instance:

    devices:
        name: My New Device
        "!my_attribute_extension": "some data passed to the extensions"

In this case, when the object creator encountered `!my_attribute_extension` it will look for an extension that specifies an attribute_tag `my_attribute_extension` and will call the associated `attribute` method on that extension. The `attribute` method will be given the object that is being worked on (the device "My New Device" in this case) as well as the value assigned to the attribute (the string "some data ..." in this case). Values can be any supported YAML type including strings, dictionaries and lists. It is up to the extension to determine if the provided value is valid or not.

### Value Extensions

Value extensions can be used to assign a value to an attribute. For instance:

    device:
        name: "!device_name"

In this case, when `!device_name` is encountered the object creator will look for an extension that implements the `device_name` value tag. If found, the corresponding `value` method will be called on the extension. Whatever `value` returns will be assigned to the attribute (`name` in this case). For a concrete example of an extension that implements both `attribute` and `value` see the API docs for the ReferenceExtension.

### Writing a New Extension

Adding functionality to `design.Builder` is as simple extending the Extension class and supplying `attribute_tag` and/or `value_tag` class variables as well as the corresponding `attribute` and `value` instance methods. Extensions are singletons within a Builder instance. When an extension's tag is encountered an instance of the extension is created. Subsequent calls to the extension will use the instance created the first time.

Each extension may optionally implement `commit` or `roll_back` methods. The `commit` method is called once all of a design's objects have been created and updated in the database. Conversely, `roll_back` is called if any error occurs and the database transaction is aborted. These methods provide a means for an extension to perform additional work, or cleanup, based on the outcome of a design's database actions.