About PropertyDescriptor

Class nifiapi.properties.PropertyDescriptor

NiFi allows developers to define configurations for a Processor. This can be done by defining a set of PropertyDescriptors in the Processor.

Parameters:

Name	Type	Description
name	String	The name of the property
description	String	The description of the property
required	Boolean; Default False
sensitive	Boolean; Default False	Sensitive values will be hidden once entered
default_value	Mixed; Default None	A default value of the property
allowable_values	List; Default None	A list of possible values of the property
validators	List(StandardValidators); Default StandardValidators.ALWAYS_VALID	Define how to validate the format of the property value; See StandardValidators
expression_language_scope	ExpressionLanguageScope; Default ExpressionLanguageScope.NONE	Extend to which the usage of the EL is permitted; See ExpressionLanguageScope
dependencies	List(PropertyDependency); Default None	Conditionally display the property based on value of another; See PropertyDependency
resource_definition	ResourceDefinition; Default None	Define a type of external resource that processor interacts with; See ResourceDefinition
display_name	String; Default None	An alias of a property 'name' to be used in the NiFi UI, for new processors use 'name' instead of 'display_name'; See display_name
dynamic	Boolean; Default False	Define whether or not this Property Descriptor represents a dynamic property

e.g.:

from nifiapi.properties import PropertyDescriptor, StandardValidators


PROPERTY = PropertyDescriptor(
    name="Property A",
    description='''
    A longer text detailing what does this property describe.
    ''',
    required=False,
    sensitive=False,
    default_value=None,
    allowable_values=None,
    validators=[
        StandardValidators.NON_EMPTY_VALIDATOR
    ]
)

sensitive

You can toggle the visibility of a property in the NiFi UI, by adjusting a value of sensitive property.

Example of a sensitive property:

from nifiapi.properties import PropertyDescriptor, StandardValidators


API_TOKEN = PropertyDescriptor(
    name="API Token",
    description="A sensitive value",
    sensitive=True,
    validators=[StandardValidators.NON_EMPTY_VALIDATOR]
)

allowable_values

The allowable_values parameter of a PropertyDescriptor is used to define a set of predefined, valid options that a user can select from when configuring a property. Property value is expected to be a list of string representations of the valid options.

Example of a property with predefined set of options:

from nifiapi.properties import PropertyDescriptor


PROPERTY_A = PropertyDescriptor(
    name="Property A",
    required=True,
    allowable_values=[
        "Value A",
        "Value B",
        "Value C"
    ],
)

dependencies

The dependencies parameter of a PropertyDescriptor is used to define conditional relationships between properties. This parameter specifies that the value of one property depends on the value of another property. To establish relationships between properties pass a list of PropertyDependency as a value of dependencies parameter.

Example of a dependent property:

from nifiapi.properties import PropertyDescriptor, PropertyDependency


PROPERTY_A = PropertyDescriptor(
   name="Property A",
   description="Dropdown Property",
   required=True,
   allowable_values=[
       "Value A",
       "Value B",
       "Value C"
   ],
)

PROPERTY_B = PropertyDescriptor(
   name="Property B",
   description='''
   A conditional property, visible only when option "Value A"
   is selected for Property A.
   ''',
   dependencies=[
       PropertyDependency(PROPERTY_A, "Value A")
   ],
)

resource_definition

The resource_definition parameter of a PropertyDescriptor allows for defining and management of external resources that a processor interacts with. These may include files, directories or APIs. To define a type of a resource provide an instance of a ResourceDefinition class as a value of a resource_definition parameter.

Example of a file resource definition:

from nifiapi.properties import (
    PropertyDescriptor,
    ResourceDefinition
)

PROPERTY = PropertyDescriptor(
    name="Property A",
    description='''
    Property with Resource Definition.
    ''',
    required=True,
    resource_definition=ResourceDefinition(allow_file=True)
)

display_name

Once processor is added to NiFi processor repository, a key-value representation of its configuration is stored for each instance of the processor existing within a workflow. Sometimes a property name needs to be updated, but doing so will invalidate all existing configurations, and is therefore not advised. A good work around this issue is an addition of display_name property. This value will be used as a property label in the NiFi UI, concealing the original name, hence keeping it intact.

In practice, it means that the display_name attribute should not be used when initially defining a property descriptor.

Registering Properties

All custom property descriptors need to be registered using getPropertyDescriptors method.

from nifiapi.flowfiletransform import FlowFileTransform
from nifiapi.properties import PropertyDescriptor

from typing import List


class Processor(FlowFileTransform):
    (...)

    PROPERTY_A = PropertyDescriptor(
        name="Property A",
        description="An example Property A",
    )

    PROPERTY_B = PropertyDescriptor(
        name="Property B",
        description="An example Property B",
    )

    def getPropertyDescriptors(self) -> List[PropertyDescriptor]:
        '''
        Register PropertyDescriptors used by the Processor.

        Returns:
            list(PropertyDescriptor)
        '''
        return [
            self.PROPERTY_A,
            self.PROPERTY_B,
        ]

Accessing Property Value

The ProcessorContext instance supplied to the onSchedule, onStopped, and transform methods can be used to access the value of a property.

e.g.:

from nifiapi.flowfiletransform import (
    FlowFileTransform,
    FlowFileTransformResult,
    PropertyDescriptor,
    ExpressionLanguageScope
)
from nifiapi.properties import ProcessContext


class Processor(FlowFileTransform):
    PROPERTY_A = PropertyDescriptor(
        name="Property A",
        description="An example Property A",
    )

    PROPERTY_B = PropertyDescriptor(
        name="Property B",
        description="An example Property B",
        expression_language_scope=ExpressionLanguageScope.FLOWFILE_ATTRIBUTES,
    )

    (...)

    def __init__(self, *args, **kwargs):
        super().__init__()
        self.property_a = None

    def onScheduled(self, context: ProcessContext) -> None:
        '''
        Properties that can be evaluated without FlowFile attributes
        can be accessed in the 'onSchedule' method.

        Parameters:
            context (ProcessContext)

        Return:
            None
        '''
        self.property_a = context.getProperty(self.PROPERTY_A).getValue()

    def transform(
        self, context: ProcessContext, flow_file
    ) -> FlowFileTransformResult:
        '''
        Parameters:
            context (ProcessContext)
            flow_file

        Returns:
            FlowFileTransformResult
        '''
        # The value of 'Property B' can contain an Expression Language
        # referencing a FlowFile attribute and should therefore be evaluated
        # only in the 'transform' method.
        property_b = context.getProperty(self.PROPERTY_B)\
                            .evaluateAttributeExpressions(flow_file)\
                            .getValue()

        return FlowFileTransformResult("success")

Working with Property Values

Property evaluation is done by Java Framework and passed through Proxy to Python and due to limitation of that proxy received evaluations will be represented as strings. Further conversion will be necessary when working with values representing floats, integers and boolean.

The PythonPropertyValue class offers helper methods: asInteger, asBoolean, asFloat, asTimePeriod and asDataSize to handle the conversion.

Example of converting a Boolean property:

from nifiapi.properties import PropertyDescriptor, StandardValidators

BOOLEAN_PROPERTY = PropertyDescriptor(
    name="Boolean Value",
    description='''
    A test of a boolean validator.
    ''',
    validators=[StandardValidators.BOOLEAN_VALIDATOR],
)

# A conversion of a Boolean Property
value = context.getProperty(BOOLEAN_PROPERTY).asBoolean()